Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
description: "Components, styling, and interaction conventions." paths: - "/*.tsx" globs: "/*.tsx" alwaysApply: false
UI conventions
Components, styling, and interaction conventions.
- FE-22 Pending or permission-gated actions render as a dimmed version of the real UI with inline accept/reject controls — not a generic placeholder icon.
- FE-23 Disclosure carets rotate 180° to point down when expanded, matching Discussion, SplitFileMenu, CollapsibleMessage, etc.
- FE-24 Truncated/collapsed controls get a tooltip (matching the app's
tooltip pattern) so the lost label stays discoverable. Use shared tooltips or
popovers instead of native
title; give each target one hint surface. - FE-25 Semantic color tokens, not raw Tailwind palette classes — the
default palette is disabled via
--color-*: initialinapps/web/src/index.css, so classes liketext-red-500silently render nothing. Enforced by ast-greptsx-no-raw-tailwind-palette, CI error. Use existing semantic surface tokens instead of component-local color mixes. - Keep runtime theme tokens together in
apps/web/src/index.css: one:root, [data-theme-light]block for dark defaults, followed by one[data-theme-light='true']override block. Keep any narrower root/device conditions inside that theme area.@themeregisters Tailwind tokens; component utilities and layer/inversion rules keep their own responsibilities. Do not append separate border, Button, glass, or avatar theme blocks elsewhere. - FE-26 Prefer composition over configurability; keep reusable components small and free of queries/complex state. Prefer children or JSX slots over render props when the parent provides no data to the child.
- FE-27 Don't add
cursor-pointerto clickable elements. Enforced by ast-greptsx-no-cursor-pointer, warning. - FE-28 Dialogs rely on Kobalte's default autofocus: make the intended
target the first tabbable element and preserve focus ownership for
restoration. Override
onOpenAutoFocusonly for a proven lifecycle requirement, and verifydocument.activeElementafter both opening and reopening in the live app. - FE-30 Never hoist Tailwind class strings into named constants (
const DAY_CELL_CLASS = '...') — shared markup+styling is a component; a class string can't carry structure, props, or behavior. Extract a component, or inline the literal at its single use; styling variants are component props, not exported strings. Enforced by ast-greptsx-no-class-string-consts, warning. - FE-32 Prefer styling in the component (Tailwind on the markup). Reserve
@utilityinapps/web/src/index.cssfor styles widely shared across many components — not one-off or two-callsite layouts.
Components
- Place skeletons at the loaded content's position and dimensions; use the shared
Macro
LoadingSpinnerwhen that geometry is unknown. - Prefer composition over configurability. Follow slot-based patterns (see src/features/channel, src/features/entity, or Kobalte).
- Keep reusable components small, atomic, and decoupled from queries/complex state. Push data-fetching and mutations up to use-case-specific composed components.
- Context should be scoped to a component subtree — Message.Content consuming a MessageContext is fine because the ownership boundary is clear.
- Composed primitives must not depend on use-case-specific context — a RecipientsSelector should never require an EmailComposeContext.
- New features and feature restructures use the layered layout in
docs/architecture/frontend-features.md,
summarized by FE-33 (
core / queries / primitives / components / viewsplus an injectedcontext/). Keep production wiring in an app-facing entry point and give reactive logic narrow feature-owned contracts.src/features/activityillustrates the layers but still has documented composition and contract migration gaps. - FE-53 Use the shared components in
apps/web/src/components/ui(@ui) whenever one fits; browse them at/app/component/ui. Don't build a one-off button, dialog, menu, or input. A missing primitive is added there, with a*.docs.tsxpage and tests, not inside a feature. - Use
Dropdown.MultiSelectItemfor multiselect filter rows; keep independent checkbox settings onDropdown.CheckboxItem. Follow the shared interaction pattern. - FE-54 Decide mobile behavior deliberately. Unless the change makes it
obvious, ask the user how a UI change should look and behave on mobile, then
follow
mobile.md. - FE-55 UI tests drive real interactions (click, type, keyboard, focus)
through
@solidjs/testing-libraryand assert what the user sees or can do. No tests that only render and check classes, snapshot markup, or mock the component under test; cover full flows with browser tests.