@tailor-platform/app-shell 1.11.0 → 1.13.0

package/skills/app-shell-patterns/references/fundamental/design-system.md

@@ -1,127 +1,176 @@
 # Design System
 
-Authority for **visual-only** decisions — tokens, theme imports, breakpoints intent, `**astw:`** rules, and custom-component conformance. For **React component APIs** (imports, props, JSX composition), pair this file with `**components.md`\*\*; that split avoids duplicating tables and lengthy examples across both docs.
+Authority for **visual-only** decisions — tokens, theme imports, breakpoints intent, the `astw:` prefix, and custom-component conformance. For **React component APIs** (imports, props, JSX composition), pair this file with `components.md`; that split avoids duplicating tables and lengthy examples across both docs.
 
-`@tailor-platform/app-shell` (ERP scaffolds target **≥0.36**; bump your app’s pinned version deliberately) ships an opinionated design system via CSS variables and a `theme.css` import. Use it whether you are consuming AppShell components (most cases) or building a custom component to fill a gap.
+`@tailor-platform/app-shell` ships an opinionated design system as CSS variables, bridged into Tailwind v4's token namespace. Use it whether you are consuming AppShell components (most cases) or building a custom component to fill a gap.
 
-**The tokens are the rails.** Consistency across customers, apps, and AI runs comes from the token system, not from rules written in prose. A hand-typed `#fff` or `padding: 13px` is not a "small deviation" — it is the mechanism by which consistency dies. Every visual value you reach for must resolve to a token in this file. If a token is missing, add one; never inline.
+**The tokens are the rails.** Consistency across customers, apps, and AI runs comes from the token system, not from rules written in prose. A hand-typed `#fff` or `padding: 13px` is not a "small deviation" — it is the mechanism by which consistency dies.
+
+**Every token in this file is verified against the shipped CSS.** If a token is not listed here, assume it does not exist. Inventing a plausible-sounding token (`bg-surface-1`, `text-fg-muted`, `--space-4`) is the worst failure mode available to you: Tailwind emits **no CSS at all** for an unknown utility, so the class is silently dropped and the element renders unstyled. There is no error, no warning, and nothing in the console. When unsure, read `node_modules/@tailor-platform/app-shell/dist/themes/default.css` — it is the ground truth.
 
 ## 1. Setup
 
-Authoritative app wiring also lives in `**project-setup.md`**; **scaffold `index.css`\*\* currently does:
+The app's CSS entrypoint (`index.css` / `globals.css`) needs exactly this:
 
 ```css
 @import "tailwindcss";
-@import "tw-animate-css";
-
 @import "@tailor-platform/app-shell/styles";
-@import "@tailor-platform/app-shell/theme.css";
-```
 
-Adjust if your App Shell version documents a different barrel filename, but keep this split:
+/* Optional: at most one palette override, imported AFTER styles */
+@import "@tailor-platform/app-shell/themes/bloom";
+```
 
-- `**theme.css**` — design tokens as CSS variables on `:root`.
-- `**styles**` (package export) — bundled component styles AppShell ships for primitives.
-- `**tailwindcss**` — utilities; token-backed classes (`bg-surface-1`, `text-fg-muted`) resolve through the theme.
+- **`tailwindcss`** — your app's own Tailwind build, which generates the utilities you write in your components.
+- **`@tailor-platform/app-shell/styles`** — the single required import. It pulls in both the design tokens (the `@theme inline` bridge, so `bg-background` / `text-muted-foreground` resolve in _your_ Tailwind build) and AppShell's precompiled component CSS.
+- **`@tailor-platform/app-shell/themes/*`** — optional palette overrides (`default`, `cream`, `bloom`). Import at most one, after `styles`. Palette selection is by CSS import; there is no runtime palette prop.
 
-Older docs referred to `app-shell.css`; prefer the `**styles**` import the template uses.
+**Do not import `@tailor-platform/app-shell/theme.css`.** That export is a deprecated no-op shim, kept only so older apps keep building. It emits nothing. Older docs also referred to `app-shell.css`; prefer `styles`.
 
-Tailwind v4 stays CSS-first; minimal `vite` / PostCSS wiring is in `**project-setup.md**`.
+Tailwind v4 stays CSS-first; minimal `vite` / PostCSS wiring is in `project-setup.md`.
 
 ## 2. Theming via CSS variables
 
-AppShell controls its theme through CSS variables. Override them in `:root` (global) or a scoped selector (per-section, per-tenant, dark mode) to customize. Any token defined in `theme.css` can be overridden after the import.
+Tokens exist in two layers, and knowing which one you are touching matters:
+
+1. **Raw CSS variables** (`--background`, `--primary`, `--radius`) — defined on `:root` in `themes/*.css`. These are what you **override**.
+2. **The Tailwind bridge** (`@theme inline` in `theme.bridge.css`) — maps each raw variable into Tailwind's namespace (`--background` → `--color-background`), which is what makes `bg-background` a real utility. You do **not** edit this layer.
+
+Override raw variables after the `styles` import, using `:root` for light and `:root.dark` for dark. Set every override in both modes — overriding just `:root` misbehaves either way: on the default palette the light value carries into dark mode, and on a branded palette the override stops applying in dark mode altogether.
 
 ```css
 :root {
-  --color-primary: #3b82f6;
-  --color-background: #ffffff;
+  --primary: #3b82f6;
 }
 
-[data-theme="dark"] {
-  --color-background: #0a0a0a;
-  --color-foreground: #fafafa;
+:root.dark {
+  --primary: #60a5fa;
 }
 ```
 
-Override at the highest scope where the change applies. Do not duplicate token values across files — change them at the source.
+Use `:root.dark`, not a bare `.dark`. The default palette is imported inside a cascade layer (`layer(theme.defaults)`), so any unlayered declaration of yours beats it — but the branded palettes (`cream`, `bloom`) are imported unlayered and define their dark values on `:root.dark`, which outranks `.dark`. A `.dark` override would silently lose against those.
+
+Override at the highest scope where the change applies. A narrower scope (per-section, per-tenant) needs the same both-modes treatment, and its dark rule must still outrank a branded palette's `:root.dark` — pair `.tenant-a` with `:root.dark .tenant-a`. Do not duplicate token values across files — change them at the source. Never copy the palette wholesale; tokens you did not copy stay on AppShell's values, so the two halves drift apart and any surface AppShell adds later has no value in the copy at all.
 
-**Dark mode** is supported via `[data-theme="dark"]` on the root element. AppShell primitives respect it automatically. Custom components inherit dark-mode behaviour for free as long as they reference tokens (`bg-surface-1`, `text-fg-default`) and never inline literal colors.
+**Do not paste a `@theme inline` block, a `@custom-variant dark` rule, or a copy of AppShell's palette into the app's entry CSS.** `styles` provides all three. A copy of any of them in the app's own CSS is unlayered, so it beats AppShell's layered palette and silently breaks dark mode — the build succeeds and nothing warns.
+
+**Dark mode is a `.dark` class on `<html>`**, not a data attribute. AppShell's theme provider toggles `document.documentElement.classList` between `light` and `dark` and persists the choice under the `appshell-ui-theme` localStorage key; the bundled `AppearanceSwitcher` component drives it. The bridge registers `@custom-variant dark (&:where(.dark, .dark *))`, so the `dark:` variant works in your own markup.
+
+AppShell primitives respond to dark mode automatically. Custom components inherit it for free as long as they reference tokens (`bg-card`, `text-muted-foreground`) and never inline literal colors.
 
 ## 3. Component styling with data attributes
 
-AppShell's UI components support data-attribute-based styling, following the [Base UI data attributes](https://base-ui.com/react/handbook/styling#data-attributes) convention. Components expose `data-`\* attributes that reflect their internal state, enabling CSS-only style control without JavaScript:
+AppShell's UI components support data-attribute-based styling, following the [Base UI data attributes](https://base-ui.com/react/handbook/styling#data-attributes) convention. Components expose `data-*` attributes that reflect their internal state, enabling CSS-only style control without JavaScript:
 
 ```css
 /* Style a component based on its state */
 .SwitchThumb[data-checked] {
-  background-color: green;
+  background-color: var(--status-completed);
 }
 
 .MenuItem[data-highlighted] {
-  background-color: var(--color-primary);
-  color: white;
+  background-color: var(--accent);
+  color: var(--accent-foreground);
 }
 ```
 
 This works with Tailwind as well — **use theme tokens**, not raw Tailwind grays:
 
 ```tsx
-<Switch.Thumb className="bg-surface-3 data-[checked]:bg-primary" />
+<Switch.Thumb className="bg-muted data-[checked]:bg-primary" />
 ```
 
 Check each component's API reference (`components.md`) for the data attributes it exposes. Custom components must follow the same convention (see Section 6).
 
 ## 4. Tokens
 
-All values below are exposed by `theme.css`. **Use the token, never hand-type the value.** A hex literal or magic px in a PR is a review failure.
+Everything below is verified present in the shipped CSS. **Use the token, never hand-type the value.** A hex literal or magic px in a PR is a review failure.
 
 ### Color
 
-Four families. Pick by **intent**, not by visual taste.
-
-| Family     | Token                    | Use                                 | Tailwind                      |
-| ---------- | ------------------------ | ----------------------------------- | ----------------------------- |
-| Surface    | `--color-surface-1`      | page background                     | `bg-surface-1`                |
-| Surface    | `--color-surface-2`      | card on page                        | `bg-surface-2`                |
-| Surface    | `--color-surface-3`      | nested card on card                 | `bg-surface-3`                |
-| Foreground | `--color-fg-default`     | primary text                        | `text-fg-default`             |
-| Foreground | `--color-fg-muted`       | secondary text, descriptions        | `text-fg-muted`               |
-| Foreground | `--color-fg-subtle`      | tertiary text, captions, timestamps | `text-fg-subtle`              |
-| Brand      | `--color-primary`        | primary buttons, links, focus rings | `bg-primary` / `text-primary` |
-| Brand      | `--color-primary-hover`  | brand hover state                   | `hover:bg-primary-hover`      |
-| Brand      | `--color-primary-active` | brand pressed state                 | `active:bg-primary-active`    |
-| Status     | `--color-danger`         | destructive actions, errors         | `bg-danger` / `text-danger`   |
-| Status     | `--color-warning`        | non-blocking caution                | `bg-warning` / `text-warning` |
-| Status     | `--color-success`        | confirmations, completed states     | `bg-success` / `text-success` |
-| Status     | `--color-info`           | neutral callouts                    | `bg-info` / `text-info`       |
+Colors follow shadcn-style semantic naming: a surface token and its matching `-foreground` pair. Pick by **intent**, not by visual taste. Pair a background with its own foreground — `bg-card` goes with `text-card-foreground`.
+
+#### Surface & chrome
+
+| Token                                | Use                           | Tailwind                                 |
+| ------------------------------------ | ----------------------------- | ---------------------------------------- |
+| `--background` / `--foreground`      | page background, default text | `bg-background` / `text-foreground`      |
+| `--card` / `--card-foreground`       | card and panel surfaces       | `bg-card` / `text-card-foreground`       |
+| `--popover` / `--popover-foreground` | menus, popovers, tooltips     | `bg-popover` / `text-popover-foreground` |
+| `--muted` / `--muted-foreground`     | subtle fills; secondary text  | `bg-muted` / `text-muted-foreground`     |
+| `--border`                           | hairlines, dividers           | `border-border`                          |
+| `--input`                            | form control borders          | `border-input`                           |
+| `--ring`                             | focus rings                   | `ring-ring` / `outline-ring`             |
+
+Surfaces are named by **role**, not by depth — there is no numbered `surface-1/2/3` ladder, and no third tier of body text below `muted-foreground`. Stack depth with `background` → `card` → `muted` plus a border or shadow, and reach for `popover` when the surface actually floats.
+
+#### Brand & action
+
+| Token                                        | Use                              | Tailwind                                     |
+| -------------------------------------------- | -------------------------------- | -------------------------------------------- |
+| `--primary` / `--primary-foreground`         | primary buttons, emphasis        | `bg-primary` / `text-primary-foreground`     |
+| `--secondary` / `--secondary-foreground`     | secondary buttons, neutral chips | `bg-secondary` / `text-secondary-foreground` |
+| `--accent` / `--accent-foreground`           | hover and selected nav states    | `bg-accent` / `text-accent-foreground`       |
+| `--destructive` / `--destructive-foreground` | destructive actions, errors      | `bg-destructive` / `text-destructive`        |
+
+There are no `-hover` or `-active` brand tokens. Express interaction states with Tailwind variants and opacity — `hover:bg-primary/90`, `active:bg-primary/80` — which is what AppShell's own components do.
+
+#### Status
+
+Five status colors, used for badge fills and status dots:
+
+| Token                | Use                      | Tailwind              |
+| -------------------- | ------------------------ | --------------------- |
+| `--status-default`   | none / not applicable    | `bg-status-default`   |
+| `--status-neutral`   | informational            | `bg-status-neutral`   |
+| `--status-completed` | success, completed       | `bg-status-completed` |
+| `--status-attention` | warning, needs attention | `bg-status-attention` |
+| `--status-danger`    | error, blocked           | `bg-status-danger`    |
+
+Prefer `Badge` with a semantic variant (`success`, `warning`, `error`, `info`, `neutral`) over applying these directly — the variants already pair fill and foreground correctly. Reach for the raw token only on custom surfaces.
+
+#### Sidebar & charts
+
+`--sidebar`, `--sidebar-foreground`, `--sidebar-border`, `--sidebar-primary(-foreground)`, `--sidebar-accent(-foreground)`, `--sidebar-ring` → `bg-sidebar`, `text-sidebar-foreground`, and so on. These let a palette tint the shell independently of page content.
+
+`--chart-1` … `--chart-5` → `bg-chart-1`, `text-chart-1`, `fill-chart-1`. Use them in order for categorical series.
+
+#### Alerts
+
+`--alert-{neutral,success,warning,error,info}-{background,foreground,foreground-muted,border}` — five variants × four slots, each bridged into Tailwind:
+
+| Slot               | Tailwind                           | Use for                    |
+| ------------------ | ---------------------------------- | -------------------------- |
+| `background`       | `bg-alert-info-background`         | Callout fill               |
+| `foreground`       | `text-alert-info-foreground`       | Primary text and icons     |
+| `foreground-muted` | `text-alert-info-foreground-muted` | Secondary/description text |
+| `border`           | `border-alert-info-border`         | Callout border             |
+
+Prefer the `Alert` component — it already pairs the four slots per variant and supplies the icon. Reach for the utilities directly only on custom surfaces `Alert` doesn't cover, such as a status-highlighted table row or an inline note:
 
 ```tsx
-// Good — Button exposes a destructive variant; prefer variants over bolting tokens on className when available
-<div className="bg-surface-1 text-fg-default">…</div>
+<div className="rounded-lg border bg-alert-warning-background text-alert-warning-foreground border-alert-warning-border">
+  …
+</div>
+```
+
+The `background` and `border` slots are already semi-transparent tints (~10% and ~20%), so an opacity modifier compounds rather than replaces — `bg-alert-info-background/50` lands near 5% alpha, not 50%.
+
+```tsx
+// Good — semantic token pairs, and a variant where one exists
+<div className="bg-card text-card-foreground">…</div>
 <Button variant="destructive">Delete</Button>
+<Badge variant="warning">Pending review</Badge>
 
 // Bad — raw colors bypass the theme
 <div style={{ background: "#fff", color: "#111" }}>…</div>
-```
 
-Never reach for raw color names. If a status doesn't fit, that's a content problem, not a token problem.
+// Bad — these classes do not exist and render as nothing at all
+<div className="bg-surface-1 text-fg-muted">…</div>
+```
 
 ### Spacing
 
-Linear scale on a 4px base. Padding, margin, and gap all come from this scale. Tailwind's `p-4`, `gap-2`, `mt-8` resolve to the same tokens.
-
-| Token        | Value | Common use                |
-| ------------ | ----- | ------------------------- |
-| `--space-0`  | 0     | reset                     |
-| `--space-1`  | 4px   | tight icon-text gap       |
-| `--space-2`  | 8px   | inline gap, small padding |
-| `--space-3`  | 12px  | row gap, button padding   |
-| `--space-4`  | 16px  | card padding, default gap |
-| `--space-6`  | 24px  | section gap               |
-| `--space-8`  | 32px  | major section gap         |
-| `--space-12` | 48px  | page section break        |
-| `--space-16` | 64px  | hero spacing              |
+**AppShell defines no spacing tokens.** Use Tailwind's default 4px-based scale (`p-4`, `gap-2`, `mt-8`) — the same scale AppShell's own components use internally. There is no `--space-*` variable.
 
 ```tsx
 // Good — scale step
@@ -135,106 +184,112 @@ Hand-typing `padding: 13px` is a smell. Round to the nearest scale step; if noth
 
 ### Typography
 
-Named roles. Each token bundles font-size + line-height + weight. Pick by **role**, not by size. Don't set `font-size` and `line-height` independently.
-
-| Token     | Tailwind       | Use                          |
-| --------- | -------------- | ---------------------------- |
-| `display` | `text-display` | hero / marketing surfaces    |
-| `h1`      | `text-h1`      | page title                   |
-| `h2`      | `text-h2`      | section heading              |
-| `h3`      | `text-h3`      | subsection / card title      |
-| `h4`      | `text-h4`      | nested heading               |
-| `body-lg` | `text-body-lg` | emphasised body              |
-| `body`    | `text-body`    | default body copy            |
-| `body-sm` | `text-body-sm` | dense rows, secondary copy   |
-| `caption` | `text-caption` | timestamps, labels, metadata |
-| `mono`    | `text-mono`    | IDs, code, numbers in tables |
+**AppShell defines no typography scale tokens.** There is no `text-h1`, `text-body`, or `text-caption`. The only typography token is `--font-sans` (Inter Variable for Latin, Noto Sans JP Variable for Japanese) → `font-sans`, which the base layer already applies to `body`. Both are variable fonts, so every weight token is real in both scripts. Override the whole stack by setting `--app-shell-font-sans` on `:root`.
+
+Compose roles from stock Tailwind utilities. These pairings are what AppShell's own components use — match them so your screens sit consistently alongside the primitives:
+
+| Role                              | Utilities                                 |
+| --------------------------------- | ----------------------------------------- |
+| Page title (`Layout.Header`)      | `text-2xl font-bold tracking-tight`       |
+| Section heading                   | `text-lg font-semibold`                   |
+| Card title                        | `text-lg font-semibold leading-none`      |
+| Body copy                         | `text-sm`                                 |
+| Secondary copy, descriptions      | `text-sm text-muted-foreground`           |
+| Caption, timestamp, metadata      | `text-xs text-muted-foreground`           |
+| Numeric value in a table or field | `text-sm font-medium tabular-nums`        |
+| ID, code, keyboard hint           | `font-mono text-xs text-muted-foreground` |
 
 ```tsx
-<h2 className="text-h2">Section</h2>
-<p className="text-body text-fg-muted">Description copy</p>
-<span className="text-caption text-fg-subtle">Updated 2h ago</span>
+<h2 className="text-lg font-semibold">Section</h2>
+<p className="text-sm text-muted-foreground">Description copy</p>
+<span className="text-xs text-muted-foreground">Updated 2h ago</span>
 ```
 
+Always use `tabular-nums` for numbers that stack in a column — without it, digits jitter between rows.
+
 ### Radius
 
-Pick by component role. A card is always `md`, regardless of its size on screen.
+`--radius` (`0.625rem`) is the base; the bridge derives four steps from it. Pick by component role — a card is always `md`, regardless of its size on screen.
 
-| Token           | Use                 |
-| --------------- | ------------------- |
-| `--radius-sm`   | inputs, small chips |
-| `--radius-md`   | cards, buttons      |
-| `--radius-lg`   | modals, sheets      |
-| `--radius-xl`   | large surfaces      |
-| `--radius-full` | pills, avatars      |
+| Token         | Value          | Use                 | Tailwind     |
+| ------------- | -------------- | ------------------- | ------------ |
+| `--radius-sm` | `radius − 4px` | inputs, small chips | `rounded-sm` |
+| `--radius-md` | `radius − 2px` | buttons, cards      | `rounded-md` |
+| `--radius-lg` | `radius`       | modals, sheets      | `rounded-lg` |
+| `--radius-xl` | `radius + 4px` | large surfaces      | `rounded-xl` |
 
-### Elevation
+`rounded-full` (pills, avatars) is a stock Tailwind utility — there is no `--radius-full` token, but the class works.
 
-Higher elevation reads as "more transient" — match the component's lifetime. Never hand-craft a `box-shadow`.
+Changing `--radius` alone rescales all four steps together.
 
-| Token           | Use                      |
-| --------------- | ------------------------ |
-| `--elevation-0` | flat surface             |
-| `--elevation-1` | persistent panel, card   |
-| `--elevation-2` | sticky bar, hovered card |
-| `--elevation-3` | popover, menu            |
-| `--elevation-4` | modal, dialog, sheet     |
+### Shadow
 
-### Motion
+Four mode-aware shadows. There are **no `--elevation-*` tokens**; the scale is expressed as shadows. Never hand-craft a `box-shadow`.
 
-Duration paired with easing. Match motion to the change's lifetime — short events get short durations.
+| Token                  | Bridged to  | Use                               |
+| ---------------------- | ----------- | --------------------------------- |
+| `--semantic-shadow-xs` | `shadow-xs` | hairline lift, active nav item    |
+| `--semantic-shadow-sm` | `shadow-sm` | cards, persistent panels          |
+| `--semantic-shadow-md` | `shadow-md` | popovers, menus, hovered surfaces |
+| `--semantic-shadow-lg` | `shadow-lg` | modals, dialogs, sheets           |
 
-| Token             | ~Duration | Use                            |
-| ----------------- | --------- | ------------------------------ |
-| `--motion-fast`   | 120ms     | hover, focus, button press     |
-| `--motion-base`   | 200ms     | state changes (toggle, select) |
-| `--motion-slow`   | 320ms     | entrance, dialog open          |
-| `--motion-slower` | 500ms     | full-page transitions          |
-| `--ease-out`      | —         | entrances, reveals             |
-| `--ease-in-out`   | —         | symmetric state changes        |
+Higher shadow reads as "more transient" — match it to the component's lifetime. Each token carries a different value in dark mode, so using the token (rather than a literal) is what keeps depth legible on both backgrounds.
 
-```css
-.menu-item {
-  transition: background-color var(--motion-fast) var(--ease-out);
-}
+### Motion
 
-@media (prefers-reduced-motion: reduce) {
-  .menu-item {
-    transition: none;
-  }
-}
+**AppShell defines no motion tokens.** There is no `--motion-fast` or `--ease-out` variable. Use Tailwind's `duration-*` and `ease-*` utilities. AppShell uses `tw-animate-css` internally for its own enter/exit animations, but those classes are prefixed and are not available to your app — add `@import "tw-animate-css";` to your own entrypoint if you want them.
+
+| Intent                        | Utilities                  |
+| ----------------------------- | -------------------------- |
+| Hover, focus, button press    | `duration-150 ease-out`    |
+| State change (toggle, select) | `duration-200 ease-in-out` |
+| Entrance, dialog open         | `duration-300 ease-out`    |
+
+```tsx
+<div className="transition-colors duration-150 ease-out motion-reduce:transition-none" />
 ```
 
-Always wrap motion in `@media (prefers-reduced-motion: reduce)` and collapse to instant or near-instant transitions. AppShell components handle this internally; custom components must do the same.
+Always give motion a reduced-motion escape (`motion-reduce:transition-none`, or a `@media (prefers-reduced-motion: reduce)` block in CSS). AppShell components handle this internally; custom components must do the same.
 
 ### Z-index
 
-Never invent a z value. If you need a new layer, add a token; never `z-index: 9999`. Popups and overlays share `50` intentionally — sequencing comes from DOM order, not z escalation.
+These exist as raw `:root` variables in the shipped base layer, but are **not** bridged into Tailwind — `z-sidebar` is not a class. Use the stock numeric utility, or reference the variable when you need it to track AppShell's layering:
 
 | Token              | Value | Use                           |
 | ------------------ | ----- | ----------------------------- |
 | `--z-sidebar`      | 10    | persistent sidebar            |
-| `--z-sidebar-rail` | 10    | sidebar collapsed rail        |
+| `--z-sidebar-rail` | 20    | sidebar collapsed rail        |
 | `--z-popup`        | 50    | menu, tooltip, popover        |
 | `--z-overlay`      | 50    | modal, sheet, dialog backdrop |
 
-### Icon sizes
+```tsx
+<div className="z-50" />
+<div className="z-[var(--z-popup)]" />
+```
+
+Never invent a z value — `z-index: 9999` is always wrong. Popups and overlays share `50` intentionally: sequencing comes from DOM order, not z escalation.
 
-Pair icon size with the surrounding text scale. Pass via the `size` prop, not raw width/height.
+### Icons
 
-| Token       | Pairs with text       |
-| ----------- | --------------------- |
-| `--icon-sm` | `body-sm`, `caption`  |
-| `--icon-md` | `body`, `body-lg`     |
-| `--icon-lg` | `h3`, `h4`            |
-| `--icon-xl` | `h1`, `h2`, `display` |
+**AppShell exports no `Icon` component and defines no `--icon-*` tokens.** Icons come from [`lucide-react`](https://lucide.dev), which AppShell already depends on. Size them with Tailwind, pairing icon size to the adjacent text:
+
+| Text size          | Icon class |
+| ------------------ | ---------- |
+| `text-xs`          | `size-3`   |
+| `text-sm`          | `size-4`   |
+| `text-lg`          | `size-5`   |
+| `text-2xl` (title) | `size-6`   |
 
 ```tsx
-<Icon name="check" size="md" />
+import { Check } from "lucide-react";
+
+<Check className="size-4" />;
 ```
 
 ### Breakpoints
 
+Stock Tailwind breakpoints — AppShell does not change them.
+
 | Token | Width  |
 | ----- | ------ |
 | `sm`  | 640px  |
@@ -245,26 +300,25 @@ Pair icon size with the surrounding text scale. Pass via the `size` prop, not ra
 
 **ERP target is `xl`/`2xl` desktop.** Pages should be designed for those widths first; smaller breakpoints exist for graceful degradation, not parity. Don't waste effort on mobile-first composition unless a screen explicitly calls for it. A list page that collapses gracefully at `md` is fine; a list page redesigned for `sm` is over-investment.
 
-Two-column **behavior** (right rail stacks under `**lg`**): respect AppShell defaults — do not force side-by-side grids on narrow viewports. `**Layout`column width table** numbers live in`**components.md` → Layout**; reuse them instead of guessing rem values here.
+Two-column **behavior** (right rail stacks under `lg`): respect AppShell defaults — do not force side-by-side grids on narrow viewports. The `Layout` column width table lives in `components.md` → Layout; reuse those numbers instead of guessing rem values here.
 
 ## 5. The `astw:` prefix
 
-AppShell exposes **layout / sizing / overflow** escapes on some components via props like `containerClassName`, `contentClassName`, `className` on roots. Prefix those utilities with `**astw:`\*\* so they apply to the wrapper AppShell controls.
+AppShell exposes **layout / sizing / overflow** escapes on some components via props like `containerClassName` and `className` on roots. Prefix those utilities with `astw:` so they apply to the wrapper AppShell controls.
 
-**Do not duplicate full component trees here.** Typical patterns (full `**DataTable`** composition, `**Sheet`+ footer**,`**Table.Root` + card insets**) live in `**components.md`\*\* with JSX you can copy.
+**Do not duplicate full component trees here.** Typical patterns (full `DataTable` composition, `Sheet` + footer, `Table.Root` + card insets) live in `components.md` with JSX you can copy.
 
-Minimal illustrations — same rules apply to other `*ClassName` hooks:
+Minimal illustration — the same rules apply to other `*ClassName` hooks:
 
 ```tsx
-<Table.Root containerClassName="astw:px-6 astw:max-h-96 astw:overflow-y-auto" />
-<Sheet contentClassName="astw:w-[480px] astw:flex astw:flex-col astw:gap-4" />
+<Table.Root containerClassName="astw:px-6 astw:overflow-y-auto" />
 ```
 
 Rules:
 
-- `**astw:**` only on AppShell `*ClassName` / root `className` hooks each component exposes. Use **plain** Tailwind (`flex`, `gap-4`, `bg-surface-1`, …) on **your** markup.
+- `astw:` only on AppShell `*ClassName` / root `className` hooks each component exposes. Use **plain** Tailwind (`flex`, `gap-4`, `bg-background`, …) on **your** markup.
 - Stick to **layout** utilities (`flex`, `grid`, `max-h-*`, `min-h-0`, `overflow-*`, widths). Avoid painting over internal AppShell padding or colors via `astw:` — prefer an upstream prop or composition change.
-- Steps like `**astw:p-4`\*\* still resolve through tokens — never arbitrary `astw:p-[13px]`.
+- Steps like `astw:p-4` still resolve through the scale — never arbitrary `astw:p-[13px]`.
 
 ## 6. When AppShell doesn't have a component you need
 
@@ -272,15 +326,15 @@ Most ERP screens compose entirely from AppShell primitives. When you hit a gap,
 
 ### Decision tree
 
-1. **Can you compose existing AppShell primitives?** A "card with metric and trend arrow" is `Card` + `Stat` + `Icon`, not a new component. Compose first.
+1. **Can you compose existing AppShell primitives?** A "card with a metric and a trend arrow" is `MetricCard`, or `Card` plus a lucide icon — not a new component. Compose first, and check `components.md` for what already exists before concluding there is a gap.
 2. **If composition won't work, is the behavior one-off?** Build it locally under `src/components/<name>/` and flag it for the `build-component` skill, which promotes useful customs into AppShell upstream.
 3. **If it's already proven reusable across 2+ apps**, skip local entirely — use the `build-component` skill to add it to AppShell directly.
 
 ### Conformance rules (non-negotiable for any custom component)
 
-- **Tokens only.** No hex literals, no magic px values, no hand-rolled shadows. Every visual property maps to a token from Section 4.
+- **Tokens only.** No hex literals, no magic px values, no hand-rolled shadows. Every visual property maps to a token from Section 4 — and only to a token that actually exists there.
 - **Base UI data-attribute pattern for state.** Expose `data-*` attributes that reflect internal state; never style off React props alone. A custom toggle exposes `data-checked`; a custom step indicator exposes `data-active`, `data-completed`, etc.
-- **Compose AppShell primitives inside.** If the custom needs a button, use `Button` — not raw `<button>`. Same for `Input`, `Badge`, `Icon`. The custom's job is composition, not reinvention.
+- **Compose AppShell primitives inside.** If the custom needs a button, use `Button` — not raw `<button>`. Same for `Input`, `Badge`, `Card`. The custom's job is composition, not reinvention.
 - **Document with a `README.md`** in the component folder listing: purpose, props, tokens used, and a brief justification for why this can't be composed from existing AppShell primitives.
 - **Match accessibility behavior** of the closest AppShell equivalent — focus management, ARIA roles/attributes, keyboard interactions. Reach for Base UI primitives if the behavior is non-trivial.
 
@@ -288,7 +342,7 @@ Example skeleton for a local custom component:
 
 ```tsx
 // src/components/StepIndicator/index.tsx
-import { Icon } from "@tailor-platform/app-shell";
+import { Check } from "lucide-react";
 
 type Props = { steps: string[]; current: number };
 
@@ -301,13 +355,13 @@ export function StepIndicator({ steps, current }: Props) {
           data-active={i === current ? "" : undefined}
           data-completed={i < current ? "" : undefined}
           className="
-            flex items-center gap-2 px-3 py-2 rounded-md
-            bg-surface-2 text-fg-muted text-body-sm
-            data-[active]:bg-primary data-[active]:text-fg-default
-            data-[completed]:text-success
+            flex items-center gap-2 rounded-md px-3 py-2
+            bg-muted text-sm text-muted-foreground
+            data-[active]:bg-primary data-[active]:text-primary-foreground
+            data-[completed]:text-status-completed
           "
         >
-          {i < current && <Icon name="check" size="sm" />}
+          {i < current && <Check className="size-4" />}
           {label}
         </li>
       ))}
@@ -316,7 +370,7 @@ export function StepIndicator({ steps, current }: Props) {
 }
 ```
 
-Notice: tokens for every value, `data-*` attributes for state, no hex literals, AppShell `Icon` composed inside.
+Notice: every value is a real token, `data-*` attributes carry state, no hex literals, and the icon comes from `lucide-react` rather than a nonexistent `Icon` component.
 
 ### Promotion path
 
@@ -338,21 +392,21 @@ When a custom component proves reusable across 2+ apps, promote it upstream into
 
 ### Semantic decisions
 
-| Intent                             | Pick                                                                                                                  |
-| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| Destructive action (delete, void)  | Prefer **`Button`** `variant="destructive"`; use danger tokens on custom surfaces; confirm in dialog at elevation `4` |
-| Non-blocking caution               | `bg-warning`                                                                                                          |
-| Confirmation / completed state     | `bg-success`                                                                                                          |
-| Neutral callout                    | `bg-info`                                                                                                             |
-| Persistent panel (sidebar, header) | elevation `1`                                                                                                         |
-| Hovered / sticky surface           | elevation `2`                                                                                                         |
-| Popover / menu / tooltip           | elevation `3`, `--motion-fast`                                                                                        |
-| Modal / sheet / dialog             | elevation `4`, `--motion-slow` entrance                                                                               |
-| Hover / focus transition           | `--motion-fast`                                                                                                       |
-| State change (toggle, select)      | `--motion-base`                                                                                                       |
-| Two-column detail at <1024         | right column collapses below main — do not override                                                                   |
-| Inline ID, code, table number      | `text-mono`                                                                                                           |
-| Timestamp, label, subtle metadata  | `text-caption text-fg-subtle`                                                                                         |
+| Intent                             | Pick                                                                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Destructive action (delete, void)  | `Button variant="destructive"`; `bg-destructive` on custom surfaces; confirm in a dialog at `shadow-lg` |
+| Non-blocking caution               | `Badge variant="warning"`, or `bg-status-attention`                                                     |
+| Confirmation / completed state     | `Badge variant="success"`, or `bg-status-completed`                                                     |
+| Neutral callout                    | `Badge variant="info"`, or the `Alert` component                                                        |
+| Persistent panel (sidebar, header) | `shadow-sm`                                                                                             |
+| Hovered / sticky surface           | `shadow-md`                                                                                             |
+| Popover / menu / tooltip           | `bg-popover`, `shadow-md`, `duration-150`                                                               |
+| Modal / sheet / dialog             | `shadow-lg`, `duration-300` entrance                                                                    |
+| Hover / focus transition           | `duration-150 ease-out`                                                                                 |
+| State change (toggle, select)      | `duration-200 ease-in-out`                                                                              |
+| Two-column detail at <1024         | right column collapses below main — do not override                                                     |
+| Inline ID, code, table number      | `font-mono text-xs` (identifiers) / `tabular-nums` (figures)                                            |
+| Timestamp, label, subtle metadata  | `text-xs text-muted-foreground`                                                                         |
 
 ### Composition & emphasis rules
 
@@ -366,9 +420,9 @@ These are visual-composition rules every screen must follow, regardless of patte
   - **Secondary statuses** (delivery, billing, fulfilment) and dense supporting columns → **`outline-*`** (with status dot).
   - **Tags / labels** ("New", "Returned") → **`subtle-*`**.
   - Reserve **`default`** (brand fill) for non-status emphasis — never the brand color as a routine status. The defect to avoid: making _every_ chip a loud fill, or giving secondary statuses the same weight as the primary one. (Variants: **`components.md`** → `Badge`.)
-- **Color:** status colors (`success`/`warning`/`error`/`info`) signal meaning, not decoration — don't tint neutral content.
+- **Color:** status colors signal meaning, not decoration — don't tint neutral content.
 
-**Hierarchy.** One `h1` per page (the `Layout.Header` title). Section headings step down (`h2` → `h3`); never skip levels for size — pick the role token (`design-system.md` §4 Typography), not the pixel size.
+**Hierarchy.** One `h1` per page (the `Layout.Header` title). Section headings step down in weight and size; never skip levels for size — pick the role from §4 Typography, not the pixel size.
 
 **States — never ship only the happy path.** Every data-backed screen handles: