@hirobius/design-system 0.17.0 → 0.19.0

package/CONSUMING.md

@@ -0,0 +1,150 @@
+# Consuming `@hirobius/design-system`
+
+The design system ships as an ESM package published to the **public npm
+registry**. This guide is for apps that want to use the components, tokens, and
+helpers.
+
+> For the full consumption guide (styles, `data-hds` scoping, routing seam, MUI
+> interop, forms, troubleshooting) see [`docs/CONSUMING.md`](docs/CONSUMING.md).
+
+## 1. Install
+
+No registry config, `.npmrc`, or auth token is required — it's public npm:
+
+```bash
+pnpm add @hirobius/design-system
+# peer dependencies (the consuming app provides these singletons):
+pnpm add react react-dom
+# react-router is an OPTIONAL peer — only if you drive links through your router
+```
+
+The package also pulls in its own runtime deps (Radix, lucide-react, motion,
+clsx, class-variance-authority, tailwind-merge) automatically. Import icons
+from `@hirobius/design-system/icons` (a curated Lucide set, nothing extra to
+install); for an icon outside it, install `lucide-react@0.487.0` (the same
+version keeps the `LucideIcon` type identical).
+
+## 2. Use
+
+```tsx
+import { Button, Card, Dialog } from '@hirobius/design-system';
+import '@hirobius/design-system/tokens.css'; // required — design tokens as CSS vars
+
+export function Example() {
+  return (
+    <Card>
+      <Button variant="primary">Hello</Button>
+    </Card>
+  );
+}
+```
+
+Available subpaths:
+
+| Import                               | What                                                                                                                                                                                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@hirobius/design-system`            | All components (primitives, patterns, templates)                                                                                                                                                                                            |
+| `@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                                                                                                                                                                                                                   |
+| `@hirobius/design-system/manifest`   | The HDS manifest JSON                                                                                                                                                                                                                       |
+| `@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/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,
+Remix, Webpack 5+) or a Node ≥ 20 ESM runtime. Built `.d.ts` declarations ship in
+`dist/types`, so TypeScript consumers get full types with no extra config.
+
+Every component's props type is exported under its own name — `AlertProps`,
+`ButtonProps`, `GridProps`, and so on — so wrapping one needs no
+`React.ComponentProps<typeof X>`:
+
+```tsx
+import { Alert, type AlertProps } from '@hirobius/design-system';
+
+export const Notice = (props: AlertProps) => <Alert tone="info" {...props} />;
+```
+
+Types that are implementation detail stay internal on purpose: the cva variant
+aliases, composition bases, and the props of sub-components the package does not
+export.
+
+**Next.js App Router / React Server Components.** Every React-bearing entry — the
+main barrel, `contexts`, `form`, `scroll`, `patterns` — ships with `'use client'`, so you can
+import components straight into a Server Component and they render as client
+components with no wrapper. The framework-free subpaths — `tokens`, `cn`,
+`manifest`, `brand`, `mui` — deliberately carry **no** directive: they have no
+React in them, and marking them would turn their exports into opaque client
+references when you use them on the server (`tokens.color.primary` in a layout,
+`brand` at the edge). Import those from server code freely.
+
+**Density.** Put `data-density="compact"` on the same `[data-hds]` scope element (or `<html>`) to tighten `semantic.space.scale.*`, surface padding and region gutter; `Table` follows it unless given a `density` prop.
+
+## 2.5. Lint discipline (optional)
+
+`@hirobius/eslint-plugin-hds` flags raw hex/px values in `style`, `className`,
+and `Box` `sx` props so token discipline shows up in your editor, not just at
+review time. See [`docs/CONSUMING.md` §11](docs/CONSUMING.md#11-lint-discipline--the-consumer-eslint-plugin)
+and [`scripts/eslint-plugin-hds/README.md`](scripts/eslint-plugin-hds/README.md).
+
+## 2.6. Agent context
+
+The package ships the docs written for agents, so an agent in your repo can read
+them without network access. Under `node_modules/@hirobius/design-system/`:
+
+- `llms.txt` (also `public/llms.txt`) - the system map and index of topic slices in `public/llms/`
+- `public/llms-full.txt` - the map, the full `DESIGN.md` and a props digest for every component
+- `DESIGN.md` - the lean visual spec
+- `src/app/data/component-api.json` - full prop reference
+
+The same files are served at <https://hirobius-design-system.vercel.app/llms.txt>
+(and `/llms-full.txt`, `/llms/components.txt`, `/DESIGN.md`, `/component-api.json`).
+
+## 3. Receiving updates
+
+Releases follow [semver](https://semver.org/) and are tracked in
+`CHANGELOG.md`. To update:
+
+```bash
+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.
+
+---
+
+### Maintainers: cutting a release
+
+```bash
+pnpm changeset add        # record a patch/minor/major bump + notes
+pnpm changeset:version    # apply bumps + regenerate CHANGELOG.md
+# commit + push to main → the Release workflow publishes to public npm
+```
+
+CI (`.github/workflows/release.yml`) automates steps 2–3 on merge to `main`.
+
+Publishing to npm uses **Trusted Publishing (OIDC)**: no npm token exists. The
+package's Trusted Publisher entry on npmjs.com (org `hirobius`, repo `hds`,
+workflow `release.yml`, no environment) lets the workflow mint a short-lived
+publish credential per run. If a publish fails with `ENEEDAUTH`/`E404`, that
+entry is missing or no longer matches the workflow filename.
+
+One repo secret is required, and the workflow fails loudly naming it if it is
+missing or expired:
+
+| Secret        | What it does                                                                                                                                            | If it lapses                                             |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `RELEASE_PAT` | Authors the "Version Packages" PR and pushes tags. A **fine-grained** PAT scoped to `hirobius/hds` with Contents + Pull requests set to Read and write. | The run fails at the guard step, before anything builds. |
+
+`RELEASE_PAT` exists because GitHub does not start workflow runs from events
+created with `GITHUB_TOKEN`. With `GITHUB_TOKEN`, `ci.yml` never fires on the
+release PR, so the required `Lean gate set` check cannot run and the PR is
+unmergeable. A user-owned token is not subject to that guard, so the release PR
+is tested like any other PR. Fine-grained tokens expire — when this one does,
+the failure names the secret and the fix rather than silently reverting to the
+deadlock.

package/DESIGN.md

@@ -0,0 +1,220 @@
+<!-- GENERATED FILE — DO NOT EDIT. Source: DESIGN.source.md. Regenerate with `pnpm tokens`. -->
+
+# DESIGN.md
+
+A machine- and human-readable specification of the Hirobius Design System for AI agents, design tools, and humans generating or reviewing UI. Values are sourced from `hirobius.tokens.json`; narrative rules are hand-authored. For the full tokens reference see `DESIGN-HANDOFF.md`.
+
+## Overview
+
+Hirobius is a clean, systems-first visual language that bridges digital precision and physical fabrication through a high-contrast monochromatic palette and a single accent that each tenant sets — neutral by default (#208). Its personality is disciplined, tactile, and quietly technical: structure is explicit, motion is purposeful, and visual noise is stripped away. Whitespace is treated as material, not leftover space, so every screen should feel deliberate, breathable, and exact.
+
+## Colors
+
+<!-- auto:start:colors -->
+**One accent — one neutral system.**
+
+- **Accent** (`#111111`): CTAs, active states, selected focus rings, and the single brand accent. `semantic.accent.rest` — a per-tenant knob, not a fixed hue (#208).
+- **Neutral**: backgrounds, surfaces, borders, text. True monochromatic — `primitive.color.neutral.50` through `950`. Use `semantic.color.surface.*`, `semantic.color.content.*`, `semantic.color.border.*`; never reach directly for primitives in components.
+- **Feedback — Error** (`#B91C1C`): destructive confirms, error banners, validation failures. `semantic.color.feedback.error`.
+- **Feedback — Success** (`#047857`): positive confirmations, completed states. `semantic.color.feedback.success`.
+- **Feedback — Warning** (`#92400E`): cautions, recoverable issues. `semantic.color.feedback.warning`.
+- **Feedback — Info** (`#1E2EFD`): neutral announcements and inline guidance. `semantic.color.feedback.info`.
+
+Feedback hues are never decorative; do not use them as accents. Light and dark mode values are defined per-token in `hirobius.tokens.json`.
+<!-- auto:end:colors -->
+
+## Typography
+
+<!-- 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.
+- **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.
+
+### 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.lineHeight.none` |  |  | Semantic alias for leading-none (1) |
+
+> Responsive `clamp()` overrides live in `src/styles/theme.css`; tokens store the desktop-max static value.
+<!-- auto:end:typography -->
+
+## Spacing
+
+<!-- auto:start:spacing -->
+**Base unit: 4px.** All spacing snaps to the primitive scale; never introduce half-steps or arbitrary px values.
+
+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.
+<!-- auto:end:spacing -->
+
+## 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.
+
+<!-- auto:start:radius -->
+| Tier | Value | Token | Applies to |
+| --- | --- | --- | --- |
+| Action | `8px` | `semantic.radius.action` | Buttons, inputs, badges, alerts, disclosures, segmented control items |
+| Container | `12px` | `role.radius` + 4px (`rounded-lg`) | Cards, surfaces, segmented control surface, modal/sheet containers |
+| Full | `9999px` | `primitive.radius.full` | Pills, avatars, indicator dots, any intentionally circular form |
+| Zero | `0px` | `primitive.radius.0` | Outer canvas / substrate boundaries only — never on everyday UI controls |
+<!-- auto:end:radius -->
+
+## Elevation
+
+Depth is communicated through 4 elevation roles bundled by `semantic.elevation.*`. Each role bundles a surface, shadow, and border so primitives can't mismatch them.
+
+### Elevation roles
+
+| Surface                                | Role token                    | Background        | Shadow            | Border              |
+| -------------------------------------- | ----------------------------- | ----------------- | ----------------- | ------------------- |
+| Card / panel resting                   | `semantic.elevation.flat`     | `surface.page`    | none              | `border.subtle` 1px |
+| Card / panel lifted (interactive only) | `semantic.elevation.raised`   | `surface.raised`  | `shadow.subtle`   | none                |
+| Popover / dropdown / tooltip           | `semantic.elevation.floating` | `surface.raised`  | `shadow.floating` | none                |
+| Dialog / sheet / modal                 | `semantic.elevation.overlay`  | `surface.overlay` | `shadow.overlay`  | none                |
+
+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.
+
+## Motion
+
+<!-- auto:start:motion -->
+Motion (lift on hover, parallax) is the interaction-affordance layer; static depth comes from the `semantic.elevation.*` role-token bundles.
+
+### Duration tiers
+
+| Tier | Value | When to use |
+| --- | --- | --- |
+| `primitive.duration.instant` | `100ms` | Immediate dismissals, binary toggles |
+| `primitive.duration.short` | `150ms` | Productive micro-interactions (default for hover/focus/press) |
+| `primitive.duration.medium` | `250ms` | Expressive entrances, teaching moments |
+| `primitive.duration.long` | `400ms` | Spatial movement, page travel, parallax |
+
+### Semantic intents
+
+| Intent | Duration | Purpose |
+| --- | --- | --- |
+| `semantic.motion.productive` | `150ms` | For micro-interactions and status changes. No deformation. |
+| `semantic.motion.expressive` | `250ms` | For teaching moments and significant UI entries. Includes physics-based squish. |
+| `semantic.motion.spatial` | `400ms` | For elements traveling long distances across the viewport. |
+| `semantic.motion.exit` | `100ms` | For elements being removed from the DOM. |
+
+Default most interactive feedback to `productive` (150ms, decelerate). Reserve `expressive` (250ms, spring) for teaching moments where the motion itself carries meaning. `spatial` (400ms) is for travel, not decoration.
+
+### Other semantic motion tokens
+
+| 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). |
+<!-- auto:end:motion -->
+
+## Components
+
+<!-- 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`. |
+| **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. |
+| **Alerts** (`Alert`) | `8px` (via `hds.borderRadius.4`) | info · success · warning · error | Inline banner pattern with icon + message + optional action. Tone is carried by left-border color, not by tinted fills. |
+| **Disclosures** (`Disclosure`) | `8px` (`hds.borderRadius.action`) | collapsed · expanded · hover · focus | Accordion primitive. Expansion uses `semantic.motion.productive`; no spring bounce. Dividers follow `semantic.color.border.subtle`. |
+| **Toggles** (`Toggle`) | `full` (pill track + circular thumb) | off · on · focus · disabled | Accent-filled track in the on state; neutral track otherwise. Track + thumb transitions share `semantic.motion.productive`. |
+| **Segmented Control** (`SegmentedControl`) | Outer `12px` · inner segments `8px` | rest · hover · selected · disabled | Selected segment fills with the accent; unselected segments are transparent. Use for 2–5 mutually exclusive options; beyond that, prefer `Select`. |
+
+See `public/hds-manifest.json` and `src/app/data/component-api.json` for the full inventory and prop tables.
+<!-- auto:end:components -->
+
+### Card Anatomy (mandatory — all properties non-negotiable)
+
+Every HDS card surface must conform to this anatomy exactly. No creative interpretation is permitted on any of these properties.
+
+| Property                 | Required value                                                                                           | Forbidden                                                                                   |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Background               | `var(--semantic-color-surface-raised)`                                                                   | Any gradient, tinted fill, or custom color                                                  |
+| Border                   | `1px solid var(--semantic-color-border-default)`                                                         | `box-shadow` as an elevation substitute                                                     |
+| 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                                           |
+| 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                        |
+
+Never use on any card surface: gradient backgrounds, glow effects, frosted glass (`backdrop-filter: blur`), decorative overlays, gradient borders, colored or tinted backgrounds, inner shadows, patterned fills, shimmer or noise effects.
+
+## Screen Patterns
+
+Five patterns sit above the primitives so that every screen is composed the same way. Import them from `@hirobius/design-system/patterns`.
+
+### 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`.
+
+### Which one, when
+
+Pick by what the thing is. The first four rows are for a headline number or a state; the rest are for containers and sections.
+
+| Component            | Use it for                                                                    | Use instead                                                                  |
+| -------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `MetricTiles`        | The default for any row of headline numbers on a screen. One fixed tile size. | Nothing: start here.                                                         |
+| `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.                       |
+| `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.      |
+
+`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`.
+
+### Destructive and table sections
+
+`DestructiveSection` is a titled danger zone with one danger `Button` that opens an `AlertDialog`; it never runs the action from the button itself, only from the dialog's confirm. Put it last on the screen, below the form. `DataTableSection` puts a `Table` under a heading and a toolbar slot. Row actions are consumer nodes in a trailing column, an empty `rows` array shows an `EmptyState`, and the table scrolls horizontally inside the section on narrow widths, so a caller never sets `minWidth`.
+
+### Form actions rule
+
+`FormActions` puts the primary submit last in DOM order and right-most, with the secondary or cancel action immediately to its left. A destructive action goes on the far left, apart from the other two, and never to the right of the primary. The row is not sticky unless `sticky` is set.
+
+## Do's and Don'ts
+
+- Don't invent new corner behavior for interactive controls; buttons, inputs, disclosures, and similar action surfaces should follow the shared action radius (`semantic.radius.action`).
+- Don't introduce additional accent hues; Hirobius uses exactly one accent, resolved from `semantic.accent.rest`, over a true monochromatic neutral system. The accent is a per-tenant knob (#208) and defaults to neutral — read the token, never assume a hue.
+- Don't tint neutrals warm or cool; greys should remain genuinely neutral and high-contrast.
+- Don't reach for shadow values directly — bind to a `semantic.elevation.*` role so surface + shadow + border stay paired. Cards default to `flat` (border, no shadow). Popovers/tooltips/dropdowns use `floating`. Dialogs/sheets use `overlay`.
+- Don't hardcode colors, spacing, radius, or typography values when governed tokens already exist.
+- Don't crowd the canvas; if a layout feels compressed, remove complexity before removing breathing room.
+- Don't default repeated roadmap, status, process, or overview groups to outlined cards; prefer open bands, section dividers, accent rails, tabs, disclosures, and whitespace. Cards are for genuinely discrete repeated objects, not the primary layout language.
+- Don't sticker badges onto the ends of prose lines. Status and progress should live in a predictable metadata slot, rail, header zone, table column, or progress surface; badges are reserved for compact state markers where their placement is intentional.
+- Don't add decorative illustration, ornamental icons, or trend-driven filler that lacks functional or structural purpose.
+- Don't make motion playful or bouncy by default; movement should feel controlled, precise, and intentional, with expressive motion used sparingly and only when it teaches or clarifies.
+- Don't add `whileTap` scale transforms for press feedback; use color, border, and state-contrast changes instead — transforms are reserved for spatial motion, not interaction acknowledgment.
+- Don't define a global disabled-state rule (opacity multiplier, saturation ramp, etc.); disabled presentation is governed per-component through its dedicated disabled tokens.
+
+## Open Questions
+
+Unresolved rules that the live repo cannot yet answer confidently are tracked in [`OPEN_DS_QUESTIONS.md`](OPEN_DS_QUESTIONS.md). Do not invent rules here to fill those gaps.
+
+<!-- auto:start:build-meta -->
+---
+
+> Generated from `hirobius.tokens.json` (381 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/README.md

@@ -13,8 +13,8 @@ pnpm add @hirobius/design-system
 <!-- auto:start:front-door-counts -->
 
 - **109** public component modules, exported from `src/index.ts`
-- **379** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
-- **455** Storybook stories in **115** story files
+- **381** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
+- **484** Storybook stories in **121** story files
 
 <!-- auto:end:front-door-counts -->
 
@@ -23,6 +23,24 @@ pnpm add @hirobius/design-system
 
 The counts are generated from source by `pnpm readme:counts`, which `pnpm tokens` also runs. `scripts/__tests__/front-door.test.mjs` fails if this README claims more than the source has.
 
+Agents: install the consumer skill with `npx skills add hirobius/hds --skill hds-consumer` (see `docs/CONSUMING.md`, "Agent skill").
+
+## In use
+
+<!-- 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`).
+
+Other consumers: the split into product apps and token-level sites is not yet confirmed, so it is not stated here.
+
+[![Ops library page](docs/images/ops-library.png)](docs/images/ops-library.png)
+
+[![Ops fleet audit page](docs/images/ops-fleet-audit.png)](docs/images/ops-fleet-audit.png)
+
+<!-- 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.
+
 ## Using the published package
 
 Installing HDS in another project? It ships to the **public npm registry** as
@@ -178,6 +196,16 @@ The gates are deterministic and need no browser or live site:
 - **CI** (`.github/workflows/ci.yml`): typecheck, zero-warning ESLint, token validity and contrast, Vitest, and the consumer smoke build, plus bundle budgets and a Storybook build.
 - **Visual review:** Storybook is the visual verification surface, reviewed by hand. The earlier browser test suite drove a docs site that no longer exists and was removed (ADR-018).
 
+### Agent consistency
+
+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%)
+```
+
+The baseline misses its thresholds on purpose: they are not softened to make it pass.
+
 `CLAUDE.md` is the operating contract for agents working in this repo.
 
 ## Bundle and release hygiene