@sableui/react 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,157 @@
+# AGENTS.md — @sableui/react
+
+How to **build with** Sable. This is the whole consumer contract an agent needs; read it top to bottom once, then retrieve details through the CLI. Changing the package itself? Read [`CONTRIBUTING.md`](./CONTRIBUTING.md). Why the system is shaped this way: [`DESIGN.md`](./DESIGN.md).
+
+## What this is
+
+**Sable** is an owned, themeable React component system: about 100 components (`npx sable manifest` has the live count), 13 layout primitives, 8 page shells, on [Base UI](https://base-ui.com) behavior with Tailwind v4 + semantic CSS-variable tokens. The default theme is **Base**; the other featured presets are Meridian, Prism, Verdant, Ember, and Poppy.
+
+**Where things are**
+
+| You need | Ask |
+|---|---|
+| Which component, and its props/examples | `npx sable search "<need>"` → `npx sable component <Name> --detail full` |
+| A page composition to start from | `npx sable pattern --list` → `npx sable pattern <Name> --skeleton` |
+| The rules for type, motion, spacing, shape, surfaces, a11y | `npx sable docs typography` (also `motion`, `spacing`, `shape`, `surfaces`, `accessibility`) |
+| Which token to reach for | `npx sable token <name>` · `npx sable docs token-intent` |
+| A task walkthrough | `npx sable docs --list --kind tasks` |
+| Is my wiring right? Is my code on-contract? | `npx sable doctor` · `npx sable-lint` |
+
+## The rules for code you write
+
+For an explicit iOS/iPhone app prototype, read `sable docs building-an-ios-prototype`
+first. **Sable first: every screen is built from Sable components** — rows, inputs,
+switches, sliders, search, buttons, forms, toasts, cards — exactly as on the web,
+and every rule below applies. `@sableui/react/ios` supplies only the iOS system
+chrome Sable has no equivalent for: `NativeApp`, `IosPage`, `IosNavbar`,
+`IosBackLink`, `IosIconButton`, `IosTabbar`, `IosTab`, `IosSheet`,
+`NavigationStack`. Never import from `konsta` (sable-lint `native-ui-import`);
+install it only as the adapter's peer for an iOS prototype. A missing piece is a
+library gap to report, not a reason for a native control.
+
+These are short on purpose. Each links to a foundations doc with the full vocabulary, the reasoning, and before/after examples; `sable-lint` catches most violations.
+
+0. **Compose from Sable components; never rebuild one.** Before writing any interactive or recognisable element — a button, a field, a toggle, tabs, a menu, a badge, a card, a search box, a dialog — run `npx sable search "<what you need>"` and use what it returns. A raw `<button>`, `<input>` or `<div>` dressed in a component's classes is a reinvention, and it is a bug even when every class is a semantic token: it misses the component's states, density, focus and keyboard contract, and drifts the moment the component changes. A link that looks like a button is `<Button render={<a href=… />}>`. If nothing fits, compose from the nearest component's parts; if it genuinely does not exist, say so in your summary — that is a library gap to report, not a license to invent. The rules below are for styling what you compose *around* components, not for re-creating them. `sable-lint` flags the common cases (`hand-rolled-control`, `lookalike-control`).
+
+   **The same goes for everything below a component. Resolve in this order, and stop at the first that fits:** (1) a **component** → (2) a Sable **utility or recipe** — relative surfaces (`sable-surface*`, `sable-well`, `sable-surface-interactive`), state variants (`sable-selected:`, `sable-highlighted:`…), geometry (`rounded-concentric-*`, `popup-inset`, `rounded-popup-item`, `popup-bleed`), scroll policies, `motion-*` recipes → (3) a **semantic token** → (4) hand-written CSS, last, and reported as a gap. `npx sable search "<what you need>"` searches all of these; `registry.json → utilities` lists the utilities with intent and what each replaces. Mixing ink into a surface by hand (`color-mix(… var(--foreground) …)`) is the tell that you skipped step 2 — that is what the relative-surface utilities compute, in every theme and mode.
+
+   **Never restyle a component with override classes to get a look it lacks.** `className` on a Sable component is for layout (width, margin, flex and grid placement, position); its look — fill, edge, corner, ring, shadow, ink — comes from a variant. Use the one that exists, and if none fits, that is a library gap to report, not a `className`. The common cases: a control floating over content is `<Button variant="floating">`, one on a coloured band `variant="on-color"`; a quiet chip is `<Pill appearance="outline" size="sm">`; a status label is `<Badge appearance="plain" tone="…" dot>`; a destructive menu row is `<MenuItem variant="destructive">` (never `className="text-destructive"`); a list of `Entity` rows in a card is `<CardList>`, and a table that runs edge to edge in a card is `<CardContent flush>`, which insets the outer columns to the card's padding (never `pl-6`/`pr-6` on cells). `sable-lint` flags these (`component-restyle`, `destructive-item-ink`, `table-edge-padding`, `popup-separator-bleed`).
+1. **Semantic tokens only.** `bg-card`, `text-muted-foreground`, `border-border`, `bg-primary` — never a palette step, never inline hex/`oklch()`. Tone fills take their paired ink (`bg-tone-success` + `text-tone-success-foreground`). → `sable docs token-intent`
+2. **Type is a closed vocabulary.** One paired utility per text node (`text-heading-2`, `text-body-md`, `text-label-lg`, `text-mono-md`); never compose `text-* font-* tracking-*` by hand. Pick by **role**, not size. One `heading-1` per route. Two colors: `foreground` and `muted-foreground` — never opacity on text. → `sable docs typography`
+3. **Space on the 4px scale, by role.** Inset, stack, inline; related things closer than unrelated things. No off-scale `p-[15px]`. Padding, gaps and insets stay on the scale (a step, or `--spacing(n)` inside an arbitrary value) so the density control moves them; fixed `rem`/`px` only for what must not scale, like a hairline. Single-column content in a card is a flex column, not a grid. → `sable docs spacing`
+4. **Controls read the ladder.** Heights come from `--control-*`, so `<Density>` can retune a region at once. Never `h-[40px]`. → `sable docs spacing`
+5. **Shape and depth are roles.** Radii from the `rounded-*` ladder, concentric when nested (inner = outer − inset; `rounded-concentric-*`, `sable-frame-inner`); elevation by transience (resting → raised → overlay → modal → toast), one shadow per surface. → `sable docs shape` · `sable docs surfaces`
+6. **Motion has a reason and a recipe.** Apply a named `motion-*` recipe; drop to `duration-(--motion-duration-*)` + `ease-*` tokens only when none fits. Never Tailwind's `animate-*`, never a raw `duration-150`. Exits are faster than entrances and never overshoot. → `sable docs motion`
+7. **Icons by semantic name.** `<Icon name="check" />`; size with `text-{size}`, never type utilities. A mark attached to a line of type (dot, bullet, leading icon) sits in an `h-[1lh] items-center` box and is sized in em, never nudged with px. → `sable docs typography`
+8. **Every scroll container declares a policy:** `scrollbar-quiet` (vertical) or `scrollbar-hidden` (horizontal, with an edge fade carrying the affordance).
+9. **Accessible by construction.** WCAG AA contrast, 44px hit areas, visible focus, logical properties, live regions that exist before they speak. → `sable docs accessibility`
+
+## Customizing: themes are presets
+
+Pick a theme as a starting point, then override tokens on top of it. Every token a theme sets can be reset by the app on `:root` (or any subtree) after the theme CSS loads — radius, density, type scale, motion scale, accent — and components follow, because they only read tokens. The docs site's **Customize** panel does exactly this live and exports the result as CSS; paste it after your Sable imports. Retrieve the overridable set with `npx sable token --list`.
+
+## Wire it up
+
+The machine-readable version of this section is the `consume` block in `registry.json`.
+
+1. **Install** from npm: `pnpm add @sableui/react` (or the project's package manager). No registry configuration or token is needed.
+2. **Dedupe React** in the bundler (`resolve.dedupe: ["react","react-dom"]`) — Base UI must not resolve a second React, or you get an "invalid hook call" blank page.
+3. **CSS, in order:** `@import "tailwindcss";` → `@import "@sableui/react/styles.css";` → `@source "<node_modules>/@sableui/react/dist/**/*.{js,mjs}";` so Tailwind scans the package's classes.
+
+   `styles.css` carries **Base only** — the default theme, and the layout floor every other theme inherits (`--page-inset`, `--region-*`, `--rhythm-unit` on a bare `:root`). The bundled **alternates are opt-in**, because they are `[data-sable-theme]`-scoped and an app that never sets the attribute ships CSS that can never match: 5.5 KB gzip of permanently-dead weight, which is exactly how a real app's build audit found this. Using one? `@import "@sableui/react/theme/prism.css";`. Offering the whole set through a `<ThemeSelector>`? `@import "@sableui/react/themes.css";`. **Symptom of forgetting:** `data-sable-theme` is set, nothing matches, and the page silently renders as Base — no error, just the wrong theme.
+4. **Fonts:** load Figtree (sans) + DM Mono (mono) — the theme declares the stacks, the host provides the files. Apply `antialiased` (`-webkit-font-smoothing: antialiased` / `-moz-osx-font-smoothing: grayscale`) **once on the app root**: Sable's type scale was drawn against smoothed text, and without it macOS renders every weight heavier than designed. The package deliberately doesn't set it — a library has no business styling the host's whole page — so it has to happen here.
+5. **Providers (all optional):** components render with **Reicon** by default, so `<IconProvider set={…}>` is only needed to replace it with another icon package or extend it using `composeIconSets(appExtras, reiconIconSet)`; `<MotionProvider>` is optional too. Use `<SableThemeProvider>` + `useSableTheme()` when the app should expose user-selectable themes; pair `themeId` / `setThemeId` with `<ThemeSelector>` and `preference` / `setPreference` with `<ThemeSwitcher>`. The provider stores `light` / `dark` / `system`, toggles the `dark` class on `<html>`, stores the active design theme, and writes `data-sable-theme` for non-default themes. Apps with their own state layer can call `applySableColorMode()` / `applySableTheme()` instead. You only need a Tailwind `@custom-variant dark` if **your** app code uses `dark:` utilities (Sable ships none).
+6. Import from the root barrel: `import { Button } from "@sableui/react"`. Page shells live on the `patterns` subpath (`import { SettingsPage } from "@sableui/react/patterns"`) — preview one, then copy its source from `registry.json → patterns` when the route needs to diverge.
+
+7. **Check the wiring:** `npx sable doctor`. Every check it runs corresponds to a way Sable fails *silently* — a second React (blank page, "invalid hook call"), a missing `@source` (Tailwind emits none of the package's classes, everything renders unstyled), or `data-sable-theme` set with no theme CSS imported (every theme renders as Base and the switcher looks broken). Exits 1 on any failure; `--json` for the structured report.
+
+8. **Read the catalog through the CLI, not the file.** `registry.json` is about 1 MB and `llms-full.txt` about 800 KB — complete and unreadable in a working context. `npx sable` serves the same generated contract in pieces, offline, at your installed version:
+
+   ```bash
+   npx sable pattern --list                      # the eight page shells
+   npx sable pattern SettingsPage --skeleton     # composition tree, fixtures stripped
+   npx sable component DataTable --props
+   npx sable search "empty state"                # across components, patterns, layout, tokens, docs
+   npx sable docs converting-an-app              # the task walkthroughs
+   npx sable manifest --json                     # the whole command surface, machine-readable
+   ```
+
+   `--json` wraps output as `{ type, data }` with a stable discriminator; `--detail brief|compact|full` picks a size; `--dense` drops prose. Errors carry a stable `code` and `suggestions` (`ERR_UNKNOWN_COMPONENT` for `Buton` suggests `Button`), so a wrong name costs one call, not a guess.
+
+   **Choose composition before components.** `--skeleton` prints a pattern's element tree with demo data removed, making comparison cheap. Reuse a shell when its information architecture fits. Compose an original surface from layout primitives when the brief needs a different structure; a shell resemblance score is not a quality score.
+
+9. **Audit the app against the contract:** `npx sable-lint` (lints `./src`; `--rules` lists the rules, `--ignore <glob>` skips paths). It reads the token vocabulary from the **installed** package's `registry.json`, so upgrading Sable moves the linter with it. Exits 1 on any violation — put it in the build script. Scope: a lexical pass over class strings, catching the drift Tailwind silently no-ops and `tsc` cannot see. It is not a type checker, and it does **not** know whether your code still matches a pattern you copied (see "Promoting from an app").
+
+10. **Build with a brief and a learning loop.** `npx sable docs designing-a-surface` covers purpose, story, visual direction, interaction, and adaptation. `npx sable learn --search "editorial hierarchy"` retrieves conditional precedents from the installed package and project-owned `.sable/lessons/`. `npx sable grade --template` supplies an evidence review record; `npx sable docs reviewing-a-design` explains the rendered checks. Record a useful discovery with `npx sable learn --template` and `--record <file.json>`. Local records survive package upgrades and remain provisional observations. Neither source conformance nor a complete evidence record independently proves taste.
+
+For a substantial new visual direction, read `sable docs developing-taste`. If the project keeps a
+visual atlas (`.sable/atlas/`), use `sable atlas --search "<context>" --contrast
+--limit 3 --json`, then `--show <id>`, and actually view the returned capture paths. When meaningful alternatives need comparison, use bounded rendered
+directions with `sable explore`. Keep the factual brief and primary flow fixed.
+Retrieve `sable prefer --search "<decision>" --scope project:<id> --json` only in
+the applicable context. Record an actual user's judgment as human; agent choices
+remain agent observations. These tools improve context and process, not model
+weights, and no structural validator can certify taste.
+
+Full walkthrough: the package `README.md`.
+
+## Copy
+
+Sable ships a lot of canonical copy — pattern fixtures, meta examples, docs samples — and agents copy it verbatim into real products. That makes interface copy part of the contract, not decoration. These rules apply to every user-facing string the package ships.
+
+- **Sentence case everywhere** — buttons, headings, labels, menu items. Not title case. It is calmer, has no per-word case rules to get wrong, and localizes cleanly. "Save Changes" sitting beside "Discard changes" reads as sloppiness, and mixed casing is how that happens.
+- **Buttons name the verb, not the answer.** "Delete this project?" offers `Delete project` and `Cancel` — never `Yes`/`No`. A confirmation repeats the consequence so the button still makes sense to someone who skipped the sentence. (`DestructiveActionModal` already defaults this way; it is the pattern, not an exception.)
+- **Toggles describe the ON state.** "Send read receipts", never "Don't send read receipts" — a negated label plus an off switch is a double negative the reader has to solve.
+- **Links name their destination.** Never "Click here". Never five bare "Learn more" links on one page: suffix each — "Learn more about exports". This is also an accessibility rule, because screen readers can list links out of context.
+- **Errors say how to fix it, next to what broke.** "Use only letters for your name", not "Invalid name". "Unable to save. Check your connection and try again.", not "Oops! Something went wrong." No blame, no "oops", no exclamation marks, and phrase the hint as the thing to do rather than the thing that failed.
+- **Never concatenate fragments around a variable.** `"You have " + n + " messages"` cannot be translated — word order and pluralization differ per language. Ship one templated string per plural form.
+- **One vocabulary per flow.** Pick "Continue" or "Next" and use it for every step; two words for one action reads as two different actions.
+- **Tone flexes with stakes.** Warm for success and onboarding; neutral for routine work; calm, plain and entirely unplayful for errors and destructive confirmations; serious for anything touching data loss, billing, or security. A joke in a delete dialog is a bug.
+
+## Conventions
+
+- **`cn()`** is the single class merger; it knows the paired typography group, so `cn("text-heading-1", "text-body-md")` dedupes correctly.
+- **Dark by default.** Build dark first; light is the counterpart.
+- **Accessibility floor:** WCAG AA. Base UI provides behavior; don't strip its ARIA/roles.
+- **Never** introduce a new external font or a hard icon dep. Never write `oklch()`/hex inline.
+- **Logical properties for direction-dependent position.** `ms-*`/`me-*`/`ps-*`/`pe-*`/`text-start`/`inset-inline-*`, not `ml-*`/`pr-*`/`text-left`/`left-*`. Flex and grid mirror for free under `dir="rtl"`; hand-positioned elements do not. Reserve physical properties for genuinely physical geometry — `SafeArea`'s notch edges are physical and stay that way. `sable-lint` flags it.
+- **Text containers size to the text, not to English.** No fixed width sized to an English label and no fixed height on a text container — `max-width` plus wrapping, and `min-height` as a floor. Buttons take their width from `padding-inline`, never a hardcoded `w-[…]`. German and Finnish routinely run 30–50% longer than English, and a translated string that doesn't fit is a layout bug shipped to everyone but the language it was designed in.
+- **A decorative layer over interactive content takes `pointer-events-none` and `aria-hidden`.** Scrims, glows, gradient films and edge fades paint over live controls; without it the control looks live and does nothing, which is invisible in review and obvious to a user. A scrim the user *clicks to dismiss* is a control, not decoration, and keeps its events.
+- **Text inputs never render below 16px on mobile.** iOS Safari zooms the page on focus under that threshold, which yanks the viewport mid-form. The field components handle this themselves; a consumer building a custom field must too.
+- **Prefer the CSS property over the raw font axis tag.** `font-weight`, `font-variant-numeric: tabular-nums`, `font-variant-numeric: slashed-zero` — never `font-variation-settings: "wght"` or `font-feature-settings: "tnum"`. Raw tags silently do nothing on a fallback font, and every Sable theme declares a fallback stack.
+- **Pair `text-wrap` to the job.** `balance` for headings (short, few lines), `pretty` for ledes and descriptions (kills the orphan), neither for long-form prose — browsers stop balancing past a few lines anyway. `text-body-lg` carries `pretty` already.
+
+### The form submit contract
+
+Base UI wires `aria-invalid`/`aria-describedby` when you use `Field`; the behavior around it is ours and is easy to get wrong:
+
+- Keep submit **enabled** until the request actually starts. A disabled submit button hides *why* it's disabled; validate on submit and say what's wrong instead.
+- On submit failure, move focus to the first invalid field. A user who can't see the page has no other way to find it.
+- While the request is in flight, disable and show the spinner but **keep the label** — a button that becomes a bare spinner loses what it was doing.
+- Never block paste, on any field. Blocking paste on a password or code field breaks password managers and helps nobody.
+- Get the keyboard right: `autocomplete="one-time-code"` for OTP, `new-password` vs `current-password` (never both as `password`), `type="text" inputmode="numeric"` for codes and card numbers (never `type="number"`, whose spinners and scroll-to-change are wrong for an identifier), and `spellcheck="false"` on emails and codes.
+
+### Announcing and focusing
+
+- **A live region must exist before it has anything to say.** Render `role="status"` empty from the start and swap its text; a polite region inserted *together with* its content is announced inconsistently or not at all. In order of preference: move focus > `aria-describedby` on the control > `role="status"` > `role="alert"` (which interrupts, so reserve it).
+- **Client-side navigation is a11y-invisible unless you make it visible.** On route change, update `document.title` most-specific-first, move focus to the new view's `h1[tabindex="-1"]` (or `#main-content`), and restore scroll on back/forward. Base UI can't own this and `AppShell` only supplies the skip link and landmark — the app has to do the rest.
+- **Verify focus rings and disabled states under `forced-colors: active`.** Windows High Contrast overrides `ring-ring` and erases opacity-based disabled styling, which is exactly how Sable expresses both. Never reach for `forced-color-adjust: none` to "fix" it.
+
+## The Sable agent skill
+
+After installing Sable, run `pnpm exec sable setup --agent` in the target
+project. It installs discoverable entry files in `.agents/skills/sable` for
+Codex/Cursor and `.claude/skills/sable` for Claude Code; `--target` selects a host.
+Each entry resolves `skills/sable/SKILL.md` from the installed package, so package
+upgrades also update the workflow. Other agents can read that file directly.
+Use `$sable build <idea>`, `inspire <references>`, `audit <target>`, or
+`polish <target>` in Codex; use `/sable` with the same modes in Claude Code or
+Cursor. `create` is a build alias. These are agent modes, not shell commands.
+
+Upgrade with `pnpm update @sableui/react --latest`, then
+`pnpm exec sable setup --agent --update`. Setup only replaces managed files
+that have not been locally edited; `--dry-run` checks without writing. Keep
+project preferences in project instructions. Package installation alone does not
+change agent settings. See [building-with-sable.md](./llms/tasks/building-with-sable.md),
+[creating-a-preset.md](./llms/tasks/creating-a-preset.md), and
+[using-presets.md](./llms/tasks/using-presets.md).

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# What's new
+
+## 0.1.1
+
+- Published with npm trusted publishing: releases come from `sableui/sable`'s
+  release workflow with provenance and no stored token. No library changes.
+
+## 0.1.0 — first public release
+
+Sable is on npm as `@sableui/react`: `pnpm add @sableui/react`. No registry setup
+or token is needed. Follow the [installation guide](/getting-started) to wire
+React, Tailwind CSS 4 and the stylesheet.
+
+### Components and layout
+
+- About 100 components on Base UI behavior: forms, selection, menus, dialogs and
+  sheets, data display, tables, navigation, feedback, messaging, media and
+  workspace tools. Every example on the site is built from Sable's own components.
+- 13 layout primitives and 8 page patterns (auth, dashboard, feed, settings,
+  list–detail, landing, brand landing, chat).
+- Semantic tokens for color, type, spacing, shape, surfaces and motion; spacing
+  follows the density control, and motion honors reduced-motion settings.
+- `styles.css` paints the page ground on `<html>`, so dark mode is readable from
+  the first render.
+
+### Six presets
+
+- **Base:** neutral surfaces, soft corners, and Figtree typography.
+- **Meridian:** cream and ink, square panels and buttons, and flat surfaces.
+- **Prism:** compact spacing, IBM Plex typography, crisp corners, and blue actions.
+- **Verdant:** forest tones, warm paper, and serif headings.
+- **Ember:** warm surfaces, light headings, and orange-red actions.
+- **Poppy:** bold headings, cream and plum, rounded panels, and offset shadows.
+
+Every preset supports light and dark modes. Try them on the homepage or tune them
+in the canvas, then download a portable preset or copy its CSS.
+
+### Build with your agent
+
+- One package-owned skill for Codex, Claude Code, Cursor and compatible agents:
+  build an idea, develop a preset from inspiration, audit existing work, and
+  polish the result. Run `pnpm exec sable setup --agent` to install it.
+- The `sable` CLI serves the catalog in pieces (components, patterns, tokens,
+  utilities, guides), checks a project's wiring with `sable doctor`, and lints
+  with `sable lint`, which catches restyled components, hand-built lookalikes,
+  raw colors and fixed spacing.
+- Presets are portable files the package validates and turns into scoped CSS.
+
+### iOS prototypes
+
+- Optional `@sableui/react/ios` for clickable iPhone prototypes: screens are Sable
+  components in your preset, inside iOS chrome (status bar, navigation bar, tab
+  bar, sheets) drawn by Konsta UI, an optional peer installed only for iOS.
+- `sable target ios` gives each component's decision; `sable-lint` flags direct
+  Konsta imports. `@sableui/react/ios/preview` frames a prototype at iPhone size.

package/CONTRIBUTING.md

@@ -0,0 +1,221 @@
+# CONTRIBUTING.md — @sableui/react
+
+Rules for changing **this package**. Building an app *with* Sable? Read [`AGENTS.md`](./AGENTS.md) instead — it is the consumer contract and is all an agent building with Sable needs. Design rationale lives in [`DESIGN.md`](./DESIGN.md); the typed foundations rules (typography, motion, spacing, shape, surfaces, accessibility) live in `src/foundations/` and are served as `sable docs <topic>`.
+
+The checks are the specification. Every rule below names the gate that enforces it; when prose and a gate disagree, the gate wins and the prose is the bug.
+
+## The six hard rules
+
+> **These are enforced, not honor-system.** `pnpm design-lint` (`scripts/design-lint.mjs`, also a CI gate) fails the build on the drift below. A genuine rare exception needs an *auditable* comment that **requires** a reason: `// design-lint-disable-next-line <ruleId> -- <why>` (also `-line`, and block `disable`/`enable`). A disable with no reason is itself an error. Full table: `DESIGN.md → Enforcement`.
+
+1. **Components reference semantic tokens only.** Use `bg-card`, `text-muted-foreground`, `bg-tone-edition`, `text-primary`, etc. — never raw palette steps (`--purple-heart-700`) and never inline `oklch()`/hex. For text/icons on a tone fill use the theme-adaptive `text-tone-*-foreground` ink (no `dark:` variant); for scrims, media letterbox, and pills on imagery use `bg-overlay`/`text-overlay-foreground`. Palette names are theme-internal; a component that names a palette breaks themeability — and `design-lint`'s `palette-ref` rule now has **zero** sanctioned exceptions.
+2. **Paired typography utilities, never decomposed.** Use `text-heading-1`, `text-body-md`, `text-label-lg`, … Each bundles size + weight + line-height + tracking. Do **not** combine `text-{size}` + `font-{weight}` + `tracking-{x}` by hand. (Icons are the exception — size them with `text-{size}` scales, never type utilities.)
+3. **Base UI is behavior; `components/` is the public API.** Each component wraps `@base-ui/react` directly inside its own folder (use the **`render` prop** for composition; read state from `data-[state=…]` attributes) and owns 100% of the styling. There is no separate primitives tier. Consumers import only from the package root barrel.
+4. **Semantic icons in components.** Use `<Icon name="…">`; Reicon is the default. Concrete icon-package imports belong only in `src/icon-sets/`. Apps may override or extend the set through `<IconProvider>`.
+5. **Every scroll container declares a scrollbar policy.** An `overflow-*-auto|scroll` utility must be paired with `scrollbar-quiet` (a 4px thumb, invisible at rest, fading in while the region scrolls) or `scrollbar-hidden` (no bar — only when something else carries the affordance, and you should be able to name it). Left bare, the platform draws its own: on Windows that means stepper arrows hard against the padding edge, poking out of any rounded corner. Vertical scrolling takes a bar; **horizontal takes none** — an edge fade says "there is more this way" better than a rail does, which is why `Scroller` splits by axis. New scroll container? Reach for `useScrollActivity` so the bar appears on touch drags and programmatic scrolls, which hover cannot see. Enforced by `design-lint`'s `unmanaged-overflow` **and** by `build-registry` over every registry example. Full rationale: `DESIGN.md → Scrolling`.
+6. **Tailwind v4 packaging discipline.** `src/styles.css` must **not** `@import "tailwindcss"` (the consumer owns that). It carries only token blocks, `@theme inline` mappings, `@utility` typography, layout vars, and `@source`. `@source` points at `src` (never the gitignored `dist`).
+
+**Variants, not overrides — and spacing on the scale.** A component's look comes from its variants, never from override classes a caller (or another component) passes in, and its own padding moves with density. Gated by:
+
+- `component-restyle` — `border*` / `bg-*` / `rounded*` / `ring-*` / `shadow-*` in a `Button`, `Pill` or `Badge` `className`. Use or add a variant (Button `floating` for a control over content). Layout classes are fine.
+- `destructive-item-ink` — `text-destructive` (or a tone ink) on `MenuItem` / `ContextMenuItem`. Use `variant="destructive"`.
+- `table-edge-padding` — `pl-*` / `pr-*` / `ps-*` / `pe-*` on `TableHead` / `TableCell`. Use `CardContent flush` (it sets `--table-edge-px`).
+- `popup-separator-bleed` — a fixed `-mx-*` on a popup separator. Use `popup-bleed`.
+- `fixed-spacing` (package only) — a `rem`/`px` padding, margin, gap or inset (`p-[1.5rem]`, `padding: "12px"`, `"--card-p": "1.5rem"`). Write a step or `--spacing(n)`; hairlines, em values and positional offsets are exempt.
+
+## File structure
+
+```
+src/
+  index.ts                 # public barrel — the only consumer entry
+  styles.css               # CSS entry: theme import + @theme map + @utility typography + layout vars + @source
+  lib/cn.ts                # cn() = clsx + tailwind-merge (with ds-typography paired-utility group)
+  themes/
+    _contract.ts           # SemanticTokens — the token names every theme MUST define
+    registry.ts            # public theme manifests, ids, and attribute helpers
+    theme-provider.tsx     # SableThemeProvider + useSableTheme for app theme switching
+    <id>/                  # one folder per theme: <id>.css (:root/.dark vars) + index.ts (TS manifest) + art-direction.md
+  foundations/             # the typed rules (typography, motion, spacing, shape, surfaces, a11y) → docs pages + llms/foundations/*.md
+  layout/                  # fluid grid/layout primitives: Region, Grid, Columns, Stack, Row, Spacer, Center, AspectBox, Bleed, SplitPane, Page, SafeArea, GridOverlay
+  icon/                    # Icon, IconProvider, IconRegistry — the semantic adapter and provider overrides
+  motion/                  # owned zero-dep motion layer: MotionProvider, useMotion, useReducedMotion, Presence, Reveal, TextReveal, useInView, View Transitions
+  components/<name>/        # <name>.tsx + <name>.variants.ts + <name>.meta.ts + index.ts
+  patterns/<name>.tsx       # canonical page shells (+ <name>.meta.ts) — see "Patterns"
+```
+
+## How to add a component (the recipe)
+
+The maintained agent workflow is `skills/sable/SKILL.md` in this package. Update
+its task guides under `llms/tasks/` alongside library changes. Repository and
+consumer agent directories contain entry files that resolve this canonical
+source; do not fork the workflow into host-specific skills. `skills/entry/SKILL.md`
+is the portable loader template; `scripts/agent-setup.mjs` installs and manages it.
+Verify setup/update/local-edit protection and the packed consumer when changing
+the installer. User-defined presets belong to apps, not the bundled theme registry.
+
+1. If it needs non-trivial behavior (overlay, focus trap, keyboard nav), wrap the Base UI part inside the component folder — never re-implement focus management Base UI already owns.
+2. Create `components/<name>/<name>.variants.ts` — a `cva()` over **semantic tokens**.
+3. Create `components/<name>/<name>.tsx` — the themed component composing the primitive + variants + `cn()`.
+4. Create `components/<name>/<name>.meta.ts` — machine-readable metadata (see "Component meta").
+5. `components/<name>/index.ts` re-exports; add to the root `src/index.ts` barrel.
+6. File it in `src/lib/taxonomy.ts` and add a docs page at `apps/docs/src/pages/components/<Name>Page.tsx` with live examples (the build fails without both).
+7. Gate: `pnpm design-lint` clean, `pnpm registry:check` in sync (regenerate with `pnpm build:registry`), package `tsc` clean (`pnpm --filter @sableui/react typecheck`), `pnpm test` green, and the docs app renders it in light + dark. (Tooling runs on **Node 22** — the registry generator imports the `.meta.ts` files via Node's built-in type-stripping.)
+
+## Registers & density
+
+The optional `src/ios/` adapter is outside the core component catalog. It wraps
+Konsta for iOS system chrome only (app frame, navigation bar, tab bar, sheet
+presentation); it must never export a control Sable already has. Keep Konsta external and optional;
+neither the root barrel nor the `ios/preview` entry may import it. Chrome reads
+the preset through `ios/styles.css`; keep that mapping, and the geometry pins on
+Konsta chrome, in CSS rather than per-app.
+Native geometry follows the iOS target contract rather than web density. Both
+docs examples must consume the published adapter instead of maintaining local
+copies. Verify the packed web consumer without Konsta, then the opt-in native
+consumer with it, alongside the two interactive demos.
+
+Sable has **two registers** — the page register (default) and the workspace register for
+tool chrome. Full doctrine, the measured numbers, and the two rules the workspace register
+deliberately reverses: `DESIGN.md → Registers`. What a contributor needs to know:
+
+1. **Never hardcode a control height.** Size variants read the ladder —
+   `h-(--control-md)`, `h-(--control-xs)` — never `h-[40px]`. A `data-density` scope
+   redefines the ladder, so one attribute retunes every control at once and nothing has to
+   override a height after the fact. CI-enforced (`raw-control-height`); the rule only
+   flags the ladder's own values, so a genuine non-control measure (a gauge diameter, the
+   WCAG touch floor) is a real exception — disable it with a reason.
+2. **`--control-*` values are set in `styles.css`, not per theme.** Density is a register
+   concern, not a palette one. A theme *may* override them (same status as
+   `MOTION_TOKENS`/`RADIUS_TOKENS`) but doesn't have to.
+3. **Workspace surfaces are derived.** `canvas` / `panel` / `panel-raised` / `hairline`
+   come from each theme's existing semantic tokens via `color-mix`, with a `--theme-*`
+   override hook. Don't hand-author them per theme.
+4. **Paired type tiers must be registered in `lib/cn.ts`.** Adding a `@utility text-foo`
+   without adding `"foo"` to `dsTypographyTokens` means tailwind-merge treats it as a
+   **colour** utility and silently drops the real colour class — a shipped bug once (white
+   text on a white button) and invisible in review. `themes.test.ts` asserts every
+   `text-ui-*` tier is registered.
+5. **Tool chrome components go in the workspace family**, not into `AppShell`'s: `Workspace`,
+   `PanelGroup`, `PanelSection`, `ScrubField`, `StatusBar`, `Tree`. `SplitPane` stays
+   page-register (responsive, not resizable) — the two are deliberately separate. `Tree`
+   is the one hierarchy, for a layers panel and a file listing alike.
+6. **Never compute a tree inset.** Rows, section headers, add affordances and empty states
+   all read `treeIndent(depth)` or `var(--tree-rail)`. And `--tree-indent` must always equal
+   `--tree-column`: a smaller step puts a child's content left of its parent's and the
+   nesting reads inverted. Asserted in `themes.test.ts` for both densities.
+7. **A new component must be filed in `lib/taxonomy.ts` and have a docs page.** The
+   taxonomy declares a **group** (role) and a **register** (`page` / `workspace` /
+   `either`), and `build-registry` fails on a component missing from it, a stale entry
+   naming a component that no longer exists, or a component with no
+   `apps/docs/src/pages/components/<Name>Page.tsx`. The grouping used to live only in the
+   docs nav array, which is exactly how `PanelGroup`, `PanelSection`, `ScrubField` and
+   `StatusBar` shipped in 0.31.0 unfiled and undocumented and stayed that way for four
+   releases. The docs nav is now generated from the contract, so the two cannot drift.
+   **Group by KIND, not by co-occurrence** — see the note in `taxonomy.ts`: the
+   `related.components` graph tracks composition as much as kinship, and grouping by it
+   measurably made things worse when tried.
+
+## Theme contract
+
+A theme is a CSS file that defines every token in `themes/_contract.ts` for `:root` (light) and `.dark` (dark), plus an optional TS manifest. Components depend on the **semantic** layer; each theme supplies its own palette underneath. Alternate themes activate through the root `data-sable-theme` attribute; consuming apps should usually let `<SableThemeProvider>` own that wiring and read/update it through `useSableTheme()`. To make a new theme: copy `themes/base/`, swap the palette + semantic values, keep the token names identical, add the manifest to `themes/registry.ts`, import its CSS from `src/themes.css`, add `./theme/<id>` + `./theme/<id>.css` to both `exports` and `publishConfig.exports`, and cover it in `themes.test.ts`. `build-registry` fails on a theme missing from any of those, and generates `registry.json → themes.available` from the manifests — never hand-edit that list. Re-skinning never touches component code.
+
+**Themes are presets, not the unit of customization.** Every token a theme sets can also be set by an app (or by the docs customizer) on `:root` after the theme loads. A theme is the starting point a consumer picks; the customizer exports the deltas on top of it. Keep that working: a theme must not set a token with `!important` or under a selector more specific than `[data-sable-theme="<id>"]`, or a consumer override cannot win.
+
+`_contract.ts` exports five token groups: `SEMANTIC_TOKENS` (colors — **light + dark**, e.g. `--background`, `--primary`, `--tone-edition`), `MOTION_TOKENS` (duration/easing ladder), `RADIUS_TOKENS` (the 7 `--theme-radius-*` steps bridged to Tailwind's `radius-*` scale), `TYPE_SCALE_TOKENS` (display/heading/title size, weight, leading, and tracking vars consumed by the paired `text-*` typography utilities in styles.css), and `TYPE_OVERLINE_TOKENS` (the small, uppercase, letter-spaced eyebrow/overline/kicker tier — size/weight/leading/tracking/transform — consumed by the `text-overline` utility). `MOTION_TOKENS`, `RADIUS_TOKENS`, `TYPE_SCALE_TOKENS`, and `TYPE_OVERLINE_TOKENS` are **mode-independent** — declared once per theme (not duplicated under `.dark`), unlike `SEMANTIC_TOKENS`.
+
+`TYPE_REFINEMENT_TOKENS` additionally exposes optional typography hooks for body,
+label, caption, mono, title sizes, and the largest display size. Retrieve
+`sable token typographyOverrides` for their intent. These preserve paired utilities
+while allowing a consumer to tune the whole type system, rather than making only
+headings reflect its art direction. Existing defaults remain the fallback; themes
+do not need to declare every optional hook.
+
+`SEMANTIC_TOKENS` includes `border-strong` alongside `border` — a visually-stronger structural divider (grid lines, table rules, section separators) distinct from `border`, which stays tuned for subtle chrome (badge/input outlines). Both need light + dark values, derived from the same neutral ramp as `border` but pulled from a higher-contrast step (e.g. Base: `border` = `--zinc-200` light / low-alpha `--zinc-700` dark → `border-strong` = `--zinc-300` light / higher-alpha `--zinc-500` dark). `styles.css`'s `@theme inline` block maps it to `--color-border-strong`, so components/consumers use it via the `border-strong` Tailwind color utility, same pattern as `border`.
+
+`TYPE_OVERLINE_TOKENS` (`type-overline-size/weight/leading/tracking/transform`) back the `text-overline` utility — the eyebrow/badge-label/stat-caption text role with no home in `TYPE_SCALE_TOKENS`'s display/heading/title ramp. `type-overline-transform` is themeable rather than a hardcoded `uppercase`, so a quieter reference (e.g. Cove) can opt into sentence case. Like the other type tiers, every built-in theme declares explicit values rather than relying on styles.css's fallback defaults (`0.75rem` / weight `600` / leading `1.2` / tracking `0.08em` / `uppercase`).
+
+The manifest's `fonts` field is `{ sans: string; mono: string; display?: string }` — `display` is **optional**, for a theme whose reference uses a distinct display/headline typeface separate from its body sans (e.g. a Chalet-style display face over an Instrument Sans body). When a theme sets `display`, its CSS also defines `--font-display` (alongside `--font-sans`/`--font-mono`) in the same `:root, [data-sable-theme="…"]` block. styles.css's `text-display-*` and `text-heading-*` utilities read `font-family: var(--font-display, var(--font-sans))` — a theme that omits `display`/`--font-display` falls through to `--font-sans` and renders identically to before this field existed. `text-title-*`/body-register utilities are unaffected and keep inheriting `--font-sans` only.
+
+## Icon contract
+
+Components reference semantic names through `<Icon name="…" />`. Reicon (MIT)
+is the default, installed as a runtime dependency and kept external to the build.
+Concrete icon imports belong only in `src/icon-sets/`; components never import
+an icon package or duplicate its SVG artwork.
+
+- **Use the default:** render components without an icon provider.
+- **Replace the package:** pass your own `IconSet` to `<IconProvider set={mySet}>`.
+  Map semantic names to that package's components; preserve className, variant,
+  spin and accessible labels. Return `null` for unknown names.
+- **Extend Reicon:** import `composeIconSets` and `reiconIconSet` from Sable and
+  use `<IconProvider set={composeIconSets(appExtras, reiconIconSet)}>`.
+  The first set returning a non-null node wins.
+- `@sableui/react/icons/reicon` remains an alternative import for the same adapter.
+  `fallbackIconSet` is a deprecated alias of Reicon, with no separate artwork.
+- Brand marks are a separate additive set at `@sableui/react/icons/brands`.
+  The 23 marks are generated from licensed `reicon-brands` npm artwork by
+  `pnpm icons:brands`, normalized to the 24-unit grid, and inherit currentColor.
+  Their MIT notice is shipped; trademark usage remains subject to each brand's rules.
+- Coverage tests enforce that Reicon maps every contract name and no others.
+  All interface glyphs, including tree controls and the color eyedropper, use Icon.
+  Progress meters and animated loading indicators remain component visuals.
+
+## Motion
+
+Motion is a first-class layer — **subtle by default, tasteful spring welcome, zero runtime dependency** (CSS tokens/recipes + tiny browser-native JS). When a component has any interaction, wire it to the system; don't leave it static or hand-roll a transition.
+
+**Four slots.** Every component answers all four — by filling the slot, or by declining it in `meta.motion` with `recipe: "none"` and a reason:
+
+| slot | the question | typical fill |
+|---|---|---|
+| `arrival` | how does it enter? | `motion-fade` · `motion-slide-*` · `motion-pop` · `Reveal` |
+| `response` | what happens under the pointer? | `motion-interactive` · `motion-press` |
+| `transition` | how does it move between its own states? | `motion-disclosure`, or ease the transform |
+| `activity` | how do you tell "working" from "frozen"? | `motion-spin` · `motion-pulse` · `motion-shimmer` |
+
+This paragraph said "don't leave it static" for many releases while **nothing checked it**. The four motion rules below are all prohibitive — they fire on motion that is present and wrong, and none can fire on motion that is absent — so a component that snapped between every state passed the whole contract, and motion stayed a thing a human had to request by name. Two gates now close that: `static-interactive` (lint, fires on an element styled for pointer states with no recipe on it) and `meta.motion` + `pnpm build:registry -- --motion-report` (declaration and coverage).
+
+1. **Reach for a recipe first** — apply one named class instead of a bespoke transition string: `motion-interactive` (default hover/focus/press chrome — **replaces** `transition-colors`), `motion-press` (tactile press; always pair with `motion-interactive`), `motion-fade`/`motion-pop`/`motion-slide-{up,down,left,right}` (overlay enter/exit, on Base UI `data-[starting-style]`/`data-[ending-style]`), `motion-disclosure` (height), and loaders `motion-{spin,shimmer,pulse,dot-bounce,ping}`.
+2. **Drop to tokens only when a recipe doesn't fit.** Durations via `duration-(--motion-duration-{instant|fast|base|slow|slower})` — **never** a raw `duration-150` (it bypasses the kill-switch). Easings via `ease-{standard|decelerate|emphasized|spring|bounce}`. Spring/bounce overshoot is **enter-only**; exits stay clean.
+3. **Never** use Tailwind's built-in `animate-spin`/`animate-pulse`/`animate-ping`/`animate-bounce` — they ignore `--motion-scale`, so the on/off policy can't freeze them. Use the scale-aware `motion-*` loader recipes.
+4. **Compositor-first & subtle:** animate opacity + transform (scale/translate) only; short durations; no exit overshoot; no gaudy motion.
+5. **Policy:** all token-driven motion collapses to static under `prefers-reduced-motion` or `<MotionProvider>` off (one `--motion-scale: 0`). JS primitives read `useMotion().enabled` and must no-op when motion is off.
+6. **JS motion lives in `src/motion/`** (zero-dep, browser-native: WAAPI / IntersectionObserver / View Transitions). Do **not** add the `motion` library to core — drag/gesture, FLIP layout, and velocity springs are the future optional `@sableui/motion` adapter (peer-dep `motion`).
+
+Full token table + rationale: `DESIGN.md → Motion`. Live demo: docs → Foundations → Motion (also the on/off toggle).
+
+## Patterns (canonical page shells)
+
+`src/patterns/` holds full-page compositions for common routes. They ship two ways:
+**importable previews** (`import { SettingsPage } from "@sableui/react/patterns"`)
+and **copy-pasteable source** (`registry.json → patterns`, imports included).
+Inspect them before choosing composition. Reuse and diverge when the information
+architecture fits; compose an original route from layout primitives when it does
+not. The brief determines the result, not resemblance to an existing shell.
+
+The **source is the contract**: each pattern is real TSX (typechecked, design-linted, rendered live by the docs app), split as `<name>.meta.ts` (a `PatternMeta`: name/summary/intent/notes/a11y) + `<name>.tsx` whose code after the `// ---pattern-code---` marker is emitted verbatim into the registry by `build-registry.mjs` — so the shipped recipe can never drift from code that compiles. Keep patterns hook-free and self-contained (inline sample data, `<a href>` for links); the generator auto-derives the consumer import block. To add one: write the pair, export both from `src/patterns/index.ts`, regenerate the registry, and add it to the docs `PatternPreview` map.
+
+## Promoting from an app (and the drift back down)
+
+The system grows **out of the apps**, not ahead of them. A component earns its way in by being built in a consuming app first, measured in place, and only then lifted here — which is how the workspace register (v0.31.1, out of Glitch's tool chrome) and `Tree` (v0.32.0, out of Glitch's layers list) landed. Both deleted more app code than they added: Glitch's `globals.css` went 229 → 49 lines and its local `components/workspace/` disappeared. That deletion is the signal you're promoting something real rather than relocating it.
+
+**The route up.** Build it in the app. Measure the actual numbers in the running product — control heights, radii, type sizes at their real weights (`DESIGN.md → Registers` is what measured numbers look like written down). Then promote with three things, none optional: **tokens** (so the geometry is retunable, never hardcoded), **a contract test** (so the invariant you discovered can't silently break — `Tree`'s is `--tree-indent` must equal `--tree-column`, because a smaller step renders nesting *inverted*), and **a docs page that reproduces the bug you hit**, so the next agent meets the failure before they meet the fix.
+
+**The over-fit check.** One consumer proves a thing works; it does not prove the shape is general. Before promoting, write down which parts you expect a *second* consumer to need — those predictions are the point, and whichever fail are the over-fits to the first app. When only one consumer exists, say so and prefer the narrower API; widening later is cheap, and unwinding an abstraction shaped around one app's accident is not.
+
+**The drift down is not automatic, and nothing detects it.** Components live in the package, so an upgrade delivers them. **Patterns are copy-in** — the moment an app adapts one it stops tracking, and no tooling notices. `sable-lint` is a lexical token linter (see "Consuming this package"); it has no idea a given file was ever meant to follow a pattern. So when a pattern changes here, the consuming app needs a deliberate read-and-diff: `CHANGELOG.md`, the pattern's `llms/patterns/<name>.md`, and the current implementation, side by side. Most of the work is usually small, because patterns are mostly *composition* over components the app already got on upgrade — what the app misses is the **wiring**, which component to reach for and how to connect it (0.56.1's ChatPanel is the example: the streaming behavior shipped in `StreamingText`; the pattern only showed how to drive it from one `pending` flag).
+
+## Component meta (the AI-readable surface)
+
+Each component ships `<name>.meta.ts` exporting a `ComponentMeta` object: `name`, `summary`, `keywords`, `usage` (intent, do/don't guidance, anatomy), `related`, `props` (name/type/default/description), `subcomponents`, `variants`, `tokensUsed` (semantic tokens it reads), `a11y` notes, and `examples` (label + code). Inline meta is the preferred **source of truth** and the contract other agents read; keep it in sync when you change a component. Existing guidance backfills may also live in `src/lib/component-guidance.ts`; the docs and registry generator merge that overlay so consumers read one resolved catalog.
+
+`usage.bestPractices` is where design judgment lives. Include concrete "do" and "dont" items that teach agents when to reach for the component, when to choose a neighboring component instead, and which visual/interaction anti-patterns to avoid. For composite components, include `usage.anatomy` so agents understand the required parts and slots before composing JSX.
+
+Two rules that keep the contract unambiguous for consumers reading the registry:
+
+- **Stable components ship guidance.** A stable component needs `keywords`, `usage.description`, at least one `usage.bestPractices` "do" item, at least one "dont" item, and `usage.anatomy` when it exposes `subcomponents`. `build-registry.mjs` enforces this against the resolved inline-plus-overlay metadata.
+- **`props` holds the root's props only.** Composed child components (SelectItem, ProgressTrack, …) go in `subcomponents` — a capitalized entry in `props` reads as a prop-object API (`<Progress ProgressTrack={{…}}/>`) and misleads agents.
+- **Every composite shows its composed form.** A meta with `subcomponents` must include at least one example whose code uses them as JSX children — the shape of the API must be visible in the examples, not only in prose.
+- **Examples are complete, copy-pasteable code.** The generator **fails** on an example that elides its content (`>…<`) or references a component the package doesn't export (a phantom like `<NetworkBanner>`); components consumers genuinely supply (a router `<Link>`) live in the generator's `EXTERNAL_COMPONENTS` allowlist. Every emitted example carries an auto-derived `imports` block — don't hand-author imports in meta code.
+
+`registry.json`'s `components[]` (with each component's full props/variants/examples) is **generated from the metas** by `scripts/build-registry.mjs` — do **not** hand-edit it. `pnpm build` regenerates it; CI runs `pnpm registry:check` (`build:registry:check`) and **fails** if the committed file is out of sync, so the catalog can't silently drift. Adding a component is therefore: write its `*.meta.ts`, run the build (or `pnpm build:registry`), commit the regenerated `registry.json`. (The static blocks — `consume`, `tokens`, `enforcement`, `iconContract`, `layoutPrimitives` — are hand-authored and preserved by the generator.)