@tailor-platform/app-shell 1.15.0 → 1.17.0

package/skills/app-shell-patterns/references/concepts/styling-theming.md

@@ -0,0 +1,785 @@
+---
+title: Styling and Theming
+description: The AppShell design system — Tailwind CSS v4 setup, theming and palettes, the token catalog, typography, and the styling boundary
+---
+
+<!-- GENERATED by docs-kit from docs-src/concepts/styling-theming.docs.outline.md — do not edit by hand. -->
+
+# Styling and Theming
+
+Styling is done with **Tailwind CSS v4** against `@tailor-platform/app-shell`'s design system, which ships as CSS variables bridged into Tailwind's token namespace. Use the tokens 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 token in this document is verified against the shipped CSS.** If a token is not listed here, assume it does not exist. The colour scales (`--primitive-*`) are internal: they are not bridged to Tailwind and are not listed. Inventing a plausible-sounding token (`bg-surface-1`, `text-fg-muted`, `--space-4`) is the worst failure mode available: Tailwind emits **no CSS at all** for an unknown utility, so the class is silently dropped and the element renders unstyled — no error, no warning, nothing in the console. When unsure, read `node_modules/@tailor-platform/app-shell/dist/themes/default.css`; it is the ground truth.
+
+## Setup
+
+AppShell exports `@tailor-platform/app-shell/styles`. Your app's CSS entrypoint (`index.css` / `globals.css`) needs exactly this:
+
+```css
+@import "tailwindcss";
+@import "@tailor-platform/app-shell/styles";
+
+/* Optional: at most one palette override, imported AFTER styles */
+@import "@tailor-platform/app-shell/themes/bloom";
+```
+
+- **`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 ships the palette (light **and** dark), the Tailwind v4 `@theme inline` bridge (so `bg-background` / `text-muted-foreground` resolve in _your_ Tailwind build), and AppShell's precompiled component CSS. Your entry CSS should declare none of these itself — a copy of any of them overrides AppShell's and silently breaks dark mode.
+- **`@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.
+
+**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; the `vite` / PostCSS wiring is minimal.
+
+## Theming with CSS variables
+
+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 {
+  --primary: #3b82f6;
+}
+
+:root.dark {
+  --primary: #60a5fa;
+}
+```
+
+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.
+
+**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.
+
+## Theme Palettes
+
+AppShell ships three palettes, each with light and dark variants:
+
+| Palette   | CSS import                                                     |
+| --------- | -------------------------------------------------------------- |
+| `default` | Included automatically via `@tailor-platform/app-shell/styles` |
+| `cream`   | `@tailor-platform/app-shell/themes/cream`                      |
+| `bloom`   | `@tailor-platform/app-shell/themes/bloom`                      |
+
+Select a palette by importing its CSS file — no prop needed. Import it in your global CSS **after** `@tailor-platform/app-shell/styles`:
+
+```css
+@import "tailwindcss";
+@import "@tailor-platform/app-shell/styles";
+@import "@tailor-platform/app-shell/themes/cream"; /* overrides default palette */
+```
+
+Only import one palette at a time.
+
+## Adding a palette
+
+Theme tokens live in `packages/core/src/assets/themes/`. Copy `_template.css` to start a new palette — it lists exactly which sections to fill in for light and dark mode.
+
+| Section               | Required?             | What to set                                                                                                                                            |
+| --------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **1. Brand**          | Yes                   | `primary`, `secondary`, `accent` (+ foregrounds) — both modes                                                                                          |
+| **2. Shell gradient** | Branded palettes only | `--shell-gradient-base`, `--shell-gradient-tint`                                                                                                       |
+| **3. System**         | Tune or copy default  | Surfaces: background, card, popover, muted, borders                                                                                                    |
+| **4. Palette**        | Optional              | Radius, chart colors, shadows                                                                                                                          |
+| **5. Semantic**       | Inherit               | Colour scales, status and alert tokens inherit from `default.css`. Override a colour role (`--{intent}-{role}`) only to recolour the status components |
+| **6. Structural**     | Branded palettes      | Copy the structural override block from `bloom.css` or `cream.css` when needed                                                                         |
+
+A palette is selected by CSS import, not by an AppShell prop. Import exactly one theme file after `@tailor-platform/app-shell/styles`; if you import none, the default palette from `styles` is used.
+
+Preview token values at `/showcase/colors` in the Vite example app.
+
+Or skip the local setup: **[theme.tailor.tech](https://theme.tailor.tech/playground)**
+takes a primary color, previews it on real AppShell components, and exports a
+`themes/{name}.css` structured according to the tier table above.
+
+## Color modes: light / dark / system
+
+AppShell supports three color modes: `light`, `dark`, and `system` (follows the OS setting).
+
+Set the initial mode via the `defaultColorTheme` prop on `<AppShell>`. The user's selection is persisted to `localStorage` and restored on subsequent visits:
+
+```tsx
+<AppShell defaultColorTheme="system" modules={modules}>
+  {/* ... */}
+</AppShell>
+```
+
+Use the [`useTheme`](../api/use-theme.md) hook to read or change the theme at runtime:
+
+<example-preview name="theme-toggle"></example-preview>
+
+```tsx
+function ThemeToggle() {
+  const { resolvedTheme, setTheme } = useTheme();
+  return (
+    <button onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}>
+      Switch to {resolvedTheme === "dark" ? "light" : "dark"} mode
+    </button>
+  );
+}
+```
+
+Drop the pre-built [`AppearanceSwitcher`](../components/appearance-switcher.md) component anywhere in your layout for a ready-made light/dark/system toggle:
+
+<example-preview name="appearance-toggle"></example-preview>
+
+```tsx
+function AppearanceToggle() {
+  return <AppearanceSwitcher />;
+}
+```
+
+## Tokens
+
+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
+
+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
+
+**Deprecated.** These five tokens and their utilities remain for existing code and will be removed in the next major. New code uses the [semantic color roles](#semantic-color-roles) below. In the default palette they are aliases of those roles, so status colors and Alert colors agree:
+
+| Token                | Use                                                  | Tailwind              | Use instead            |
+| -------------------- | ---------------------------------------------------- | --------------------- | ---------------------- |
+| `--status-default`   | none / not applicable (follows `--muted-foreground`) | `bg-status-default`   | `bg-neutral-indicator` |
+| `--status-neutral`   | informational                                        | `bg-status-neutral`   | `bg-info-solid`        |
+| `--status-completed` | success, completed                                   | `bg-status-completed` | `bg-success-solid`     |
+| `--status-attention` | warning, needs attention                             | `bg-status-attention` | `bg-warning-solid`     |
+| `--status-danger`    | error, blocked                                       | `bg-status-danger`    | `bg-danger-solid`      |
+
+Prefer `Badge` with a semantic variant (`success`, `warning`, `error`, `info`, `neutral`) over applying a fill directly — the variants already pair fill and foreground correctly.
+
+These are fill and indicator colors. `--status-default` follows `--muted-foreground`, so it is theme-dependent and translucent in `cream` and `bloom`; the four hue tokens are opaque in every palette. Do not use them as text color: `--status-completed`, `--status-danger` and `--status-neutral` are below 4.5:1 on a dark card, and `--status-attention` is below 3:1 on a light one. For text, use `text-{intent}-text`.
+
+#### Semantic color roles
+
+Each intent has eight roles. The intents are `info`, `success`, `warning`, `danger` and `neutral`. The hue intents read internal color scales; `neutral` reads the system tokens. Every role is a token named `--{intent}-{role}` and a Tailwind color named `{intent}-{role}`:
+
+| Role            | Tailwind                | Use for                             |
+| --------------- | ----------------------- | ----------------------------------- |
+| `surface`       | `bg-info-surface`       | Soft background                     |
+| `surface-hover` | `bg-info-surface-hover` | Hover state of a soft background    |
+| `border`        | `border-info-border`    | Border on a soft background         |
+| `solid`         | `bg-info-solid`         | Filled background                   |
+| `solid-hover`   | `bg-info-solid-hover`   | Hover state of a filled background  |
+| `text`          | `text-info-text`        | Text and icons on a soft background |
+| `contrast`      | `text-info-contrast`    | Text on a filled background         |
+| `indicator`     | `bg-info-indicator`     | Dots and small marks                |
+
+```tsx
+<span className="rounded-md bg-success-surface px-2 py-0.5 text-success-text">Paid</span>
+```
+
+In the default palette, `text` on `surface` and `contrast` on `solid` and `solid-hover` are at least 4.5:1 for the four hue intents, in light and dark mode, on `--card` and `--background`. A unit test checks this from the shipped CSS. `text` on `surface-hover` is held at 4.2:1 by the same test; it is below 4.5:1 for `danger` and `success` in light mode. The test does not cover the `cream` and `bloom` palettes or the `neutral` intent.
+
+Most `surface` and `border` values are translucent tints, so an opacity modifier compounds rather than replaces — `bg-info-surface/50` halves the tint's alpha instead of setting it to 50%. Some light-mode values are opaque instead of translucent: the `warning` surface, surface-hover and border, the `info` border and the `danger` surface-hover. They do not blend with a tinted parent. All dark-mode values are translucent.
+
+`Badge`, `Alert`, `CsvImporter` and `MetricCard` read these roles directly, not `--status-*` or `--alert-*`. To recolour them, override the roles. `Badge` `error` and `subtle-error`, and `Alert` `error`, follow `--danger-*`. They no longer follow `--destructive`, which still drives `Button` and `text-destructive`.
+
+#### 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
+
+**Deprecated.** `--alert-{neutral,success,warning,error,info}-{background,foreground,foreground-muted,border}` and the matching utilities (`bg-alert-info-background`, `text-alert-info-foreground`, ...) remain for existing code and will be removed in the next major. In the default palette they are aliases of the semantic color roles: `background` is `surface`, `border` is `border`, `foreground` is `text`, and `foreground-muted` follows `foreground`; `error` reads the `danger` intent. The `Alert` component reads the roles, so overriding `--alert-*` changes these utilities but not `Alert`.
+
+For new custom surfaces, use the roles instead of the alert slots:
+
+```tsx
+<div className="rounded-lg border bg-warning-surface text-warning-text border-warning-border">
+  …
+</div>
+```
+
+Across all colour tokens:
+
+```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>
+
+// Bad — these classes do not exist and render as nothing at all
+<div className="bg-surface-1 text-fg-muted">…</div>
+```
+
+### 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
+<div className="flex gap-3 p-4">…</div>
+
+// Bad — magic value
+<div className="p-[13px]">…</div>
+```
+
+Hand-typing `padding: 13px` is a smell. Round to the nearest scale step; if nothing fits, the layout is wrong, not the scale.
+
+### Typography
+
+AppShell defines **composite typography role tokens**. A role sets font size, line height, font weight, and letter spacing together, so one utility such as `text-heading-md` replaces a set like `text-lg font-semibold`. The font family is a separate token, `--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`.
+
+There are 8 core roles and 2 relaxed body variants:
+
+| Role              | Utility                | Size / line height | Weight | Use                                             |
+| ----------------- | ---------------------- | ------------------ | ------ | ----------------------------------------------- |
+| `heading-lg`      | `text-heading-lg`      | 24px / 32px        | 700    | Page title (`Layout.Header`)                    |
+| `heading-md`      | `text-heading-md`      | 18px / 28px        | 600    | Section heading, card title                     |
+| `heading-sm`      | `text-heading-sm`      | 14px / 20px        | 600    | Sub-section heading                             |
+| `body-md`         | `text-body-md`         | 14px / 20px        | 400    | Body copy, descriptions                         |
+| `body-sm`         | `text-body-sm`         | 12px / 16px        | 400    | Caption, timestamp, metadata                    |
+| `label-md`        | `text-label-md`        | 14px / 20px        | 500    | Field label, short UI text, figures in a table  |
+| `label-sm`        | `text-label-sm`        | 12px / 16px        | 500    | Small label, badge text                         |
+| `code-sm`         | `text-code-sm`         | 12px / 18px        | 400    | ID and code. Use with `font-mono`               |
+| `body-md-relaxed` | `text-body-md-relaxed` | 14px / 24px        | 400    | Long text, such as a chat message or a document |
+| `body-sm-relaxed` | `text-body-sm-relaxed` | 12px / 20px        | 400    | Long text at the small size                     |
+
+`heading-lg` also sets letter spacing to `-0.025em`. All other roles set `0em`.
+
+Pair a role with a color token from the Color section above. These pairings are the recommended combinations:
+
+| Use                               | Utilities                                      |
+| --------------------------------- | ---------------------------------------------- |
+| Page title (`Layout.Header`)      | `text-heading-lg`                              |
+| Section heading                   | `text-heading-md`                              |
+| Card title (`div` or `span`)      | `text-heading-md leading-none`                 |
+| Body copy                         | `text-body-md`                                 |
+| Secondary copy, descriptions      | `text-body-md text-muted-foreground`           |
+| Caption, timestamp, metadata      | `text-body-sm text-muted-foreground`           |
+| Numeric value in a table or field | `text-label-md tabular-nums`                   |
+| ID, code                          | `font-mono text-code-sm text-muted-foreground` |
+
+<example-preview name="typography-roles"></example-preview>
+
+```tsx
+function TypographyRoles() {
+  const rows = [
+    {
+      role: "heading-lg",
+      className: "text-heading-lg",
+      en: "Purchase orders",
+      ja: "発注管理",
+    },
+    {
+      role: "heading-md",
+      className: "text-heading-md",
+      en: "Purchase orders by supplier",
+      ja: "仕入先別の発注一覧",
+    },
+    {
+      role: "heading-sm",
+      className: "text-heading-sm",
+      en: "Delivery address",
+      ja: "納品先",
+    },
+    {
+      role: "body-md",
+      className: "text-body-md",
+      en: "The order was sent to the supplier on 12 March.",
+      ja: "発注書は3月12日に仕入先へ送付されました。",
+    },
+    {
+      role: "body-sm",
+      className: "text-body-sm text-muted-foreground",
+      en: "Updated 2 hours ago",
+      ja: "2時間前に更新",
+    },
+    {
+      role: "label-md",
+      className: "text-label-md",
+      en: "Order quantity",
+      ja: "発注数量",
+    },
+    {
+      role: "label-sm",
+      className: "text-label-sm",
+      en: "Draft",
+      ja: "下書き",
+    },
+    {
+      role: "code-sm",
+      className: "font-mono text-code-sm",
+      en: "PO-2026-000184",
+      ja: "PO-2026-000184",
+    },
+    {
+      role: "body-md-relaxed",
+      className: "text-body-md-relaxed",
+      compareWith: { role: "body-md", className: "text-body-md" },
+      en: "Please confirm the delivery date with the supplier before you approve this order. If the supplier cannot deliver by the requested date, change the date or choose another supplier. Approved orders are sent to the supplier by email.",
+      ja: "この発注を承認する前に、納期を仕入先に確認してください。希望日までに納品できない場合は、納期を変更するか、別の仕入先を選んでください。承認した発注は、メールで仕入先に送られます。",
+    },
+    {
+      role: "body-sm-relaxed",
+      className: "text-body-sm-relaxed text-muted-foreground",
+      compareWith: { role: "body-sm", className: "text-body-sm text-muted-foreground" },
+      en: "Changes to a confirmed order are recorded in the order history. Each record shows who made the change, when it was made, and the values before and after the change.",
+      ja: "確定済みの発注への変更は、発注履歴に記録されます。記録には、変更した人、変更した日時、変更前と変更後の値が含まれます。",
+    },
+  ];
+
+  return (
+    <div className="flex flex-col gap-4">
+      {rows.map(({ role, className, compareWith, en, ja }) => (
+        <div key={role} className="grid grid-cols-[9rem_1fr] items-baseline gap-4">
+          <span className="font-mono text-code-sm text-muted-foreground">{role}</span>
+          {compareWith ? (
+            // A relaxed role changes only line height, so show the same text in the base role first.
+            <div className="flex flex-col gap-4">
+              {[compareWith, { role, className }].map((variant) => (
+                <div key={variant.role} className="flex flex-col gap-1">
+                  <span className="font-mono text-code-sm text-muted-foreground">
+                    {variant.role}
+                  </span>
+                  <p className={variant.className}>{en}</p>
+                  <p className={variant.className}>{ja}</p>
+                </div>
+              ))}
+            </div>
+          ) : (
+            <div className="flex flex-col gap-1">
+              <p className={className}>{en}</p>
+              <p className={className}>{ja}</p>
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+```tsx
+<h2 className="text-heading-md">Section</h2>
+<p className="text-body-md text-muted-foreground">Description copy</p>
+<span className="text-body-sm text-muted-foreground">Updated 2h ago</span>
+```
+
+On an `h1` to `h6` element, the `cream` and `bloom` palettes replace the role's line height and letter spacing, including `leading-none`; see "Change a role" below. AppShell's own components still use the stock utilities (`text-sm`, `font-medium`, and so on) today. They will move to the roles in later changes, so the two sets can appear side by side for now.
+
+**Rules**
+
+- **A role carries no color.** Set the color with a token such as `text-muted-foreground`.
+- **A role does not choose the HTML element.** Pick `h2`, `p`, or `span` from the document structure, not from the size.
+- **A role sets weight and letter spacing on its own element.** It does not inherit them from a parent. Put an emphasis or tracking class on the element that has the role, not on its parent.
+- **Four modifiers may be combined with a role.** All are stock Tailwind utilities:
+  - Compact line height: `leading-none`. Use it only for single-line text, such as a card title. Write it after the role when you merge with `cn()`.
+  - Tabular figures: `tabular-nums`.
+  - Emphasis on inline text: `font-medium` or `font-semibold`.
+  - Uppercase: `uppercase`.
+- **Do not combine a role with other `leading-*`, `tracking-*`, or `text-[Npx]` values.** If none of the roles fits, use the nearest role.
+- **12px is the minimum size.** Do not use smaller text.
+- **`code-sm` needs `font-mono`.** The role sets size, line height, weight, and letter spacing, but a role cannot set the font family.
+- **Use the relaxed variants for long text only.** For labels, table cells, and other short text, use the regular roles.
+
+Always use `tabular-nums` for numbers that stack in a column — without it, digits jitter between rows.
+
+**Change a role.** Each role is four CSS variables named `--app-shell-type-<role>-<size|line-height|weight|letter-spacing>`. Override them on `:root` to change a role for the whole app. Typography has no dark variant, so one override applies to light and dark mode.
+
+```css
+:root {
+  --app-shell-type-heading-lg-size: 1.75rem;
+  --app-shell-type-heading-lg-line-height: calc(36 / 28);
+}
+```
+
+The `cream` and `bloom` palettes set `line-height` and `letter-spacing` on `h1` to `h6`. These rules are outside any `@layer`, so they win over a role utility, and over any `leading-*` or `tracking-*` class, on those elements. Under these palettes, an `h1` to `h6` element takes its line height (1.2) and letter spacing (`-0.03em`) from the palette. This includes `leading-none`: `<h3 className="text-heading-md leading-none">` has a line height of 1.2, while a `div` with the same classes has 1.0. Font size and weight still come from the role. The `default` palette has no such rule.
+
+**`tailwind-merge`.** AppShell's `cn()` keeps a role together with a text color class, for example when you pass `className="text-label-md text-muted-foreground"` to an AppShell component. It cannot replace a size that a component sets itself, because component classes carry the internal `astw:` prefix (see "Why a plain utility can't override an AppShell default" below). If your app has its own `cn()` built on `tailwind-merge`, register the role names. Without this, `twMerge("text-label-md text-muted-foreground")` removes the role and keeps only the color.
+
+```ts
+import { extendTailwindMerge } from "tailwind-merge";
+
+const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [
+        {
+          text: [
+            "heading-lg",
+            "heading-md",
+            "heading-sm",
+            "body-md",
+            "body-sm",
+            "body-md-relaxed",
+            "body-sm-relaxed",
+            "label-md",
+            "label-sm",
+            "code-sm",
+          ],
+        },
+      ],
+    },
+  },
+});
+```
+
+### Radius
+
+`--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         | 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` |
+
+`rounded-full` (pills, avatars) is a stock Tailwind utility — there is no `--radius-full` token, but the class works.
+
+Changing `--radius` alone rescales all four steps together.
+
+### Shadow
+
+Four mode-aware shadows. There are **no `--elevation-*` tokens**; the scale is expressed as shadows. Never hand-craft a `box-shadow`.
+
+| 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           |
+
+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.
+
+### Motion
+
+**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 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
+
+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` | 20    | sidebar collapsed rail        |
+| `--z-popup`        | 50    | menu, tooltip, popover        |
+| `--z-overlay`      | 50    | modal, sheet, dialog backdrop |
+
+```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.
+
+### Icons
+
+**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 |
+| ------------------------------------------------------------------- | ---------- |
+| 12px: `text-xs`, `text-body-sm`, `text-label-sm`, `text-code-sm`    | `size-3`   |
+| 14px: `text-sm`, `text-body-md`, `text-label-md`, `text-heading-sm` | `size-4`   |
+| 18px: `text-lg`, `text-heading-md`                                  | `size-5`   |
+| 24px (title): `text-2xl`, `text-heading-lg`                         | `size-6`   |
+
+```tsx
+import { Check } from "lucide-react";
+
+<Check className="size-4" />;
+```
+
+### Breakpoints
+
+Stock Tailwind breakpoints — AppShell does not change them.
+
+| Token | Width  |
+| ----- | ------ |
+| `sm`  | 640px  |
+| `md`  | 768px  |
+| `lg`  | 1024px |
+| `xl`  | 1280px |
+| `2xl` | 1536px |
+
+**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. The `Layout` column width table lives in [`Layout`](../components/layout.md); reuse those numbers instead of guessing rem values here.
+
+## Fonts
+
+AppShell bundles **Inter Variable** for Latin and **Noto Sans JP Variable** for Japanese, and
+applies both via the `body` rule in `@tailor-platform/app-shell/styles`. No extra import:
+
+```css
+@import "tailwindcss";
+@import "@tailor-platform/app-shell/styles";
+```
+
+Both are variable fonts with a continuous 100–900 weight axis, so every weight the design
+system names — `font-normal`, `font-medium`, `font-semibold`, `font-bold` — resolves to a real
+weight in both scripts rather than to whatever faces happen to be installed.
+
+### Why Japanese needs its own font
+
+Inter has no CJK glyphs, so without a bundled Japanese font, Japanese characters fall through
+to the operating system's. On Windows that font is Yu Gothic UI, which ships only
+Light/Semilight/Regular/Semibold/Bold — no 500 — so CSS weight matching resolves a
+`font-weight: 500` request down to Regular, and `font-medium` becomes **indistinguishable from
+body text in Japanese**. Current macOS is not affected: it ships Hiragino Sans W0–W9 including
+W5, which `font-weight: 500` resolves to correctly. Bundling the font makes the weight scale
+hold on every platform rather than depending on what the OS happens to install.
+
+Noto Sans JP is metric-harmonised against Inter (`size-adjust: 94%` plus ascent/descent
+overrides) so mixed Japanese/Latin strings read at one optical size, and a line containing
+Japanese is exactly as tall as one without. A metric-matched `local()` fallback covers the
+window before a subset arrives, so rows do not change height as fonts stream in.
+
+### What it costs
+
+The Japanese faces are roughly **5 MB of woff2 subsets**, and they land in your build output
+whether or not your app renders Japanese — a bundler emits every subset it can see, because it
+cannot know at build time which characters your data will contain. The stylesheet grows from
+about 98 KB to 200 KB uncompressed, or 15 KB to 45 KB gzipped.
+
+What your **users** download is much smaller, and proportional to what they actually read.
+Each subset carries a `unicode-range`, so the browser fetches one only when it is about to
+paint a character in that range. The faces are restricted to Japanese blocks — kana, kanji,
+CJK punctuation, fullwidth forms and the compatibility blocks carrying ㈱ ㍿ ㎡ — so shared
+symbols such as `✓` or `→` resolve to Inter or the system font as before, and
+**an app that renders no Japanese downloads none of them**:
+
+| what the user has seen                   | downloaded  |
+| ---------------------------------------- | ----------- |
+| all hiragana + katakana                  | ~237 KB     |
+| + ~230 common ERP kanji                  | ~458 KB     |
+| + ~30 name kanji including variant forms | ~467 KB     |
+| **typical first Japanese screen**        | **~910 KB** |
+
+Files are content-hashed and cached, so the cost is front-loaded rather than per-navigation,
+and it grows slowly as unusual characters appear in your data. Weight costs nothing extra —
+every weight lives in the same file, so using `font-medium` and `font-bold` downloads no more
+than `font-normal` alone.
+
+To drop the Japanese faces entirely, override the stack without naming them (see below).
+Nothing references them, so nothing is downloaded — though the files still ship in your build
+output.
+
+### Using your own font
+
+Set `--app-shell-font-sans` on `:root` **after** importing AppShell styles to replace the whole
+stack:
+
+```css
+@import "@tailor-platform/app-shell/styles";
+
+:root {
+  --app-shell-font-sans: "Your Brand Sans", ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+A replacement should be a variable font, or otherwise supply real 400/500/600/700 faces —
+AppShell's weight scale assumes all four exist. If your app renders Japanese, include a
+Japanese family with a continuous weight axis for the same reason.
+
+## Styling AppShell components
+
+Write **plain Tailwind utilities** in your application code. Three rules cover every case:
+
+1. **Your own markup** — ordinary utilities, exactly as in any Tailwind app.
+2. **A documented layout hook** — props like `Table.Root`'s `containerClassName` also take ordinary utilities from your Tailwind build:
+
+   ```tsx
+   <Table.Root containerClassName="max-h-96 overflow-y-auto" />
+   ```
+
+3. **An AppShell component's own appearance** — reach for its documented props, variants, or composition rather than styling over its internals. `Sheet.Content` takes `size`, `Table.Head` and `Table.Cell` take `align`, `Grid` takes `columns`, `Layout` takes `gap`, `Button` takes `variant`. A prop is a supported contract; a utility class aimed at a component's internals is not.
+
+```tsx
+// Props, not utilities, for a component's own appearance
+<Sheet.Content size="lg" />
+<Layout gap={6} />
+<Button variant="destructive">Delete</Button>
+
+// Ordinary utilities on your own markup and on documented hooks
+<div className="flex flex-col gap-4">
+  <Table.Root containerClassName="max-h-96 overflow-y-auto" />
+</div>
+```
+
+When no prop exists and you genuinely have to override a value a component sets, add Tailwind's [importance modifier](https://tailwindcss.com/docs/styling-with-utility-classes#important-modifier) — a trailing `!`. It is the last resort, not the first: a plain utility silently loses (see below). Check for a prop before reaching for it. Sitting a table flush inside a card, for example, used to need `className="px-0!"`; it is now a prop:
+
+```tsx
+<Card.Root>
+  <Card.Header title="Line items" />
+  <Card.Content padding="none">
+    <Table.Root>{/* … */}</Table.Root>
+  </Card.Content>
+</Card.Root>
+```
+
+Note the table container adds **no** horizontal padding of its own there: `Table.Head` and `Table.Cell` already carry `first:pl-6` / `last:pr-6`, so a `containerClassName="px-6"` would stack on top and push the first column 24px past the card title.
+
+### Never write the `astw:` prefix in application code
+
+AppShell's own components are styled with utilities carrying an `astw:` prefix (AppShell TailWind). This exists because Tailwind generates classes at build time: AppShell's stylesheet is compiled and published before your application's is generated, and Tailwind cannot reconcile two independently-generated stylesheets against each other. The prefix keeps the library's utilities from clashing with yours.
+
+The prefix is **internal to the library**, and it is not a customization API. Your Tailwind build has no `astw` prefix configured, so it never generates `astw:*` classes — an `astw:` class written in application code only resolves if AppShell happens to already ship that exact utility for its own use. Many do not — 17 of the 55 classes this documentation used to recommend are absent from the shipped stylesheet — and Tailwind emits nothing for an unknown utility: no error, no warning, nothing in the console. The class lands in the DOM and does nothing.
+
+Worse, one `className` string can be half-applied. AppShell merges class names with `tailwind-merge`, which is not configured with the `astw` prefix, so it strips a conflicting _internal_ class while leaving an unshipped `astw:` class in place — the element keeps a dead class and loses the style it had.
+
+`@tailor-platform/eslint-plugin-app-shell` ships a `no-astw-prefix` rule that catches this in your own source. Enable it via the `recommended` preset in your `oxlint.config.ts`.
+
+### Why a plain utility can't override an AppShell default
+
+This is the reason rule 3 sends you to props rather than to a more specific class. `tailwind-merge` groups `astw:px-6` and `px-0` separately — it reads the unknown `astw:` as a variant — so both survive on the element rather than the later one replacing the earlier. Both land in the same `@layer utilities` at equal specificity, and AppShell's precompiled sheet is imported after your Tailwind output, so its rule is later in the cascade and the library's value wins:
+
+```tsx
+// Element keeps both classes; padding stays at AppShell's 24px
+<Card.Content className="px-0" />
+```
+
+(For this particular case, use `padding="none"`.)
+
+State variants make it worse rather than better: `Button`'s `ghost` variant sets a hover color, and a `:hover` rule outranks an unprefixed utility on **specificity**, not merely order — so a plain `text-destructive` on a ghost button is red only until the pointer reaches it. `variant="destructive"` is the supported way to express that; where no such prop exists, `!` wins in every state because importance beats specificity.
+
+### Styling by state (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:
+
+```css
+/* Style a component based on its state */
+.SwitchThumb[data-checked] {
+  background-color: var(--success-solid);
+}
+
+.MenuItem[data-highlighted] {
+  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-muted data-[checked]:bg-primary" />
+```
+
+Check each component's own page under `docs/components/` for the data attributes it exposes. Custom components must follow the same convention (see [Custom components](./custom-components.md)).
+
+## Links
+
+One treatment for every text link — inside `DescriptionCard`, in table rows,
+in cards:
+
+- **`text-primary` at rest, `hover:underline` only.** Colour carries the affordance; a resting underline is noise. Pair with `underline-offset-4`.
+- **Internal routes** use app-shell's `Link` (`to`), never a bare `<a href>`.
+- **External destinations** use `<a target="_blank" rel="noopener noreferrer">` with a lucide `ExternalLink` at `size-3` after the label. There is no dedicated component for this; that markup is the convention.
+- **Identifiers** (document numbers, SKUs) keep `font-mono` on top of the link style.
+
+This is the treatment `DescriptionCard` already applies to its `type: "link"`
+fields — match it rather than inventing a second one.
+
+## Composition & emphasis rules
+
+These are visual-composition rules every screen must follow, regardless of pattern. They exist because emphasis only works when it is scarce.
+
+**Emphasis budget.** Attention is a budget you spend once per scan region.
+
+- **One primary action per view.** A screen (or a card/section) has at most one filled/primary `Button`; everything else is `outline`, `secondary`, or `ghost`. If two things look equally important, neither reads as important.
+- **Badges** encode status by semantic color, with a clear primary/secondary split:
+  - A record's **primary / lifecycle status** (PO status, SO status) → a **filled semantic** variant (`success` / `warning` / `error` / `info` / `neutral`) — one per row in a list, one in a detail header.
+  - **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: [`Badge`](../components/badge.md).)
+- **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 in weight and size; never skip levels for size — pick the role from the Tokens → Typography table, not the pixel size.
+
+**States — never ship only the happy path.** Every data-backed screen handles:
+
+- **Loading** — skeleton/placeholder, not a blank flash.
+- **Empty** — a labelled empty state (what it is, how to add the first record), not a bare empty table.
+- **Error** — an inline error with a retry affordance, not a silent failure.
+
+**Spacing rhythm.** Use the spacing scale (see Tokens) consistently — equal gaps between sibling sections, consistent card padding. A one-off `gap` or `padding` that doesn't match its siblings reads as a mistake.
+
+## Quick reference
+
+### Where to look
+
+| Concern                                                    | Where                                                           |
+| ---------------------------------------------------------- | --------------------------------------------------------------- |
+| Tokens, theming, the `astw:` styling boundary, conformance | **this document**                                               |
+| A component's imports, props, variants, composition        | its page under [`docs/components/`](../components/)             |
+| A hook / function API                                      | its page under [`docs/api/`](../api/)                           |
+| Screen / page layout recipes                               | [`docs/patterns/`](../patterns/) and [`docs/pages/`](../pages/) |
+| Building a custom component to fill a gap                  | [Custom components](./custom-components.md)                     |
+
+### Semantic decisions
+
+| 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-warning-surface text-warning-text`                                    |
+| Confirmation / completed state     | `Badge variant="success"`, or `bg-success-surface text-success-text`                                    |
+| Informational callout              | `Badge variant="info"`, or `Alert variant="info"`                                                       |
+| Neutral callout                    | `Badge variant="neutral"`, or `Alert variant="neutral"`                                                 |
+| 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-code-sm` (identifiers) / `text-label-md tabular-nums` (figures)                         |
+| Timestamp, label, subtle metadata  | `text-body-sm text-muted-foreground`                                                                    |