@hirobius/design-system 0.19.1 → 0.21.0

package/AGENTS.md

@@ -0,0 +1,123 @@
+# AGENTS.md — @hirobius/design-system
+
+<!-- Generated by scripts/generate-agents-md.mjs from mcp/guide.mjs and src/app/data/component-api.json. Do not hand-edit above the repo-notes marker: pnpm agents:generate -->
+
+For agents building UI with `@hirobius/design-system`. Read this first. It settles the choices the rest of the docs leave open, so two agents given the same screen build it the same way.
+
+## Look things up, do not guess
+
+- **MCP server `hds`** (stdio, ships in this package, no network): `npx hds-mcp` from an app that has the package installed. Client config:
+  `{ "mcpServers": { "hds": { "command": "npx", "args": ["hds-mcp"] } } }`
+- Tools: `list_core` (call first), `search_components` (by name or need), `get_component` (props, usage contract, compound parts), `search_tokens` (by path, prefix or words). Each answer is under 2 KB.
+- Without the server, the same data is in `src/app/data/component-api.json` (props, `usage`), `public/hds-manifest.json` (tokens, compound parts), `llms.txt` and `DESIGN.md` in this package.
+
+## Imports
+
+- `@hirobius/design-system`: `Alert`, `AlertDialog`, `Avatar`, `AvatarGroup`, `Badge`, `Blockquote`, `Box`, `Breadcrumb`, `Button`, `Card`, `Checkbox`, `Combobox`, `Container`, `Dialog`, `Disclosure`, `Divider`, `EmptyState`, `Field`, `Grid`, `HdsRouterProvider`, `HdsThemeProvider`, `Icon`, `InlineLink`, `Input`, `Kbd`, `Menu`, `MetadataList`, `Pagination`, `Pin`, `Popover`, `Progress`, `Radio`, `SegmentedControl`, `Select`, `Sidebar`, `Skeleton`, `Slider`, `Spinner`, `Stack`, `Surface`, `Switcher`, `Table`, `Tabs`, `TabsContent`, `TabsList`, `TabsTrigger`, `Tag`, `Text`, `Textarea`, `Timestamp`, `ToastProvider`, `Toggle`, `Tooltip`, `VisuallyHidden`, `useToast`.
+- `@hirobius/design-system/patterns`: `DataTableSection`, `DestructiveSection`, `Form`, `FormActions`, `MetricTile`, `MetricTiles`, `Page`, `PageHeader`. These are not in the root barrel.
+- Load one stylesheet once at the app root and put `data-hds` on the root element (`CONSUMING.md`).
+
+## Pick by need
+
+One answer per need. Use the components after the arrow; what follows "Not:" is what agents reached for instead, which is the wrong answer for that need even where it has a purpose of its own.
+
+- **Outermost wrapper of a screen** → `Page`, `Stack`. Not: `Container`, `Box`, a bare Stack as the root.
+  `<Page><Stack gap="spacious">…one child per section…</Stack></Page>`. `Container` is for a full-bleed surface that is not a page.
+- **Screen title with breadcrumb, status and actions** → `PageHeader`, `Breadcrumb`, `Badge`. Not: Text as the page title, a Stack row of Text and Badge.
+  Exactly one per screen: `<PageHeader breadcrumb={<Breadcrumb items={[{ label, href }, { label }]} />} title="…" status={<Badge tone="success">Active</Badge>} />`.
+- **Row of headline numbers (stats, KPIs, counts, totals)** → `MetricTiles`, `MetricTile`. Not: `Stat`, `StatusTile`, `CardMetric`, Card with Text.
+  `<MetricTiles><MetricTile label="Open projects" value="5" />…</MetricTiles>`; one MetricTile per number. `Stat` is for a number inside prose or a dense list, `Card.Metric` for one inside an existing `Card`, `StatusTile` for a state with notes (never a number).
+- **Table of records with row actions** → `DataTableSection`, `Badge`, `Button`. Not: Table on its own, Card around a Table.
+  `<DataTableSection title="Projects" columns={[{ key, label }]} rows={[{ key, cells: [...], actions: <Stack direction="row" gap="tight">…</Stack> }]} />`; leave the actions column out of `columns`.
+- **Switch between panels of related content** → `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. Not: `SegmentedControl`, Button rows.
+  `<Tabs defaultValue="a"><TabsList><TabsTrigger value="a">A</TabsTrigger></TabsList><TabsContent value="a">…</TabsContent></Tabs>`.
+- **Status label in a header or table cell** → `Badge`. Not: `Tag`, `Text`.
+  `<Badge tone="success|info|warning|danger|neutral|inProgress">…</Badge>`; tone is the only styling input.
+- **Form with fields and a submit button** → `Form`, `Textarea`, `Input`, `FormActions`, `Button`. Not: a raw `<form>`, a Stack of Buttons as the footer.
+  `<Form onSubmit={…}><Textarea label="Notes" … /><FormActions primary={<Button type="submit">Save note</Button>} /></Form>`; every field takes its own `label`.
+- **Confirm a destructive or irreversible action (delete, archive, remove)** → `AlertDialog`, `Button`. Not: `Dialog`, `window.confirm`.
+  Trigger, title, description, Cancel and Action parts: `<AlertDialog><AlertDialog.Trigger asChild><Button …>Archive</Button></AlertDialog.Trigger><AlertDialog.Content><AlertDialog.Header><AlertDialog.Title>…</AlertDialog.Title><AlertDialog.Description>…</AlertDialog.Description></AlertDialog.Header><AlertDialog.Footer><AlertDialog.Cancel asChild><Button variant="secondary">Cancel</Button></AlertDialog.Cancel><AlertDialog.Action asChild><Button tone="danger" onClick={…}>Archive</Button></AlertDialog.Action></AlertDialog.Footer></AlertDialog.Content></AlertDialog>`. Focus moves in and returns to the trigger for you.
+- **Brief confirmation after an action (saved, archived, sent)** → `ToastProvider`, `useToast`. Not: `Badge`, `Alert`, `Text`.
+  Wrap the app root once in `<ToastProvider>`, then `toast({ title: "Note saved", tone: "success" })` from `useToast()`.
+- **Message that stays next to its content (error, warning, info)** → `Alert`. Not: Text in a coloured Surface.
+  `<Alert tone="warning">…</Alert>`.
+- **Button or row action** → `Button`. Not: a raw `<button>`, InlineLink for an action.
+  Row actions: `<Button variant="tertiary" size="sm" aria-label="View Brand refresh">View</Button>`; the destructive one adds `tone="danger"`.
+- **Space between sections or items** → `Stack`, `Grid`. Not: margins on children, raw px gaps such as px8.
+  Stack `gap`: `spacious` between page sections, `normal` inside a section, `tight` between buttons. `Grid` for two-dimensional layout.
+- **Padded background or a titled content object** → `Surface`, `Card`. Not: a Box with background and padding.
+  `Surface` for a plain padded background; `Card` only when the content has a title or can be pressed.
+- **Progress bar or ring** → `Progress`. Not: a hand-built bar.
+  `<Progress value={60} label="Upload" />`; inside an existing `Card`, `CardProgress`.
+- **Body copy** → `Text`. Not: Text as a section heading.
+  Section headings come from the pattern that owns the section (`PageHeader` `title`, `DataTableSection` `title`), not from extra Text.
+- **Empty state for a list or section** → `EmptyState`. Not: Text saying "No items".
+  `DataTableSection` shows its own through `emptyTitle`; use `EmptyState` elsewhere.
+- **The one irreversible action of a screen (delete the client, close the account)** → `DestructiveSection`. Not: a danger Button that acts without a confirm.
+  Last on the screen: `<DestructiveSection title="Delete client" description="…" actionLabel="Delete" onConfirm={…} />`; it opens its own AlertDialog. A per-row destructive action uses AlertDialog directly.
+- **Read-only details as label and value pairs** → `MetadataList`, `Field`. Not: a Table with two columns, Text pairs in a Stack.
+  `<MetadataList items={[{ term: "Owner", description: "Ada" }]} />` for a set; `Field` for one pair.
+- **A person, or a group of people** → `Avatar`, `AvatarGroup`. Not: an image in a rounded Box.
+  `<Avatar src alt initials />`; several in a row: `<AvatarGroup max={3}>…Avatars…</AvatarGroup>`.
+- **A date or time** → `Timestamp`. Not: a formatted string in Text.
+  `<Timestamp date="2026-10-14" />` renders a `<time dateTime>`; a date in a table cell may stay plain text.
+- **A keyboard key or shortcut hint** → `Kbd`. Not: `InlineCode`, Text in a Box.
+  `<Kbd>⌘K</Kbd>`.
+- **A quotation with attribution** → `Blockquote`. Not: Callout for a quote, italic Text.
+  `<Blockquote attribution="Ada Lovelace">…</Blockquote>`.
+- **A fixed-width side rail beside fluid content, or a row that stacks when narrow** → `Sidebar`, `Switcher`. Not: a Grid with media queries.
+  `Sidebar` (`side`, `sideWidth`) for rail + content; `Switcher` (`threshold`) for a row that flips to a column. Neither needs a media query.
+- **Keep an element stuck while its region scrolls** → `Pin`. Not: position: sticky in style.
+  `<Pin top="…">…</Pin>` inside the scrolling region.
+
+## Rules
+
+- Tokens only: no raw hex or rgb, no raw `px`, no Tailwind classes, no custom CSS files. Spacing comes from component props (`Stack` `gap`), colour from component `tone` props or `semantic.*` tokens (`search_tokens`).
+- No raw `<button>`, `<input>`, `<select>`, `<textarea>` or `<form>`: use `Button`, `Input`, `Select`, `Textarea`, `Form`.
+- Every control has an accessible name: fields take `label`, a repeated row action takes an `aria-label` naming its row.
+- Section headings come from the pattern that owns the section (`title` props). Do not add a `Text` heading the screen does not ask for.
+
+## Finish with the lint plugin
+
+The ESLint plugin ships in this package. Pass its `recommended` rules before you report done:
+
+```js
+// eslint.config.mjs
+import hds from '@hirobius/design-system/eslint-plugin';
+
+export default [...hds.configs.recommended];
+```
+
+<!-- hds:repo-notes — everything below is hand-written, for agents working in the hds repo itself; consumers can stop here. -->
+
+## Working in the hds repo
+
+Notes for agents working on this repository, not with the package. Read `CLAUDE.md` for
+the full engineering protocol; this section is the home for autonomous-loop rules.
+
+## Ralph quality bar
+
+REPO_TYPE: library
+QUALITY BAR: Public npm package. Backward compatibility matters. Tests + Storybook stories required.
+
+Rules for any autonomous loop in this repo:
+
+- One issue per PR. Small steps. Never push to main.
+- The gate (ralph/gate.sh) must pass before any PR. No exceptions.
+- Fight entropy: leave the code better than you found it.
+- No shortcut that creates debt someone else pays for.
+- Merges are HUMAN-approved: `ralph-approved` on the PR, or the issue
+  pre-tagged `ralph-auto` (batch approval). Never merge yourself.
+
+Loop mechanics (see `ralph/README.md` for the full contract):
+
+- Labels: `ralph-ready` (queue, human) · `p0`–`p3` (priority, human) ·
+  `ralph-auto`/`ralph-approved` (merge approval, human) · `ralph-wip`
+  (claimed, loop) · `ralph-parked`/`needs-adrian` (parked with reason, loop) ·
+  `ralph-selfheal-attempted` (gate's one bounded repair, spent).
+- Selection is deterministic (`ralph/next.sh`: priority label, then issue #);
+  claims are atomic (`refs/heads/ralph/claim-<n>`); the loop's exit codes are
+  a contract (`ralph/run.sh` header). Agents never touch `ralph-*` labels,
+  claim refs, or `ralph/{.lock,runs.jsonl,logs/}` — the harness owns those.
+- The engine is org-level: workflows are thin callers into
+  `hirobius/ralph/.github/workflows/ralph-{run,gate}-reusable.yml@v1`.

package/CONSUMING.md

@@ -29,6 +29,7 @@ version keeps the `LucideIcon` type identical).
 ```tsx
 import { Button, Card, Dialog } from '@hirobius/design-system';
 import '@hirobius/design-system/tokens.css'; // required — design tokens as CSS vars
+import '@hirobius/design-system/fonts.css'; // optional — the HDS brand fonts (Satoshi, Geist Mono)
 
 export function Example() {
   return (
@@ -43,7 +44,8 @@ Available subpaths:
 
 | Import                               | What                                                                                                                                                                                                                                        |
 | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@hirobius/design-system`            | All components (primitives, patterns, templates)                                                                                                                                                                                            |
+| `@hirobius/design-system`            | The 43-component core set ([README → What belongs in the system](README.md#what-belongs-in-the-system)), the rest of the allow-list and the templates; the `pattern` tier is only in `/patterns`                                            |
+| `@hirobius/design-system/fonts.css`  | Optional brand fonts (Satoshi, Geist Mono); woff2 files ship in the package, relative URLs, `font-display: swap`                                                                                                                            |
 | `@hirobius/design-system/tokens.css` | Token CSS variables (import once at app root)                                                                                                                                                                                               |
 | `@hirobius/design-system/tokens`     | Token values as TS constants                                                                                                                                                                                                                |
 | `@hirobius/design-system/cn`         | `cn()` class-merge helper                                                                                                                                                                                                                   |
@@ -51,8 +53,8 @@ Available subpaths:
 | `@hirobius/design-system/contexts`   | Theme / language / tenant / font providers                                                                                                                                                                                                  |
 | `@hirobius/design-system/brand`      | Palette → HDS-semantic overlay bridge (static / SSR / Astro; see [`docs/CONSUMING.md` §12](docs/CONSUMING.md#12-static-astro-sites--the-brand-overlay-bridge))                                                                              |
 | `@hirobius/design-system/scroll`     | Opt-in scroll-motion primitives — `SmoothScroll` (Lenis), `useScrollProgress` (Motion). Requires the optional peer `lenis`. See [`docs/CONSUMING.md` §13](docs/CONSUMING.md#13-scroll-motion-the-scroll-subpath)                            |
-| `@hirobius/design-system/patterns`   | The 22 `pattern`-tier components (nav shells, feeds, rails, pickers — see hds#254). Also still re-exported from the root for one minor (`@deprecated`, removed at the next major) — prefer this subpath in new code.                        |
-| `@hirobius/design-system/icons`      | Curated Lucide icon set for `IconButton` / `Icon` (`Ellipsis`, `Pencil`, `Trash2`, `X`, …). Names listed in the manifest `iconSet`.                                                                                                         |
+| `@hirobius/design-system/patterns`   | The 12 pattern modules: the hds#254 `pattern` tier (page shells, forms, code blocks, page sections). The only entry that exports them: 0.20.0 removed their root re-exports (the `hds-patterns-subpath` codemod, see MIGRATIONS.md).        |
+| `@hirobius/design-system/icons`      | Curated Lucide icon set for `Icon`, and so for `Button iconOnly` (`Ellipsis`, `Pencil`, `Trash2`, `X`, …). Names listed in the manifest `iconSet`.                                                                                          |
 | `@hirobius/design-system/static.css` | CSS-only static-primitive layer — `.hds-badge`/`.hds-card`/`.hds-alert`/`.hds-divider`/`.hds-tag` classes, no React. See [`docs/CONSUMING.md` §14](docs/CONSUMING.md#14-css-only-static-primitives--badgecardalertdividertag-with-no-react) |
 
 The package is **ESM-only**, so consume it with a modern bundler (Vite, Next.js,
@@ -113,8 +115,11 @@ Releases follow [semver](https://semver.org/) and are tracked in
 pnpm update @hirobius/design-system   # latest within your version range
 ```
 
-For a major (breaking) release, bump the version explicitly and review the
-CHANGELOG entry. Token or export changes are released as majors.
+For a breaking release, bump the version explicitly and review the CHANGELOG
+entry. Before 1.0 a breaking change (a removed export or token) ships in a 0.x
+minor, which a caret range such as `^0.19` never picks up; from 1.0 on it ships
+in a major. Each removal is listed in [MIGRATIONS.md](MIGRATIONS.md) with its
+replacement and, where one applies, a codemod (ADR-014).
 
 ---
 
@@ -122,7 +127,7 @@ CHANGELOG entry. Token or export changes are released as majors.
 
 ```bash
 pnpm changeset add        # record a patch/minor/major bump + notes
-pnpm changeset:version    # apply bumps + regenerate CHANGELOG.md
+pnpm changeset:version    # apply bumps + regenerate CHANGELOG.md + refresh docs/api/api-baseline.json
 # commit + push to main → the Release workflow publishes to public npm
 ```
 

package/DESIGN.md

@@ -28,28 +28,29 @@ Feedback hues are never decorative; do not use them as accents. Light and dark m
 <!-- auto:start:typography -->
 HDS ships three typefaces — each with a distinct and exclusive role:
 
-- **Display / Heading font**: Satoshi. Bound exclusively to `display`, `h1`, `h2`, and `h3` styles. Never used for body copy or UI labels.
+- **Display / Heading font**: Satoshi. Bound exclusively to the `display` and `title` styles. Never used for body copy or UI labels.
 - **Body / UI font**: Satoshi. All prose, labels, small text, captions, and UI copy.
 - **Mono font**: Geist Mono. Reserved for tokens, code, technical callouts, and metric readouts.
 
-Weights declared: `400` regular, `500` medium, `700` bold. Heading styles (display · h1 · h2 · h3) use `700` bold; body, UI, and caption use `500` medium. Declared but unused by any semantic role: `400` regular.
+Weights declared: `400` regular, `500` medium, `700` bold. Heading styles (display · title) use `700` bold; body, UI, and caption use `400` regular / `500` medium.
 
 ### Type ramp
 
 | Role | Size (desktop max) | Weight | Use |
 | --- | --- | --- | --- |
-| `semantic.typography.display` | 60px | 700 | Display headline |
-| `semantic.typography.h1` | 48px | 700 | Primary section headings (h1) |
-| `semantic.typography.h2` | 30px | 700 | Secondary section headings (h2) |
-| `semantic.typography.h3` | 20px | 700 | Component and card headers (h3) |
-| `semantic.typography.body` | 16px | 500 | Body prose |
-| `semantic.typography.ui` | 14px | 500 | UI text for nav, labels, captions |
-| `semantic.typography.caption` | 12px | 500 | Caption / helper text |
-| `semantic.typography.eyebrow` | 12px | 500 | Eyebrow / kicker label |
-| `semantic.typography.mono` | 14px | 400 | Monospace for code, token names, shortcuts |
+| `semantic.typography.display` | 48px | 700 | One per page, hero only |
+| `semantic.typography.title` | 24px | 700 | Section and card headings |
+| `semantic.typography.body` | 16px | 400 | Prose |
+| `semantic.typography.ui` | 14px | 500 | Controls, nav, table text, values |
+| `semantic.typography.caption` | 12px | 500 | Metadata, help text and labels, in sentence case |
+| `semantic.typography.mono` | 13px | 400 | Code and ids |
+| `semantic.typography.h1` | 24px | 700 | deprecated: use semantic.typography.title |
+| `semantic.typography.h2` | 24px | 700 | deprecated: use semantic.typography.title |
+| `semantic.typography.h3` | 24px | 700 | deprecated: use semantic.typography.title |
+| `semantic.typography.eyebrow` | 12px | 500 | deprecated: use semantic.typography.caption |
 | `semantic.typography.lineHeight.none` |  |  | Semantic alias for leading-none (1) |
 
-> Responsive `clamp()` overrides live in `src/styles/theme.css`; tokens store the desktop-max static value.
+> The ramp is static: tokens store the value every surface renders. `h1`, `h2`, `h3` and `eyebrow` are deprecated aliases and go in 1.0.0.
 <!-- auto:end:typography -->
 
 ## Spacing
@@ -59,9 +60,19 @@ Weights declared: `400` regular, `500` medium, `700` bold. Heading styles (displ
 
 Scale: `0px` (`primitive.space.0`) · `1px` (`primitive.space.px1`) · `2px` (`primitive.space.px2`) · `4px` (`primitive.space.1`) · `6px` (`primitive.space.px6`) · `8px` (`primitive.space.2`) · `10px` (`primitive.space.px10`) · `12px` (`primitive.space.3`) · `16px` (`primitive.space.4`) · `20px` (`primitive.space.5`) · `24px` (`primitive.space.6`) · `28px` (`primitive.space.7`) · `32px` (`primitive.space.8`) · `40px` (`primitive.space.10`) · `48px` (`primitive.space.12`) · `64px` (`primitive.space.16`) · `80px` (`primitive.space.20`) · `96px` (`primitive.space.24`) · `128px` (`primitive.space.32`)
 
-Use `primitive.space.*` for layout rhythm, padding, and gaps. Use `semantic.space.*` aliases (e.g. `semantic.space.surface.padding`) when the purpose is established. `data-density="compact"` (on `<html>` or the `[data-hds]` scope element) remaps `semantic.space.scale.*`, `semantic.space.surface.padding` and `semantic.space.region.gutter` one step down the scale, and `Table` follows it. The `--hds-space-{xs…4xl}` vars are a legacy bridge that no component reads.
+Layout rhythm, padding, and gaps use the `semantic.space.scale.{xs…xl}` steps (and `none`), never a raw `primitive.space.*` value or a numeric Tailwind class; `primitive.space.*` is the ramp behind the scale. Use `semantic.space.*` aliases (e.g. `semantic.space.surface.padding`) when the purpose is established. `data-density="compact"` (on `<html>` or the `[data-hds]` scope element) remaps `semantic.space.scale.*`, `semantic.space.surface.padding` and `semantic.space.region.gutter` one step down the scale, and `Table` follows it. The `--hds-space-{xs…4xl}` vars are a legacy bridge that no component reads.
 <!-- auto:end:spacing -->
 
+## Layout contract (v1)
+
+Approved 2026-10-07. Data: `docs/guardrails/layout-contract.json`; gates: `pnpm check:layout-contract` and `pnpm check:spacing-scale` (warn mode; baseline in `docs/audits/layout-contract-baseline.md`).
+
+1. **Sizing.** Every component declares `fill` or `hug` on each axis. Leaves hug. Input, Textarea, Select, Combobox, Table, Progress and Divider fill width. One override prop, `width="hug|fill"`, on every component. Height always hugs; stretching is the parent's job (`align="stretch"`). No component sets `h-full`, `height: 100%` or `self-*` on its root.
+2. **Padding.** Only containers pad: Card, Surface, Alert, Callout, Dialog, Page. Compound parts (`Card.Header`, `Body`, `Footer`, `Metric`) have zero padding and the container's `gap` spaces them. Padding is `none | sm | md`, default `md`, density-aware. A padded container directly inside a padded container is an error unless the inner one is `padding="none"`.
+3. **Spacing.** One scale, `xs…xl` (plus `none`), for every `gap` and `padding` prop. Every gap defaults to `md`. No outer margins on any component; space between siblings is the parent's `gap`.
+4. **Primitives.** Stack, Grid, Page (absorbs Container) and Surface compose layouts. Box and Pin are escape hatches. Sidebar and Switcher fold into Stack and Grid.
+5. **Forms.** A form control in a form context has a max width (`40rem` by default) and siblings share one width.
+
 ## Corner-Radius Policy
 
 Shape is one knob. `semantic.radius.action` is the system's single shape value — interactive controls (buttons, inputs, badges, alerts, segmented items) all resolve to it, and Tailwind's `rounded-md` maps to it exactly so the utility and the token cannot disagree. Containers sit one step above at `rounded-lg` (`action + 4px`); `rounded-sm` (`action - 2px`) is for chrome nested inside a control. `full` is reserved for pills and circular forms, and `0px` only for intentional outer canvas or substrate boundaries, never everyday UI controls. Reshaping the whole system means overriding `role.radius` in one tenant overlay — that is how `brutalist-demo` goes square in a single value.
@@ -90,7 +101,7 @@ Depth is communicated through 4 elevation roles bundled by `semantic.elevation.*
 
 Cards default to `flat`. They lift to `raised` only on interactive hover or when explicitly elevated above siblings. Never combine `raised` with a border — depth is one mechanism (border OR shadow), not both stacked.
 
-Overlays (Dialog, AlertDialog, Menu, ContextMenu, Popover, Select, HoverCard, Tooltip) portal into the nearest `data-hds` scope, so they inherit its theme (for example `<div data-hds data-theme="dark">`); pass `container` on the Content part to override.
+Overlays (Dialog, AlertDialog, Menu, Popover, Select, Tooltip) portal into the nearest `data-hds` scope, so they inherit its theme (for example `<div data-hds data-theme="dark">`); pass `container` on the Content part to override.
 
 ## Motion
 
@@ -121,7 +132,7 @@ Default most interactive feedback to `productive` (150ms, decelerate). Reserve `
 
 | Token | Value | Purpose |
 | --- | --- | --- |
-| `semantic.motion.distance` | `24px` | Travel distance for a scroll-reveal translateY offset. Coincides in value with semantic.space.scale.md today, but names a motion travel distance rather than a spacing tier (hds#242). |
+| `semantic.motion.distance` | `24px` | Scroll-reveal translateY travel distance. Equals semantic.space.scale.md today, but names motion travel, not a spacing tier (hds#242). |
 <!-- auto:end:motion -->
 
 ## Components
@@ -129,7 +140,7 @@ Default most interactive feedback to `productive` (150ms, decelerate). Reserve `
 <!-- auto:start:components -->
 | Component | Radius | States | Guidance |
 | --- | --- | --- | --- |
-| **Buttons** (`Button`) | `8px` (`semantic.radius.action`) | default · hover · focus · active · disabled · loading | Three variants: primary (accent-filled), secondary (outline), tertiary (ghost). Primary uses `semantic.accent.*` ramp per state. Icon buttons (`IconButton`) follow the same token surface. Icon-only actions use `IconButton` with an icon from `@hirobius/design-system/icons`. |
+| **Buttons** (`Button`) | `8px` (`semantic.radius.action`) | default · hover · focus · active · disabled · loading | Three variants: primary (accent-filled), secondary (outline), tertiary (ghost). Primary uses `semantic.accent.*` ramp per state. Pressed is a 5% `semantic.color.state.pressed.overlay` wash over the fill (`role.pressed-overlay`: black in light, white in dark), not a brightness filter. Icon-only buttons (`iconOnly`) follow the same token surface. Icon-only actions use `Button iconOnly` with a `label` and an `Icon` from `@hirobius/design-system/icons` in `iconLeft`. |
 | **Inputs** (`Input`) | `8px` (`semantic.radius.action`) | default · focus · filled · error · disabled · loading | Border-driven treatment; no filled background by default. Focus uses `semantic.color.border.accent` plus a 2px outline offset. Error swaps to `component.input.borderError`. |
 | **Cards** (`Card`) | `12px` (`rounded-lg`, role radius + 4px) | default · hover (optional parallax) · pressed (when interactive) | Cards default to `elevation.flat` (1px border `border.subtle`, no shadow). Interactive cards lift to `elevation.raised` (shadow.subtle, no border) on hover. Bind via `semantic.elevation.{role}` — never raw box-shadow values. Radius: `rounded-lg` (role radius + 4 px, follows the tenant knob) — never a hard-coded value. Padding: `var(--semantic-space-surface-padding)`. Title: `heading3`. Meta: `caption` + `var(--semantic-color-content-secondary)`. Hover (interactive): `scale(1.02)` transform + lift to raised. Never: gradients, glow, frosted glass, tinted surfaces, decorative overlays, or inner shadows. |
 | **Badges** (`Badge`) | `8px` (`primitive.radius.4`) | neutral · accent · feedback (error/success/warning/info) | Single-line status markers. Feedback colors come from `semantic.color.feedback.*`. Never used as decorative chrome. |
@@ -152,7 +163,7 @@ Every HDS card surface must conform to this anatomy exactly. No creative interpr
 | Border radius            | `rounded-lg` (`role.radius` + 4 px: 12 px by default, follows the tenant)                                | `var(--component-card-radius)`, `rounded-full`, or any hard-coded value                     |
 | Padding                  | `var(--semantic-space-component-padding)` or `<HdsSurface padding="component">`                          | Raw pixel values or ad hoc insets                                                           |
 | Shadow                   | Resting cards: none (`elevation.flat`). Interactive lifted state: `shadow.subtle` via `elevation.raised` | Raw `box-shadow` values, `drop-shadow`, glow, or any depth effect not bound to a role token |
-| Title                    | `hds.typeStyles.heading3` / `<HdsText variant="heading3">`                                               | Any other type style for the primary card heading                                           |
+| Title                    | `hds.typeStyles.title` / `<Text variant="title">`                                                        | Any other type style for the primary card heading                                           |
 | Subtitle / meta          | `hds.typeStyles.caption` + `var(--semantic-color-content-secondary)`                                     | Primary content color or body size for secondary text                                       |
 | Hover (interactive only) | `transform: scale(1.02)`                                                                                 | Background fill change, border color shift, or opacity fade on hover                        |
 
@@ -164,7 +175,7 @@ Five patterns sit above the primitives so that every screen is composed the same
 
 ### Page title rule
 
-Every screen has exactly one `PageHeader`. The page title is `heading2` (30px), a fixed size with no size prop; `level` changes only the DOM heading element. `display` and `h1` are reserved for marketing and landing surfaces and are never a screen title. Breadcrumb goes in the `breadcrumb` slot, one status `Badge` in `status`, screen-level actions in `actions`.
+Every screen has exactly one `PageHeader`. The page title is `title` (24px), a fixed size with no size prop; `level` changes only the DOM heading element. `display` is reserved for marketing and landing surfaces and is never a screen title. Breadcrumb goes in the `breadcrumb` slot, one status `Badge` in `status`, screen-level actions in `actions`.
 
 ### Which one, when
 
@@ -176,14 +187,16 @@ Pick by what the thing is. The first four rows are for a headline number or a st
 | `Stat`               | An inline number inside prose or a dense list.                                | `MetricTiles` when the number stands alone in a row of its own.              |
 | `Card.Metric`        | A metric inside an existing `Card` only.                                      | `MetricTiles` when there is no enclosing `Card`.                             |
 | `StatusTile`         | State with notes and a trailing badge, never a number.                        | `MetricTiles` when the tile is a number; `StatusTile` never carries a value. |
-| `Card`               | A titled or interactive content object (header, body, footer, or selectable). | `Surface` when there is no title and nothing to press.                       |
+| `Card`               | A titled or interactive content object (header, body, footer, `selectable`).  | `Surface` when there is no title and nothing to press.                       |
 | `Surface`            | A plain padded background around content that has no header of its own.       | `Card` when the content is titled or interactive.                            |
 | `DestructiveSection` | The one irreversible action on a screen, with an explanation and a confirm.   | `FormActions` `destructive` slot for a delete beside a form's own buttons.   |
 | `DataTableSection`   | A titled table with a toolbar, row actions and an empty state.                | `Table` alone when there is no heading, toolbar or empty state to show.      |
 
+Three more needs are props on an existing component, not components of their own. A card people pick from a set is a `Card` with `selectable`, `selected` and `onSelectedChange`, announced as a checkbox. A wrapping row of equal tiles that are not headline numbers is a `Grid` with `layout="auto-fill"` and `minItemWidth`. A state shown only as a colored marker, with no notes, is a `Badge` with `dot` and a `label` that names the state.
+
 `Card` and `Surface` share one container radius, `rounded-lg` (`role.radius` + 4 px: 12 px by default, 4 px under `brutalist-demo`). Dialogs and alert dialogs use it too. Never read `--component-card-radius` for a container; it ignores the tenant.
 
-`MetricTiles` has `min(tiles, 4)` columns, so a row never leaves an empty column, and every tile has one fixed min-height with the value in `heading2`, the label as an eyebrow and the sub line in `caption`. Its tone comes from the fixed feedback vocabulary: `neutral | success | warning | danger | info`.
+`MetricTiles` has `min(tiles, 4)` columns, so a row never leaves an empty column, and every tile has one fixed min-height with the value in `title`, the label in `caption` and the sub line in `caption`. Its tone comes from the fixed feedback vocabulary: `neutral | success | warning | danger | info`.
 
 ### Destructive and table sections
 
@@ -215,6 +228,6 @@ Unresolved rules that the live repo cannot yet answer confidently are tracked in
 <!-- auto:start:build-meta -->
 ---
 
-> Generated from `hirobius.tokens.json` (381 tokens) and `public/hds-manifest.json` by `scripts/build-design-md.mjs`.
+> Generated from `hirobius.tokens.json` (389 tokens) and `public/hds-manifest.json` by `scripts/build-design-md.mjs`.
 > Hand-edit `DESIGN.source.md`; this file (`DESIGN.md`) is overwritten by `pnpm tokens`.
 <!-- auto:end:build-meta -->

package/NOTICE.md

@@ -3,7 +3,7 @@
 `@hirobius/design-system` is not under a single license.
 
 - **HDS code** (components, compiled JavaScript, types, CSS, and token files): MIT. See [LICENSE](LICENSE).
-- **Satoshi** (weights 500 and 700, by Indian Type Foundry, distributed through [Fontshare](https://www.fontshare.com/fonts/satoshi)): ITF Free Font License.
+- **Satoshi** (weights 400, 500 and 700, by Indian Type Foundry, distributed through [Fontshare](https://www.fontshare.com/fonts/satoshi)): ITF Free Font License.
 - **Geist Mono** (weight 400, by Vercel, [source](https://github.com/vercel/geist-font)): SIL Open Font License 1.1.
 
 Both fonts are embedded as base64 `@font-face` data in `dist/tokens.css` and `dist/styles.css`. The MIT license does not cover them; each font keeps its own license. `dist/variables.css` embeds no fonts.

package/README.md

@@ -12,9 +12,9 @@ pnpm add @hirobius/design-system
 
 <!-- auto:start:front-door-counts -->
 
-- **109** public component modules, exported from `src/index.ts`
-- **381** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
-- **484** Storybook stories in **121** story files
+- **53** public component modules, exported from `src/index.ts`
+- **389** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
+- **341** Storybook stories in **71** story files
 
 <!-- auto:end:front-door-counts -->
 
@@ -29,9 +29,12 @@ Agents: install the consumer skill with `npx skills add hirobius/hds --skill hds
 
 <!-- auto:start:consumer-usage -->
 
-The Ops dashboard (`hirobius/ops`) is the only verified component-level consumer: **35** of its source files import from `@hirobius/design-system`, using **25** distinct components. The two screenshots below are Ops pages rendered from its `main` (measured at commit `01fce2f`).
+The Ops dashboard (`hirobius/ops`) is the only product app that uses components: **33** of its source files import from `@hirobius/design-system`, using **25** distinct components. The two screenshots below are Ops pages rendered from its `main` (measured at commit `76ef65e`).
 
-Other consumers: the split into product apps and token-level sites is not yet confirmed, so it is not stated here.
+| Consumer kind     | Count | How it uses HDS                           |
+| ----------------- | ----- | ----------------------------------------- |
+| Product apps      | 1     | Components and tokens                     |
+| Token-level sites | 4     | Tokens and CSS only, no component imports |
 
 [![Ops library page](docs/images/ops-library.png)](docs/images/ops-library.png)
 
@@ -39,7 +42,36 @@ Other consumers: the split into product apps and token-level sites is not yet co
 
 <!-- auto:end:consumer-usage -->
 
-The numbers come from `pnpm consumer:usage --root <ops checkout>`, which measures that checkout and records its commit in `docs/data/consumer-usage.json`; without a root it reuses the committed snapshot. `scripts/__tests__/consumer-usage.test.mjs` fails if this section drifts from that snapshot. The product-app and token-level-site split is a declared figure in that file and stays out of this section until `consumersConfirmed` there is set to true.
+The numbers come from `pnpm consumer:usage --root <ops checkout>`, which measures that checkout's `src/` and records its commit in `docs/data/consumer-usage.json` (pass `--commit <sha>` when the root is a `git archive` export); without a root it reuses the committed snapshot. A deprecated alias counts as the component it points to (`HdsCheckbox` as `Checkbox`). The components that Ops's page- and video-clone prompts tell generated code to import are listed there as `promptContracts` and are not counted here. `scripts/__tests__/consumer-usage.test.mjs` fails if this section drifts from that snapshot. The product-app and token-level-site split is a declared figure in that file, not a measurement. It was confirmed on 2026-10-01 (hds#389: there is no second product app), so `consumersConfirmed` there is true and the table above shows it.
+
+## What belongs in the system
+
+<!-- auto:start:core-set -->
+
+**43** components are the core set: the brand-neutral, composable surface every HDS screen is built from, and the part of the system that has to be excellent. Import them from the package root; each carries `core: true` in `public/hds-manifest.json`.
+
+- **Actions:** `Button`
+- **Display:** `Avatar`, `Card`, `EmptyState`, `Field`, `Icon`, `Kbd`, `Table`
+- **Feedback:** `Alert`, `Badge`, `Progress`, `Skeleton`, `Spinner`, `ToastProvider`
+- **Inputs:** `Checkbox`, `Combobox`, `Input`, `Radio`, `SegmentedControl`, `Select`, `Slider`, `Tag`, `Textarea`, `Toggle`
+- **Layout:** `Box`, `Container`, `Disclosure`, `Divider`, `Grid`, `Stack`, `Surface`
+- **Navigation:** `Breadcrumb`, `InlineLink`, `Pagination`, `Tabs`
+- **Overlays:** `Dialog`, `Menu`, `Popover`, `Tooltip`
+- **Theming:** `HdsRouterProvider`, `HdsThemeProvider`
+- **Typography:** `Text`
+- **Utility:** `VisuallyHidden`
+
+**12** pattern modules ship from `@hirobius/design-system/patterns`, and only from there: composed surfaces that assume a product (page shells, forms, code blocks, page sections), built from the core set. One name per module; its parts and props types come with it.
+
+`AssetImg`, `CodeBlock`, `DataTableSection`, `DestructiveSection`, `ErrorPattern`, `Form`, `FormActions`, `MetricTiles`, `Page`, `PageHeader`, `Reveal`, `StatusTile`
+
+The package root also exports the rest of the allow-list (compound parts, and the components outside the core set; the [consumer skill](skills/hds-consumer/SKILL.md) lists them by category): reach for the core set first. 0.20.0 removed the root re-exports of the pattern modules, the docs internals and 13 components that fold into a survivor ([MIGRATIONS.md](MIGRATIONS.md#0200-removals-2026-10-01)).
+
+Every component's disposition (core, pattern, fold or internal) is in the [architecture doc](docs/hds-architecture-2026-09-18.html), ratified 2026-09-26 in [hds#254](https://github.com/hirobius/hds/issues/254); [ADR-031](docs/adr/031-core-set-and-dispositions.md) records the decision and what has changed since.
+
+<!-- auto:end:core-set -->
+
+This section is generated by `pnpm readme:counts` (which `pnpm tokens` also runs) from `scripts/lib/core-components.mjs`, `src/patterns.ts` and the manifest. `scripts/__tests__/core-set.test.mjs` fails if it drifts from them.
 
 ## Using the published package
 
@@ -51,7 +83,7 @@ guide: **[docs/CONSUMING.md](docs/CONSUMING.md)**.
 > `@hirobius/design-system` entry under GitHub Packages
 > (`/pkgs/npm/design-system`). That listing is **frozen and no longer updated** —
 > publishing moved to the public npm registry in
-> [#39](https://github.com/hirobius/hirobius-design-system/pull/39). Always
+> [#39](https://github.com/hirobius/hds/pull/39). Always
 > install from npm:
 > **[npmjs.com/package/@hirobius/design-system](https://www.npmjs.com/package/@hirobius/design-system)**.
 
@@ -63,8 +95,9 @@ npm install @hirobius/design-system react react-dom
 ```
 
 ```tsx
-// once at the app root — full bundle: tokens + theme + utilities + embedded fonts
+// once at the app root — full bundle: tokens + theme + utilities
 import '@hirobius/design-system/tokens.css';
+import '@hirobius/design-system/fonts.css'; // optional: the HDS brand fonts
 import { Button } from '@hirobius/design-system';
 
 // add data-hds to the root (or any section) so the scoped base styles apply
@@ -153,7 +186,7 @@ pnpm build-storybook
 
 HDS is built around three structural rules:
 
-- **Strict semantics** — public surfaces prefer system primitives such as `Stack`, `Grid`, `Surface`, and `TextLockup` instead of raw layout divs or ad hoc CSS.
+- **Strict semantics** — public surfaces prefer system primitives such as `Stack`, `Grid`, `Surface`, and `Text` instead of raw layout divs or ad hoc CSS.
 - **Polymorphism** — primitives preserve semantic HTML while staying composable through governed APIs such as `forwardRef`, `as`, and layout slots.
 - **12-column grid** — page structure follows a consistent editorial grid: readable center columns, intentional breakout zones, and explicit `gap` ownership rather than one-off spacing math.
 
@@ -165,6 +198,8 @@ Source-of-truth files:
 - `DESIGN.md` — lean visual spec for agents and engineers.
 - `DESIGN-HANDOFF.md` — verbose visual mirror for handoff and review.
 
+Which components belong in the system, and what happens to the rest, is decided in the [architecture doc](docs/hds-architecture-2026-09-18.html): every component is core, pattern, fold or internal, ratified 2026-09-26 in hds#254 and recorded in [ADR-031](docs/adr/031-core-set-and-dispositions.md). [What belongs in the system](#what-belongs-in-the-system) above lists the result.
+
 Component-by-component Figma links live in [docs/DESIGN_LINKS.md](docs/DESIGN_LINKS.md), generated by `pnpm figma:links`.
 
 ## Accessibility
@@ -173,10 +208,10 @@ What CI and the hooks check today, and nothing more:
 
 - **Contrast:** `scripts/check-contrast.mjs` enforces WCAG AA contrast on the core token pairs, in light and dark. It runs in CI and the pre-commit hook.
 - **Lint:** `jsx-a11y` rules run inside ESLint with zero warnings allowed.
-- **Focus:** `scripts/check-focus-states.mjs` (`pnpm check:focus`) audits focus styles on interactive components. It runs in the agent gate and on demand, not in the main CI workflow, and currently reports 1 violation (`src/app/components/asset-img.tsx`).
-- **Storybook:** the `addon-a11y` panel shows axe results for each story while you review it. It reports; it does not gate.
+- **Focus:** `scripts/check-focus-states.mjs` (`pnpm check:focus`) audits focus styles on interactive components. It runs in `pretest` under `pnpm test`, so in the pre-push hook and in CI, and passes with 0 violations.
+- **Storybook:** the `addon-a11y` panel shows axe results for each story while you review it. The gate is `scripts/check-storybook-axe.mjs`: CI scans every built story in light and dark, including the open Select and Combobox, and fails on serious or critical violations outside its allowlist (`scripts/axe-allowlist.json`). The allowlist has one entry: `aria-hidden-focus` on the open Select story, where Radix Select hides the page around its listbox while focus stays trapped inside it (hds#407).
 
-There is no automated screen-reader testing.
+Screen-reader output is checked by `tests/primitive-contracts/screen-reader.contract.test.tsx`, which runs in `pnpm test` and walks Dialog, Menu, Select, Combobox, Table and Alert with a virtual screen-reader (`@guidepup/virtual-screen-reader`) under jsdom, asserting the role, name and state phrases it reads and the alert's live-region announcement; it reads the jsdom accessibility tree, not what a desktop or mobile screen-reader says.
 
 ## Visual direction: Editorial Enterprise
 
@@ -201,7 +236,7 @@ The gates are deterministic and need no browser or live site:
 Three agents build the same Client-detail screen from the public docs, and `pnpm eval:consistency` measures how alike the results are: builds, token violations, axe, component-set overlap (Jaccard) and pixel diff. Today it runs the offline half over a directory of apps (`pnpm eval:consistency -- --apps <dir> --offline`, violations and Jaccard from source only). The ledger, the thresholds and the screen spec live in [`eval/consistency/`](eval/consistency/README.md). The latest recorded run, as printed by `pnpm eval:consistency -- --summary`:
 
 ```text
-Agent consistency 2026-09-30 (harness, design-system 0.18.0): FAIL - builds 3/3, violations 0, axe 0, Jaccard min 0.7368 (limit >= 0.85), light diff max 1.0268% (limit <= 1.5%)
+Agent consistency 2026-10-05 (harness, design-system 0.20.0): FAIL - builds 3/3, violations 0, axe 0, Jaccard min 0.4091 (limit >= 0.85), light diff max 3.2096% (limit <= 1.5%)
 ```
 
 The baseline misses its thresholds on purpose: they are not softened to make it pass.