# UI primitives & design tokens

Shared building blocks for a cohesive, predictable UI. **Prefer these over ad-hoc
Tailwind class strings** — if you find yourself repeating a class combo, add/extend
a primitive here instead.

## Color tokens (defined in `src/index.css`, exposed in `tailwind.config.js`)

All colors are CSS variables so light/dark "just work". Use the Tailwind aliases,
never raw hex or `gray-*`.

| Token | Use for |
| --- | --- |
| `app-bg` | App/page background |
| `app-surface` | Cards, panels, sidebars, modals |
| `app-surface-muted` | Insets, secondary fills, code wells |
| `app-surface-hover` | Hover state for rows/controls |
| `app-elevated` | Popovers / floating menus |
| `app-selected` | **Active/selected** rows & bubbles — subtle, mostly-neutral |
| `app-border` / `app-border-strong` | Hairlines / stronger dividers |
| `app-text` / `app-muted` | Primary / secondary text |
| `brand` (+ `-strong`,`-text`,`-subtle`,`-button`,`-button-hover`) | **Primary accent (cyan).** Primary/user actions, focus rings, brand identity. `-button` is dark enough for white text. |
| `accent` (+ `-text`,`-subtle`) | **Secondary accent (indigo). Use sparingly:** secondary actions, the AI "working" state, occasional category accents. Never for primary CTAs. |
| `danger` / `success` / `warning` (+ `-text`, etc.) | Status |

Two-accent rule of thumb: **cyan = the user / primary action; indigo = AI/system &
secondary.** Keep indigo rare so it stays meaningful.

### Elevation & radius
- Shadows: `shadow-card`, `shadow-card-hover`, `shadow-composer`.
- Radius convention: controls `rounded-md`, cards/inputs `rounded-xl`, pills & avatars `rounded-full`.
- Motion: a global `prefers-reduced-motion` reset neutralizes animations/transitions.

## Primitives (`import { ... } from '../ui'`)

| Primitive | What it is |
| --- | --- |
| `Button` | `variant` (primary/secondary/ghost/danger/success) × `size` (sm/md/lg). Primary = `brand-button`. |
| `IconButton` | Square icon-only button; requires `label` (aria). |
| `MenuItem` / `menuItemClass` | Sidebar/menu/nav rows. `active` → `app-selected`. Use the class for `<a>`. |
| `Panel` | Bordered surface container (`muted` variant). |
| `ModalShell` | Modal frame (backdrop, header, scroll body, footer) — focus trap + Escape. |
| `SegmentedControl` | Compact tab/segment switch. |
| `StatusBadge` | Small pill, `tone` = neutral/brand/success/warning/danger. |
| `ToggleRow` | Labeled switch row (used in Permissions settings). |
| `Tooltip` | CSS hover/focus tooltip; inverts via tokens. |
| `Avatar` | User account chip (soft cyan→indigo gradient + initials, or image). |
| `BrandMark` | The canonical circular brand mark — home hero **and** message avatar. |