@sableui/react 0.0.0-stage → 0.1.0

package/llms/tasks/adding-a-component.md

@@ -0,0 +1,113 @@
+# Task: adding a component to Sable
+
+Contributing *to the library*, not consuming it. Every step below is enforced by
+`pnpm build:registry` or `pnpm design-lint` — the checks are the specification,
+so run them early rather than at the end.
+
+## The files
+
+```
+src/components/<kebab-name>/
+  <kebab-name>.tsx        the component
+  <kebab-name>.meta.ts    the machine-readable contract  ← the important one
+  <kebab-name>.test.tsx   behaviour, not snapshots
+  index.ts                named exports + the meta
+```
+
+Then: export from `src/index.ts` (the single public barrel), file it in
+`src/lib/taxonomy.ts`, and add `apps/docs/src/pages/components/<Name>Page.tsx`
+plus its route in `apps/docs/src/App.tsx`.
+
+## The meta is the deliverable
+
+`registry.json` is generated from it, and that catalog is what every agent reads.
+A component whose meta is thin is a component nobody can use correctly.
+
+Enforced minima — the build fails below them:
+
+- `usage.description` — why it exists and when to reach for it
+- **≥1 `do`, ≥2 `dont`, ≥2 examples, ≥2 a11y notes, ≥1 related component**
+- every prop described; `props` holds the ROOT's props only (a capitalised entry
+  that is not the root is a subcomponent hiding in `props`)
+- a component with `subcomponents` must show the composed JSX in an example
+- examples must be **complete and copy-pasteable** — no `…` elisions, no phantom
+  components, only on-contract `<Icon name>` values
+- `tokensUsed` entries must exist in the token contract
+
+A second `dont` must name a **different** failure, not restate the first. The
+highest-value guidance answers *which of these near-identical components do I
+actually want* — AppHeader vs PageHeader, Code vs CodeBlock (`prompt` for a
+command), Meter vs Progress.
+
+## Declare how it moves
+
+`meta.motion` answers four questions, one entry per slot. Fill the ones that
+apply and **decline the rest explicitly** — `recipe: "none"` with a `why`. Use
+`recipe: "custom"` when a rAF loop or canvas fills the slot and no CSS utility
+could (ThinkingOrb draws a point cloud per frame).
+
+| slot | the question |
+|---|---|
+| `arrival` | how does it enter, or does it belong to a layout that already staged it? |
+| `response` | what happens under the pointer? |
+| `transition` | how does it move between its own states? |
+| `activity` | what does it do while working, indeterminately? |
+
+The `why` states what the motion is *for* — what a reader would misread without
+it. `"motion-pop on the panel"` restates the recipe and teaches nothing; *"the
+transform-origin follows the anchor, so on a form with several selects in a
+column the origin is the only thing identifying which field the open list belongs
+to"* is the sentence worth writing, because it also tells the next person when
+**not** to copy it.
+
+This exists because every other motion rule is prohibitive — `raw-duration`,
+`builtin-animate`, `unknown-motion` all fire on motion that is present and wrong,
+and none of them can fire on motion that is absent. A component with no motion at
+all used to clear the entire contract, which is exactly what gets written when
+nobody is asked for it by name. `pnpm build:registry -- --motion-report` shows
+current coverage; `static-interactive` catches the element-level half in lint.
+
+## Taxonomy: two orthogonal axes
+
+`src/lib/taxonomy.ts` declares a **group** (role) and a **register**
+(`page` / `workspace` / `either`). Keep them separate: a register-based *group*
+was tried and made every workspace form control have two valid homes. Group by
+KIND, not by co-occurrence — the `related` graph tracks composition as much as
+kinship, and grouping by it measurably made cohesion worse.
+
+Guidance lives in the component's own meta. `lib/component-guidance.ts` is for
+the 13 layout primitives only; a component in both places fails the build,
+because the meta wins *whole* and silently discards the other.
+
+## The hard rules
+
+1. **Semantic tokens only** — never hex/oklch, never a raw palette step.
+2. **Paired typography utilities** — never `text-{size}` + `font-{weight}`.
+3. **`primitives/` is behaviour, `components/` is the public API.** Base UI is
+   wrapped and re-exported; consumers import only from the root barrel.
+4. **No icon library in the package.** `<Icon name>` resolves through the
+   injected provider. Two narrow amendments exist (`src/icon-sets/`, and
+   size-matched structural marks) — read them before assuming you qualify.
+5. **Tailwind v4 packaging discipline** — `src/styles.css` must not
+   `@import "tailwindcss"`.
+
+## Two failure modes that do not announce themselves
+
+- **A custom `text-*` utility unregistered in `lib/cn.ts`** lands in
+  tailwind-merge's *colour* group and silently evicts the real colour class. This
+  shipped white text on a white button. Register the tier, or do not name it
+  `text-*`. The same applies to `bg-*`.
+- **An unmapped icon name renders nothing** — no error, no warning.
+
+## Verify
+
+```bash
+pnpm typecheck && pnpm design-lint && pnpm build:registry && pnpm test:run
+pnpm build:registry -- --doc-report      # guidance depth, weakest entries first
+pnpm build:registry -- --motion-report   # motion slots: filled, declined, absent
+```
+
+## Read next
+
+- `CONTRIBUTING.md` — the hard rules, the recipe, theme + icon + motion contracts
+- `DESIGN.md` — the system spec, with intent and do/don't per layer

package/llms/tasks/auditing-an-app.md

@@ -0,0 +1,216 @@
+# Task: auditing existing work against Sable
+
+This is Sable's native contract-and-taste audit, used by `$sable audit <target>`.
+`$sable critique <target>` emphasizes design judgment. These are agent skill
+modes, not shell subcommands. No other design skill is required.
+
+## Establish the comparison basis
+
+Identify source paths, rendered routes, installed Sable version, audience, primary
+task, selected identity and supported device/color modes. Reuse the existing brief;
+label assumptions. For a whole app, inventory routes and shared controls, inspect
+each distinct layout and critical journey, and state which routes were sampled.
+Audit the installed version using its registry, AGENTS.md and DESIGN.md. Library
+contribution rules do not all apply to consumers: original themes, fonts, layouts
+and native elements are not automatically violations.
+
+An audit reports findings by default. An explicit "audit and fix" request already
+authorizes scoped repairs and verification. Do not automatically upgrade packages,
+migrate the app, change its identity, generate variants or alter CI for a review.
+Resolve the project's installed CLI before using `npx`; in this repository use
+`node packages/sable/bin/sable.mjs`. Below, `sable` means that resolved CLI.
+
+Inspect the interface before reading previous verdicts. Follow
+[reviewing-a-design.md](./reviewing-a-design.md) for desktop/mobile, full-route,
+keyboard, interaction and motion evidence. A screenshot-only critique leaves code
+and live behavior untested. Compare three layers explicitly:
+
+| Layer | Evidence and judgment |
+|---|---|
+| System contract | Component props/anatomy/states, semantic tokens, layout primitives, pattern intent, icons, motion and accessibility behavior. |
+| Taste and craft | Brief fit, hierarchy, typography, spacing/rhythm, color/material, imagery, story, interaction, motion and mobile composition. |
+| Learned context | Applicable human preferences, separately identified agent observations, conditional lessons and comparable previous builds. |
+
+If the project keeps a visual atlas, retrieve a close analogue and a useful
+contrast through `sable atlas --search "<audience and design problem>" --contrast
+--limit 3 --json`. Open useful entries
+with `sable atlas --show <id> --json` and actually inspect their images. Explain
+which relationships transfer; resemblance to Sable's default theme is not the goal.
+Use `sable prefer --search "<decision>" --scope project:<project-id> --json` in an
+applicable scope and `sable learn --search "<problem>" --json`. Agent preferences
+require explicit `--reviewer agent` retrieval and agent attribution. Empty memory
+is valid. When prior builds matter, inspect their actual captures for repeated
+compositions and range; state when comparison evidence is absent.
+
+Inventory imported Sable components, locally recreated controls, native elements,
+consumer tokens and repeated overrides. Query the installed catalog before
+recommending a replacement. Check the API, composed anatomy, supported states,
+keyboard/focus behavior, semantic token roles and motion policy. Explain which
+behavior a replacement gains and what must remain. An unused page pattern is not
+drift; repeated overrides can indicate a missing system hook rather than app misuse.
+Run relevant `sable doctor`, `sable lint <paths> --json` and `sable grade <paths>
+--json` checks. Lint is lexical; source grades and pattern similarity do not judge
+taste. Deliberately static motion slots remain valid with appropriate feedback.
+
+## Deliver evidence-backed findings
+
+Save the audit under `design/<surface>/audit/` or the existing review location.
+Record source/version, routes/states inspected, commands, reference/memory IDs and
+untested areas. Use the source/artifact binding and review template described in
+[reviewing-a-design.md](./reviewing-a-design.md) for structured review records.
+
+For each finding, record location, observed consequence, severity, evidence,
+comparison basis, concrete repair, owner (app or Sable) and verification method.
+Distinguish **contract violation**, **taste/craft issue**, **intentional choice**
+and **Sable system gap**. Separate objective failures from agent judgments and
+suspected gaps from verified library defects. Keep component/token findings
+separate from visual quality; report the eight review dimensions as `pass`,
+`revise` or `untested`, never a fabricated premium score. Retain what already works.
+
+For authorized fixes, repair observed issues, run relevant checks and recapture
+affected states. Preserve before/after evidence and resolved/remaining findings.
+Use [reviewing-a-journey.md](./reviewing-a-journey.md) for connected flows and
+[reviewing-motion.md](./reviewing-motion.md) for temporal behavior. Save useful
+conditional lessons through [learning-from-builds.md](./learning-from-builds.md).
+Completing an audit supplies no human preference and does not authorize inventing
+or automatically saving one.
+
+## Additional checks after an upgrade
+
+An app converted to Sable is correct against the contract *as it stood on the day
+it was converted*. The contract keeps moving — new rules, new components,
+deprecations, new doctrine — and none of that reaches an app that merely has the
+package installed. This is the pass that closes the gap.
+
+Use the following drift checks after an actual upgrade, or when the user asks to
+compare versions. For an audit-only request, report suggested changes rather than
+performing the fixes or CI edits illustrated below.
+
+## The failure this prevents
+
+Enforcement travels with the package: `sable-lint` reads the token vocabulary and
+rule table out of the `registry.json` of the version you installed, so upgrading
+Sable silently widens what counts as a violation. That is the design — it means a
+new rule reaches every app without anyone republishing a checklist — but it has a
+predictable failure mode. An app upgrades, CI goes red, the findings are a mix of
+brand-new requirements and drift that has been sitting there for months, nobody
+can tell which is which, and the team pins the version. A pinned version is a
+contract that stopped applying.
+
+So audit in the order below: **find out what changed, then measure, then fix.**
+
+## 0. Know what moved before you look at your code
+
+```bash
+npx sable-lint --since 0.54.2      # the version you were on
+```
+
+`--since` lists only the rules added after that version, with the reason each
+exists. Everything else `sable-lint` reports is pre-existing drift — still worth
+fixing, but it is not what the upgrade did to you, and separating the two is what
+keeps the upgrade reviewable.
+
+For changes that are not lint rules, diff the catalog:
+
+```bash
+# Components that gained a deprecation, and what replaced them.
+node -e "const r=require('@sableui/react/registry.json');
+  r.components.filter(c=>c.status==='deprecated')
+   .forEach(c=>console.log(c.name,'→',c.supersededBy))"
+```
+
+Deprecation is structured, not prose — `status: "deprecated"` always carries
+`supersededBy`, and the build refuses a deprecation without a forward path. Grep
+your app for each name on the left.
+
+## 1. Run the linter, and read the new rules first
+
+```bash
+npx sable-lint                      # ./src by default
+npx sable-lint app components       # or pass your dirs
+```
+
+Fix the `--since` rules first: those are the ones your reviewers have not seen
+before, and they are the ones with a fresh rationale worth reading. A genuine
+exception takes an auditable
+`// design-lint-disable-next-line <ruleId> -- <reason>`; a reasonless disable is
+itself a violation.
+
+## 2. Motion — the part the linter can only half-see
+
+`static-interactive` (new in 0.55.0) is the first **prescriptive** rule in the
+system. Every other motion rule fires on motion that is present and wrong;
+none of them could ever fire on motion that is *absent*, so an app that simply
+snaps between every state passed the entire contract. Most apps converted before
+0.55.0 will have findings here, and they are real: they are the places the
+interface has no reaction.
+
+The linter catches static interactive **elements**. It cannot see the three
+motion slots that are about a component's behaviour over time, so check those by
+hand, per surface:
+
+| slot | ask | usual fix |
+|---|---|---|
+| arrival | does new content appear, or cut in? | `motion-fade`, `motion-slide-*`, `motion-pop`, `Reveal` |
+| response | does anything happen under the pointer? | `motion-interactive`, `motion-press` |
+| transition | does it move between its own states, or teleport? | `motion-disclosure`, or ease the transform |
+| activity | can you tell "working" from "frozen"? | `motion-spin`, `motion-pulse`, `motion-shimmer` |
+
+Sable's own components declare their slots — the `## Motion` section of each
+entry in `llms/components/` says which slots are filled, which were *declined*,
+and why. Read the declined ones too: "this does not animate, and here is the
+reason" is what stops you adding motion somewhere it was ruled out.
+
+Anything you compose by hand owns its own slots. The question is not "should this
+animate" but "which of the four does this need, and what fills them".
+
+## 3. Hand-rolled components that Sable now ships
+
+The most valuable finding in an audit is usually a deletion. Search for the
+shapes that tend to get built locally before the library has them, then check the
+catalog:
+
+```bash
+grep -rEl "role=\"(dialog|listbox|tablist|menu)\"|aria-expanded" src/ | head -40
+```
+
+Every conversion so far has deleted more than it added at this step. One tool's
+layers panel lost 174 lines by adopting `Tree`; its whole local
+`components/workspace/` directory went away.
+
+## 4. Review the rendered product
+
+Contract drift is only one part of an audit. A valid token can still be used in
+the wrong hierarchy; a page full of correct cards can still obscure the task.
+Follow [reviewing-a-design.md](./reviewing-a-design.md) across purpose/story,
+typography, spacing, color/material, interaction, motion, responsive behavior,
+and accessibility. Compare against the surface brief, not the default theme.
+Inspect actual desktop/mobile states and record repairs with before/after evidence.
+Capture a reusable finding through [learning-from-builds.md](./learning-from-builds.md).
+
+## 5. Make the contract audit a gate
+
+An audit you have to remember to run is an audit that happens once. Two lines:
+
+```jsonc
+// package.json
+"scripts": { "lint:design": "sable-lint src" }
+```
+
+```yaml
+# CI, alongside tsc and tests
+- run: pnpm lint:design
+```
+
+With that in place the loop closes itself: the dependency bot opens the Sable
+upgrade PR, the new rules ship inside it, CI fails on that PR rather than three
+weeks later, and the diff that introduced the requirement is the diff that has to
+satisfy it. That is the only arrangement where "we should audit the apps" stops
+being a thing anyone has to say.
+
+## Read next
+
+- [converting-an-app.md](./converting-an-app.md) — the first-pass migration
+- [building-a-page.md](./building-a-page.md) ·
+  [building-a-tool.md](./building-a-tool.md)
+- `DESIGN.md → Motion`

package/llms/tasks/building-a-page.md

@@ -0,0 +1,109 @@
+# Task: building a page (page register)
+
+Marketing, docs, settings, a feed, a dashboard — anything whose primary
+interaction is reading and navigating. This is the default register; if you are
+building an editor or a canvas app, see
+[building-a-tool.md](./building-a-tool.md).
+
+## Start from the brief, then choose composition
+
+Read [designing-a-surface.md](./designing-a-surface.md) for the user's outcome,
+content, visual direction, story, interaction, and adaptation. Retrieve relevant
+lessons with `sable learn --search "<context>"`.
+
+`sable pattern --list` offers complete canonical compositions with imports.
+Inspect a matching skeleton and reuse it when its information architecture fits.
+For an original page, compose layout primitives and semantic HTML around the
+brief. Patterns encode useful defaults; they do not define the space of good
+designs. Record the reason for the chosen composition.
+
+## Layout, in the order it matters
+
+```tsx
+<AppShell header={<AppHeader title="…" />} sidebar={<Sidebar>…</Sidebar>}>
+  <Region max="content">          {/* width capped BY ROLE, never globally */}
+    <PageHeader title="Invoices" description="…" actions={<Button>Export</Button>} />
+    <Stack gap={3}>                {/* gap counts 8px rhythm units, not pixels */}
+      …
+    </Stack>
+  </Region>
+</AppShell>
+```
+
+- **Never a global `max-width`.** Width is capped per region by role:
+  `prose` / `form` / `feed` / `content` / `wide` / `full`. A form region is narrow
+  because a 700px text input is harder to use, not more generous.
+- **Measure ≠ width.** Cap prose line length in `ch` (`--measure-prose`)
+  independently of the region's layout width.
+- **The 12-column grid lives *inside* a region**, for genuinely multi-column
+  content. A column span is not a page width.
+- **Chrome is off the grid.** `Sidebar` and rails are fixed-width, outside the
+  content grid.
+
+## Typography: pick the tier by ROLE, not by size
+
+| tier | for | not |
+|---|---|---|
+| `text-display-*` | a hero, one per view at most | page titles — that is `heading-1` |
+| `text-heading-1..4` | the document outline; pick by depth | size — if it belongs in a table of contents it is a heading |
+| `text-title-*` | a *component's* title: card, dialog, panel section | a heading tier — a card title is not part of the page outline |
+| `text-body-*` | prose you read a sentence of | labels |
+| `text-label-*` | field labels, column headers, button text | body at the same size |
+| `text-caption` | metadata *beneath* something | `text-overline`, which sits *above* and categorises |
+
+Always the paired utility. Never `text-sm font-medium` — CI rejects it.
+
+## Colour: role, not appearance
+
+`accent`, `secondary` and `muted` are near-identical in most themes and are
+chosen by what the surface *does*:
+
+- `muted` — recessed and inert (a well, a disabled field, a zebra stripe)
+- `secondary` — a control fill (something you can press)
+- `accent` — a transient state (hover, selected, current)
+
+Pick by appearance and it works in Base and breaks in Meridian. Every token's
+intent, and what it gets confused with, is in
+`llms/reference/token-intent.md`.
+
+Ink is never chosen independently of its surface: `bg-card text-card-foreground`,
+as a pair.
+
+## The traps
+
+- **A `Card` is a container, not a heading or a landmark.** If its title is the
+  only heading in the region, render a real heading element.
+- **One `h1` per route** — `PageHeader` renders it. A second breaks the outline a
+  screen-reader user navigates by.
+- **`AppHeader` is app chrome; `PageHeader` is content.** Route-specific actions
+  in `AppHeader` persist onto routes where they mean nothing.
+- **Tone is never the only signal.** Pair a tone with an icon or text; colour
+  alone fails for colour-blind users.
+
+## Verify
+
+```bash
+npx sable-lint            # lints ./src; pass dirs to change (npx sable-lint app components)
+```
+
+`sable-lint` ships with the package and reads the token vocabulary from the
+`registry.json` of the version you installed, so it checks your app against your
+exact tokens. It exits 1 on any violation. `--rules` explains each one; `--ignore
+'<glob>'` skips a data/fixture layer, where a hex value is content rather than a
+style. A rare, genuine exception takes an auditable
+`// design-lint-disable-next-line <ruleId> -- <reason>`.
+
+Then your own `tsc` and tests. (`pnpm design-lint && pnpm build:registry &&
+pnpm test:run` are the *in-repo* gates — they only run inside the Sable repo.)
+
+Then inspect the rendered page on desktop and mobile, operate its primary flow,
+use the keyboard, and check reduced motion. Follow
+[reviewing-a-design.md](./reviewing-a-design.md) for evidence and repair. Passing
+source checks alone says nothing about hierarchy, story, or the resulting polish.
+
+## Read next
+
+- `sable pattern --list` — the current compositions
+- `registry.json → layoutPrimitives` — full contracts plus the layout doctrine
+- `DESIGN.md` — spacing, dimensions, shape, elevation, layering, motion
+- `llms/reference/token-intent.md`

package/llms/tasks/building-a-tool.md

@@ -0,0 +1,141 @@
+# Task: building a tool (workspace register)
+
+An editor, a canvas app, a console — anything whose primary interaction is
+*operating on something* rather than reading and navigating.
+
+If the primary interaction is reading down a page, stop: you want
+[building-a-page.md](./building-a-page.md). A dashboard that scrolls is a page
+with dense content, not a workspace.
+
+## The shell
+
+First read [designing-a-surface.md](./designing-a-surface.md). Define the operator's
+primary task, selection/navigation model, most frequent actions, and narrower
+viewport behavior before choosing panel furniture. Retrieve applicable precedents
+with `sable learn --search "workspace interaction"`; editorial motion and display
+hierarchy do not automatically transfer to dense operating surfaces.
+
+```tsx
+<Workspace                                   {/* h-dvh, sets data-density="compact" */}
+  toolbar={<WorkspaceBar>…</WorkspaceBar>}
+  statusBar={<StatusBar>…</StatusBar>}
+>
+  <PanelGroup>
+    <Panel label="Layers" width={leftWidth}>…</Panel>
+    <PanelResizer side="left" width={leftWidth} onWidthChange={setLeftWidth}
+                  label="Resize layers panel" />
+    <WorkspaceCanvas>{/* the work surface — clips, never scrolls */}</WorkspaceCanvas>
+  </PanelGroup>
+</Workspace>
+```
+
+`Workspace` sets the compact density scope for its whole subtree. Nothing
+hardcodes a height: every control reads `--control-*`, so the same
+`<Button size="md">` is 40px on a page and 32px here. A `Dialog` opened from
+inside resets to comfortable, because a modal is a page-register surface even
+when a tool launched it.
+
+## What you will need, and what to avoid reaching for
+
+| you want | use | NOT |
+|---|---|---|
+| a property grid | `PanelSection` + `PropertyRow` / `PropertyPair` | `Card` — in 240px it spends its border and inset on nothing |
+| a numeric property | `ScrubField` | `NumberField` — its two steppers put a ~112px floor on a ~44px slot |
+| a layers / object list | `Tree` | a hand-nested list — no selection model or keyboard |
+| an empty panel section | `TreeEmpty` | `EmptyState` — `px-6 py-12` around a `size-12` disc |
+| a colour property | `ColorField` | `<input type="color">` — OS dialog, ignores the theme, wrong size |
+| ambient document facts | `StatusBar` | a toolbar — status is glanced at, not operated |
+| chrome typography | `text-ui-md` / `-sm` / `-body` / `-section` / `-micro` / `-num` | `text-body-*` — page tiers, ~1/3 too large here |
+
+## Menus, selects and popovers adapt on their own
+
+`Menu`, `Select`, `Popover`, `Tooltip` and `ContextMenu` pick up the workspace's
+density automatically — including **across the portal**. Their popups mount at
+the document root, so CSS could never reach them; they re-apply `data-density`
+from React context instead.
+
+**Do not size them per call site.** That was necessary before v0.41 — Glitch
+carried 14 such overrides and had them inconsistent — and it is now drift.
+
+A **modal** is deliberately different: `Dialog`, `Sheet` and
+`DestructiveActionModal` stay page-register even when a tool opens them, because
+a modal is its own surface rather than part of the control that opened it.
+
+## The traps, all of which have shipped
+
+- **A portaled surface still fires your canvas's pointer handlers.** Every Sable
+  popup — `Dialog`, `Menu`, `Select`, `Popover`, `Tooltip`, `ContextMenu` —
+  portals to `document.body`. But React propagates events through the **component
+  tree, not the DOM tree**, so if the component that renders your canvas also
+  renders the dialog, every press inside that dialog re-enters your pan/drag/
+  marquee handler.
+
+  The symptom is specific and misleading: **pointerdown-driven controls work while
+  click-driven ones do not.** A combobox opens (pointerdown) but you cannot pick
+  an option (click); buttons, switches and Cancel are dead; typing and Escape are
+  fine. That is a global handler calling `setPointerCapture` on pointerdown, which
+  retargets `pointerup` away from the button, so the browser never synthesises a
+  `click`. Nothing is prevented and nothing errors — it reads exactly like a
+  broken component.
+
+  Guard by **containment in your own surface**, not by a marker on ancestors:
+
+  ```tsx
+  // ✗ walks DOM ancestors — a portaled popup's ancestors are <body>/<html>,
+  //   so the marker is never found and the guard passes everything through
+  if ((e.target as Element).closest("[data-no-pan]")) return
+
+  // ✓ a pan is a press inside the thing being panned. Portals fail this by
+  //   construction, and so does every future popup you have not written yet
+  if (!viewportRef.current?.contains(e.target as Node)) return
+  ```
+
+  Test it with a popup **open over a live document**, not on an empty canvas — a
+  disabled pan cannot exhibit the bug, so a green run there proves nothing.
+
+- **`min-h-0` is the precondition for scrolling.** `overflow-y-auto` only
+  activates if every flex ancestor can shrink. One missing `min-h-0` up the chain
+  and the panel grows instead of scrolling — silently.
+- **Never override a control height with a selector.** `[data-density] button {
+  height: … }` loses to any equal-specificity utility. Redefine `--control-*` in a
+  density scope instead. CI-enforced (`raw-control-height`).
+- **Tree geometry has one invariant:** `--tree-indent` must equal
+  `--tree-column`. A smaller step puts a child's content LEFT of its parent's and
+  the nesting reads inverted. Use `treeIndent(depth)`; never hand-write an inset.
+- **No pills in chrome.** The compact scope flattens `--button-radius` to ~5px —
+  one of two page-register rules the workspace register deliberately reverses.
+- **Drag with window listeners, not `setPointerCapture`.** Capture throws for an
+  inactive pointer id and the throw aborts the handler mid-gesture, silently.
+- **An unmapped `<Icon name>` renders nothing.** No error. Check the contract.
+
+## Verify
+
+```bash
+npx sable-lint            # lints ./src; pass dirs to change (npx sable-lint app components)
+```
+
+`sable-lint` ships with the package and reads the token vocabulary from the
+`registry.json` of the version you installed, so it checks your app against your
+exact tokens. It exits 1 on any violation. `--rules` explains each one; `--ignore
+'<glob>'` skips a data/fixture layer, where a hex value is content rather than a
+style. A rare, genuine exception takes an auditable
+`// design-lint-disable-next-line <ruleId> -- <reason>`.
+
+Then your own `tsc` and tests. (`pnpm design-lint && pnpm build:registry &&
+pnpm test:run` are the *in-repo* gates — they only run inside the Sable repo.)
+
+Then measure in the browser. Every number in the workspace register came from
+measuring Figma and Paper in-page, and every register bug found so far was found
+by reading computed values, not by looking at a screenshot.
+
+Also inspect the rendered hierarchy and complete a real flow with a live document,
+keyboard navigation, a narrow viewport, and reduced motion. Use
+[reviewing-a-design.md](./reviewing-a-design.md) to record evidence, repair defects,
+and distinguish observed behavior from untested claims.
+
+## Read next
+
+- `DESIGN.md → Registers` — doctrine, measured numbers, the two reversals
+- `llms/components/workspace.md`, `panel-group.md`, `panel-section.md`,
+  `tree.md`, `scrub-field.md`, `status-bar.md`, `color-field.md`
+- `llms/reference/token-intent.md` — which token to reach for