Shared UI Design System

Use the primitives in src/shared/ui/ as the default way to build interface elements. Prefer extending these components over recreating their styling in feature code.

Core Rules

• Prefer shared UI primitives over custom markup plus Tailwind classes.
• Prefer adding a variant or prop to a shared component over one-off styling in feature code.
• Keep feature code focused on composition, state, and content. Visual treatment should usually live in src/shared/ui/.
• If a pattern appears in more than one place, extract or extend a shared primitive instead of copying class strings.

Button sizing rule

All buttons within a single surface zone must use the same size. Footer buttons in dialogs are the default Button size. Toolbar buttons are xs. Page-level actions are default. Never mix sizes within a footer, toolbar, or inline button group — if one button needs to be smaller, the whole group steps down together.

The button system is a closed menu. Every button in the app is one of these named things — never a custom-styled Button.

The semantic menu (Button variants)

Two flags modify variants:

• destructive — danger intent. Works on primary (red fill), outline (red border/text), subtle (red tinted fill), and ghost (red text + tint hover). Other variants ignore it and warn in dev.
• flush — ghost only. Inline geometry: no padding pill; rests at muted-foreground and raises the label on hover. For quiet actions that sit flush with surrounding content (list section actions, "show more").

Pick the emphasis first; if the action is dangerous, add destructive.

Chrome buttons (named wrappers)

Surface-specific recipes live in named components that compose Button. Use these instead of restyling Button for app chrome:

Each wrapper's recipe owns all of its interactive states; see the doc comment in its source for the full contract.

DisclosureButton takes a surface (default | sidebar | sidebarRow) because how quiet the rest state can afford to be depends on what the button sits on. default inherits the system ghost + flush states and is correct on tinted raised surfaces like the chat user bubble; the sidebar* surfaces dim to muted-foreground/75, which is only legible against the page background. Do not use a sidebar* surface on a tinted surface.

The rule (audited in CI)

Feature code never puts color or interactive-state classes (bg-*, text-foreground/text-muted-foreground/..., hover:*, active:*, shadow-*, opacity-*) on a <Button>. Layout-only classes (ml-auto, w-full, justify-start, shrink-0, truncation) are fine. If no variant, flag, or wrapper fits, that is a design-system conversation — extend the menu, don't restyle locally. pnpm design-system:audit enforces this and fails on new violations.

General guidance

• Use Button for clickable controls unless there is a strong reason not to.
• Use variant and size before adding custom classes.
• Use leftIcon and rightIcon for leading and trailing icons instead of manually placing icon children.
• Do not add spacing classes only to position button icons unless the design system cannot express the pattern yet.
• For icon-only actions, use the icon-* sizes instead of text button sizes.
• For active icon-only buttons, prefer native hover via title plus aria-label.
• Reserve custom Tooltip for disabled controls or richer explanatory content.
• Use Button for async action feedback too. Prefer its feedbackState, loadingLabel, successLabel, errorLabel, loadingVisual, and preserveWidth props over creating a separate async button wrapper or hand-placing spinners in feature code.
• When combining async feedback with asChild, keep the visible label inside the slotted child so Button can swap it with loading, success, or error feedback.

Ghost icon buttons

variant="ghost" has compound variants for all icon-* sizes that set hover:bg-transparent hover:text-foreground. This means ghost icon buttons have no background fill on hover — only a color change. Do not add hover:bg-accent/50 or similar hover background classes to ghost icon buttons; the compound variant already provides the correct behavior. Layout classes like mr-1, size-6, flex-shrink-0 are fine to add.

Icon Sizing

• Let Button size button icons by default.
• Current button icon defaults are tied to button size:
• xs and sm buttons use size-3 icons.
• default buttons use size-3.5 icons.
• lg buttons use size-4 icons.
• Only give an icon its own explicit size-* class when intentionally overriding the design-system default.
• Match icon visual weight to the text and control size. Small toolbar controls should not use oversized icons.

Dialogs

There is one modal surface: Dialog. Do not create new dialog chrome components; compose the anatomy the use case needs.

• DialogContent owns the glass surface, close button, and width via the size prop (md | lg | xl). Do not pass ad-hoc max-w-* classes.
• Simple dialogs: DialogHeader + content + DialogFooter. Everything scrolls together.
• Content-heavy dialogs (forms, pickers, lists): wrap the middle in DialogBody. Its presence automatically pins the header and footer, moves padding to the zones, and gives the footer its top divider. Use DialogBody asChild with a <form> child when the body is a single form.
• All dialog actions live in DialogFooter and use Button directly. Do not create wrapper buttons for back/save/delete. Back is just <Button variant="ghost" flush className="sm:mr-auto" />. Submit/save buttons use default Button size in the footer; if the body is a form, submit with <Button form={formId} type="submit">.
• Semantic variants are the only other dialog components: AlertDialog (interruptive, no light-dismiss), ConfirmDialog (yes/no preset), and CommandDialog (search-first palette). Never fork a new one for content density — density is size + DialogBody, not a new component.
• Name feature dialogs *Dialog, not *Modal.
• List rows inside dialogs and settings use RowButton (menu variant for borderless option rows, field for bordered input-like triggers) instead of raw <button> + hand-rolled classes. Hover states come from the primitive (bg-muted); do not use washed-out one-offs like hover:bg-accent/30.

Menus And Selectors

• Compose menus from DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, and related shared primitives.
• When a trigger behaves like a button, use Button as the trigger surface.
• Repeated trigger patterns like icon + label + chevron should be expressed through shared props or shared wrapper components.

Styling Boundaries

• Avoid introducing custom colors, spacing, radii, or typography in feature code when existing tokens and shared variants cover the need.
• If a control needs a new visual treatment, add it to the shared component API first.
• Keep accessibility built in: semantic elements, labels for icon-only buttons, and consistent focus states.

Good Heuristic

Before writing custom classes in a feature, ask:

1. Can an existing shared component already do this?
2. Should this become a shared variant or prop?
3. Will another screen likely need the same pattern?