@tailor-platform/app-shell 1.14.0 → 1.16.0

package/skills/app-shell-patterns/references/{fundamental/design-system.md → concepts/styling-theming.md}

@@ -1,16 +1,21 @@
-# Design System
+---
+title: Styling and Theming
+description: The AppShell design system — Tailwind CSS v4 setup, theming and palettes, the token catalog, typography, and the styling boundary
+---
 
-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.
+<!-- GENERATED by docs-kit from docs-src/concepts/styling-theming.docs.outline.md — do not edit by hand. -->
 
-`@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.
+# 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 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.
+**Every token in this document 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: 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.
 
-## 1. Setup
+## Setup
 
-The app's CSS entrypoint (`index.css` / `globals.css`) needs exactly this:
+AppShell exports `@tailor-platform/app-shell/styles`. Your app's CSS entrypoint (`index.css` / `globals.css`) needs exactly this:
 
 ```css
 @import "tailwindcss";
@@ -21,14 +26,14 @@ The app's CSS entrypoint (`index.css` / `globals.css`) needs exactly this:
 ```
 
 - **`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/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`.
+**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; the `vite` / PostCSS wiring is minimal.
 
-## 2. Theming via CSS variables
+## Theming with CSS variables
 
 Tokens exist in two layers, and knowing which one you are touching matters:
 
@@ -57,31 +62,85 @@ Override at the highest scope where the change applies. A narrower scope (per-se
 
 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
+## Theme Palettes
 
-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 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
-/* Style a component based on its state */
-.SwitchThumb[data-checked] {
-  background-color: var(--status-completed);
-}
+@import "tailwindcss";
+@import "@tailor-platform/app-shell/styles";
+@import "@tailor-platform/app-shell/themes/cream"; /* overrides default palette */
+```
 
-.MenuItem[data-highlighted] {
-  background-color: var(--accent);
-  color: var(--accent-foreground);
-}
+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**       | Do not duplicate      | Status and alert tokens inherit from `default.css`                             |
+| **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>
 ```
 
-This works with Tailwind as well — **use theme tokens**, not raw Tailwind grays:
+Use the [`useTheme`](../api/use-theme.md) hook to read or change the theme at runtime:
+
+<example-preview name="theme-toggle"></example-preview>
 
 ```tsx
-<Switch.Thumb className="bg-muted data-[checked]:bg-primary" />
+function ThemeToggle() {
+  const { resolvedTheme, setTheme } = useTheme();
+  return (
+    <button onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}>
+      Switch to {resolvedTheme === "dark" ? "light" : "dark"} mode
+    </button>
+  );
+}
 ```
 
-Check each component's API reference (`components.md`) for the data attributes it exposes. Custom components must follow the same convention (see Section 6).
+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>
 
-## 4. Tokens
+```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.
 
@@ -300,115 +359,181 @@ Stock Tailwind breakpoints — AppShell does not change them.
 
 **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 `components.md` → Layout; reuse those numbers 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 [`Layout`](../components/layout.md); reuse those numbers instead of guessing rem values here.
 
-## 5. The `astw:` prefix
+## Fonts
 
-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.
+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:
 
-**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.
+```css
+@import "tailwindcss";
+@import "@tailor-platform/app-shell/styles";
+```
 
-Minimal illustration — the same rules apply to other `*ClassName` hooks:
+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.
 
-```tsx
-<Table.Root containerClassName="astw:px-6 astw:overflow-y-auto" />
+### 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;
+}
 ```
 
-Rules:
+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.
 
-- `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 the scale — never arbitrary `astw:p-[13px]`.
+## Styling AppShell components
 
-## 6. When AppShell doesn't have a component you need
+Write **plain Tailwind utilities** in your application code. Three rules cover every case:
 
-Most ERP screens compose entirely from AppShell primitives. When you hit a gap, work through this decision tree before building anything:
+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:
 
-### Decision tree
+   ```tsx
+   <Table.Root containerClassName="max-h-96 overflow-y-auto" />
+   ```
 
-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.
+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.
 
-### Conformance rules (non-negotiable for any custom component)
+```tsx
+// Props, not utilities, for a component's own appearance
+<Sheet.Content size="lg" />
+<Layout gap={6} />
+<Button variant="destructive">Delete</Button>
 
-- **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`, `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.
+// 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>
+```
 
-Example skeleton for a local custom component:
+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), and `!` is what the pattern catalogue uses for the one documented case, zeroing a card's padding so a table can sit flush inside it:
 
 ```tsx
-// src/components/StepIndicator/index.tsx
-import { Check } from "lucide-react";
+<Card.Root>
+  <Card.Header title="Line items" />
+  <Card.Content className="px-0!">
+    <Table.Root>{/* … */}</Table.Root>
+  </Card.Content>
+</Card.Root>
+```
 
-type Props = { steps: string[]; current: number };
+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.
 
-export function StepIndicator({ steps, current }: Props) {
-  return (
-    <ol className="flex gap-2">
-      {steps.map((label, i) => (
-        <li
-          key={label}
-          data-active={i === current ? "" : undefined}
-          data-completed={i < current ? "" : undefined}
-          className="
-            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 && <Check className="size-4" />}
-          {label}
-        </li>
-      ))}
-    </ol>
-  );
-}
+### 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" />
 ```
 
-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.
+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.
 
-### Promotion path
+### Styling by state (data attributes)
 
-When a custom component proves reusable across 2+ apps, promote it upstream into AppShell via the `build-component` skill (a separate skill at `~/.claude/skills/build-component/`). The skill handles API design, exports, test coverage, and the upstream PR. Local custom components should be considered staging — not a permanent home.
+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:
 
-## 7. Quick reference
+```css
+/* Style a component based on its state */
+.SwitchThumb[data-checked] {
+  background-color: var(--status-completed);
+}
 
-### Where to look
+.MenuItem[data-highlighted] {
+  background-color: var(--accent);
+  color: var(--accent-foreground);
+}
+```
 
-| Concern                                             | File                               |
-| --------------------------------------------------- | ---------------------------------- |
-| Component imports, props, JSX composition           | **`components.md`**                |
-| Page / screen layout patterns                       | **`patterns/<type>/<slug>.md`**    |
-| Design tokens, `astw:` rules, custom UI conformance | **this file** (`design-system.md`) |
+This works with Tailwind as well — **use theme tokens**, not raw Tailwind grays:
 
-**`components.md`** holds long JSX compositions (e.g. **`DataTable`**, **card + `Table`**). **Do not copy those trees into this file** — link back here only for tokens and `astw:` policy.
+```tsx
+<Switch.Thumb className="bg-muted data-[checked]:bg-primary" />
+```
 
-`patterns/` is organised by page type: `patterns/list/`, `patterns/detail/`, `patterns/form/`, `patterns/interaction/`. Pick the slug matching the screen you're building.
+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)).
 
-### Semantic decisions
+## Links
 
-| 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`                                                                         |
+One treatment for every text link — inside `DescriptionCard`, in table rows,
+in cards:
 
-### Composition & emphasis rules
+- **`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.
 
@@ -419,10 +544,10 @@ These are visual-composition rules every screen must follow, regardless of patte
   - 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: **`components.md`** → `Badge`.)
+  - 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 §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 the Tokens → Typography table, not the pixel size.
 
 **States — never ship only the happy path.** Every data-backed screen handles:
 
@@ -430,4 +555,34 @@ These are visual-composition rules every screen must follow, regardless of patte
 - **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 (§4) 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.
+**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-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`                                                                         |

package/skills/app-shell-patterns/references/migrations.md

@@ -1,3 +1,5 @@
+<!-- GENERATED by docs-kit from docs-src/guides/migrations.docs.outline.md — do not edit by hand. -->
+
 # Migrations
 
 Every change that requires you to edit your application before or after upgrading, newest first.
@@ -8,6 +10,7 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 
 | Version       | Change                                                                                                                       |
 | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| 1.15.0        | [Base UI 1.8.0 breaks closed-`Select` and dialog-click tests](#1150-base-ui-180-breaks-closed-select-and-dialog-click-tests) |
 | 1.12.0        | [`DateField` / `DatePicker` field chrome moved to `Field.Root`](#1120-datefield--datepicker-field-chrome-moved-to-fieldroot) |
 | 1.11.0        | [React 19.2.7 and React Router v8 required](#1110-react-1927-and-react-router-v8-are-now-required)                           |
 | 1.11.0        | [Non-modal `Sheet` renders no backdrop](#1110-non-modal-sheet-no-longer-renders-a-backdrop)                                  |
@@ -18,6 +21,37 @@ Each entry states which versions are affected, what breaks, how to detect it, an
 | 1.0.2         | [`Toaster` no longer accepts `richColors`](#102-toaster-no-longer-accepts-richcolors)                                        |
 | before 1.0    | [Pre-1.0 breaking changes](#before-10)                                                                                       |
 
+## 1.15.0: Base UI 1.8.0 breaks closed-`Select` and dialog-click tests
+
+**Applies to:** apps with unit tests that assert `Select` options without opening the `Select`, and apps with Playwright tests that click buttons inside a `Dialog` or `AlertDialog`.
+
+1.15.0 updates the bundled `@base-ui/react` from 1.6.0 to 1.8.0 (1.12.0 to 1.14.0 used 1.6.0). The AppShell API is unchanged and the app behaves the same for the people using it. Two upstream behaviour changes do break tests that relied on the old behaviour, so an app that changes nothing can still go red in CI after upgrading. The fix is in the tests, not the app.
+
+### `Select` options are not in the DOM until it opens
+
+A closed `Select` used to render its options into the DOM. It no longer does, so a test that asserts option text with `getByText` on a closed `Select` fails with "Unable to find an element".
+
+Open the `Select` first, then wait for the option:
+
+```tsx
+await userEvent.click(screen.getByRole("combobox", { name: "Auto Renewal Period" }));
+expect(await screen.findByText("1 Month")).toBeInTheDocument();
+```
+
+### Dialog scroll lock can move a button under a Playwright click
+
+Opening a `Dialog` or `AlertDialog` applies a scroll lock that shifts the layout slightly. Playwright can judge a button stable and then click where it used to be, so the click lands on the backdrop and closes the dialog. The test then times out waiting for the dialog, and the Playwright call log shows the click being retried after "element was detached from the DOM".
+
+Press the button instead of clicking it. `press` does not use coordinates, so the layout shift cannot affect it:
+
+```ts
+const confirm = page.getByRole("alertdialog").getByRole("button", { name: "Delete" });
+await expect(confirm).toBeVisible();
+await confirm.press("Enter");
+```
+
+Do not reach for `click({ force: true })`. It only skips Playwright's stability check, and the click can still miss.
+
 ## 1.12.0: `DateField` / `DatePicker` field chrome moved to `Field.Root`
 
 **Applies to:** apps passing `label`, `description`, `errorMessage`, or `hideTimeZone` to `DateField` or `DatePicker`.