@hirobius/design-system 0.23.2 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.24.0
+
+### Upgrade
+
+```sh
+npx @hirobius/design-system@latest upgrade
+```
+
+- Do by hand: The --primitive-color-apple-100 variable is gone; use --primitive-color-graphite-100 for the same accent step.
+- Do by hand: The --primitive-color-apple-200 variable is gone; use --primitive-color-graphite-200 for the same accent step.
+- Do by hand: The --primitive-color-apple-300 variable is gone; use --primitive-color-graphite-300 for the same accent step.
+- Do by hand: The --primitive-color-apple-400 variable is gone; use --primitive-color-graphite-400 for the same accent step.
+- And 31 more: see [UPGRADING.md](https://github.com/hirobius/hds/blob/main/UPGRADING.md#0240).
+
+### Minor Changes
+
+- 72800bc: feat(brand): change the default accent from apple green to graphite (warm charcoal).
+
+  The base brand accent moves from the bright apple green shipped in 0.23.0 to a warm
+  graphite — a full-monochrome accent that reads calmer and more considered. A new
+  `primitive.color.graphite` scale replaces `primitive.color.apple`; feedback hues
+  (`green`/`red`/`amber` for success/danger/warning) are untouched, so the system stays
+  monochrome without flattening its status colors.
+  - `semantic.accent.{rest,hover,pressed,content,contentHover,subtle}`, `semantic.color.surface.accent`/`accentSubtle`, `semantic.color.content.accent`, and `semantic.color.border.accent` now resolve through `primitive.color.graphite.*`.
+  - The accent **inverts per theme** so fills never vanish on a dark page: a dark graphite step in light mode (near-white on-accent text) and a light warm-grey step in dark mode (dark on-accent text). `semantic.color.content.onAccent` flips to `neutral.50` in light mode and `graphite.900` in dark mode — `content.onAccent / surface.accent` is 10.5:1 light / 10.0:1 dark.
+  - Per-tenant accents are unchanged: `accent-lilac` and `concrete-creations` set their own accent (and their own `onAccent`); `brutalist-demo` inherits the new graphite base.
+
+  The `--primitive-color-apple-*` CSS variables (introduced in 0.23.0) are removed in favor of `--primitive-color-graphite-*`; consumers who referenced a raw accent primitive should repoint to the graphite scale, though the semantic accent tokens are the intended surface and the per-tenant accent knob is unchanged — set your own accent overlay to override the base.
+
+### Patch Changes
+
+- 72800bc: fix(theming): the font dial now works.
+
+  Setting `--hds-font-family` / `--hds-font-family-mono` (or `<HdsThemeProvider fontFamily fontFamilyMono>`) used to change nothing: the type roles were resolved once on `:root`, so descendants inherited the default stack. They are now re-declared on each element of the `[data-hds]` subtree, so the dial applies at whatever scope you set it — headings, body, UI text, captions, code, and the JS style objects (`hds.fontFamily`, `hds.typeStyles`) all follow it. With no override, nothing changes: the default is still the brand typeface.
+
+- 72800bc: feat(tokens): add a reserved mauve primitive scale.
+
+  `primitive.color.mauve.{50…950}` (anchor `#734B5E` at 500) is added alongside graphite, lightness-matched to it step for step. Nothing maps to it yet: graphite stays the brand accent, and no semantic or component token reads mauve. It is available as `--primitive-color-mauve-*` for exploration.
+
 ## 0.23.2
 
 ### Upgrade

package/DESIGN.md

@@ -6,14 +6,14 @@ A machine- and human-readable specification of the Hirobius Design System for AI
 
 ## Overview
 
-Hirobius is a clean, systems-first visual language that bridges digital precision and physical fabrication through a high-contrast monochromatic neutral palette and a single accent that each tenant sets — a bright apple green by default. 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.
+Hirobius is a clean, structured visual language that bridges digital precision and physical fabrication through a high-contrast monochromatic neutral palette and a single accent that each tenant sets — a warm graphite by default. 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** (`#66B239`): CTAs, active states, selected focus rings, and the single brand accent. `semantic.accent.rest` — a per-tenant knob, not a fixed hue (#208).
+- **Accent** (`#433A3F`): 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`.
@@ -26,10 +26,9 @@ Feedback hues are never decorative; do not use them as accents. Light and dark m
 ## Typography
 
 <!-- auto:start:typography -->
-HDS ships three typefaces — each with a distinct and exclusive role:
+HDS ships two typefaces:
 
-- **Display / Heading font**: Plus Jakarta Sans. Bound exclusively to the `display` and `title` styles. Never used for body copy or UI labels.
-- **Body / UI font**: Plus Jakarta Sans. All prose, labels, small text, captions, and UI copy.
+- **Text font**: Plus Jakarta Sans. Headings, prose, labels, captions, and UI copy; the type roles set size and weight.
 - **Mono font**: IBM Plex Mono. Reserved for tokens, code, technical callouts, and metric readouts.
 
 Weights declared: `400` regular, `500` medium, `700` bold. Heading styles (display · title) use `700` bold; body, UI, and caption use `400` regular / `500` medium.
@@ -65,7 +64,7 @@ Layout rhythm, padding, and gaps use the `semantic.space.scale.{xs…xl}` steps
 
 ## 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`).
+Approved 2026-10-07 as the **target**; adoption is in progress, so some components below (Container, Sidebar, Switcher) still ship until they fold in. 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"`.
@@ -209,7 +208,7 @@ Three more needs are props on an existing component, not components of their own
 ## 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 a bright apple green — read the token, never assume a hue.
+- 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 and defaults to a warm graphite — 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.
@@ -223,11 +222,11 @@ Three more needs are props on an existing component, not components of their own
 
 ## 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.
+Unresolved rules that the live repo cannot yet answer confidently are tracked as GitHub issues. Do not invent rules here to fill those gaps.
 
 <!-- auto:start:build-meta -->
 ---
 
-> Generated from `hirobius.tokens.json` (400 tokens) and `public/hds-manifest.json` by `scripts/build-design-md.mjs`.
+> Generated from `hirobius.tokens.json` (411 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

@@ -18,40 +18,42 @@ Upgrading: [UPGRADING.md](UPGRADING.md) lists what each release asks of you. Fro
 <!-- auto:start:front-door-counts -->
 
 - **53** public component modules, exported from `src/index.ts`
-- **400** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
+- **411** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
 
 <!-- auto:end:front-door-counts -->
 
 What the system includes:
 
 - **Token pipeline.** DTCG tokens in `hirobius.tokens.json` compile to CSS variables and TypeScript constants through a validated alias chain, with AA-contrast gates in light and dark.
-- **Gates with proof-of-firing.** Typecheck, zero-warning ESLint, token validity and contrast, Vitest unit and contract tests, bundle budgets, a consumer smoke build, and a docs-site build with an axe gate — run in git hooks and CI. Many gates carry a passing and a violating fixture that demonstrate the gate catches what it describes.
+- **Gates with proof-of-firing.** Typecheck, zero-warning ESLint, token validity and contrast, Vitest unit and contract tests, and a consumer smoke build run in git hooks and CI; bundle budgets and a docs-site accessibility (axe) gate run in CI. Many gates carry a passing and a violating fixture that demonstrate the gate catches what it describes.
 - **Upgrade path.** A release ledger and one consumer command: `npx @hirobius/design-system@latest upgrade`.
 - **One-way Figma sync.** Code is the source of truth; tokens project into Figma, and `pnpm check:figma-drift` compares a committed snapshot against the model.
 - **Theming without JavaScript.** Four root attributes — theme, density, brand, font — re-skin HDS descendants through CSS variables.
 
 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.
 
+**How it's built:** [How HDS is engineered](docs/ENGINEERING.md) walks the token pipeline, the quality gates (and how they're proven to fire), testing, release and upgrade, and Figma sync.
+
 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 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`).
+An internal operations dashboard 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 pages of that app, rendered from its `main` branch.
 
 | 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)
+[![Library page of the product app](docs/images/product-app-library.png)](docs/images/product-app-library.png)
 
-[![Ops fleet audit page](docs/images/ops-fleet-audit.png)](docs/images/ops-fleet-audit.png)
+[![Audit page of the product app](docs/images/product-app-audit.png)](docs/images/product-app-audit.png)
 
 <!-- auto:end:consumer-usage -->
 
-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.
+The numbers come from `pnpm consumer:usage --root <consumer 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 the app'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 (there is no second product app), so `consumersConfirmed` there is true and the table above shows it.
 
 ## What belongs in the system
 
@@ -235,7 +237,7 @@ The governing direction is "Editorial Enterprise" — enterprise rigor with edit
 
 The gates are deterministic and need no browser or live site:
 
-- **pre-commit** (`.husky/pre-commit`): secrets scan, Prettier on staged files, typecheck, zero-warning ESLint, and token validity and contrast.
+- **pre-commit** (`.husky/pre-commit`): secrets scan (when `gitleaks` is installed locally; not yet in CI), Prettier on staged files, typecheck, zero-warning ESLint, and token validity and contrast.
 - **pre-push** (`.husky/pre-push`): `pnpm test` (the pretest gates, then Vitest unit and contract tests), then the consumer smoke build (library build, subpath resolution, publint, consumer typecheck).
 - **CI** (`.github/workflows/ci.yml`): typecheck, zero-warning ESLint, token validity and contrast, Vitest, and the consumer smoke build, plus bundle budgets and the docs-site build with its axe gate.
 - **Visual review:** the docs site (`docs-site/`) is the visual verification surface: every core component and pattern has a page with a live demo, `check-docs-axe` gates its accessibility.
@@ -263,18 +265,26 @@ Releases are cut with [Changesets](https://github.com/changesets/changesets). A
 ```text
 src/
   app/
-    components/
-    layouts/
-    pages/
-  styles/
-scripts/
-docs/
-public/
+    components/     the components
+    context/        theme provider
+    design-system/  generated token constants
+  styles/           tokens.css, theme.css, generated CSS
+  brand/ form/ mui/ scroll/   subpath entry points
+hirobius.tokens.json  the single token source
+scripts/            generators and gates
+codemods/           the upgrade command and its codemods
+mcp/                the MCP server shipped in the package
+docs-site/          the documentation site
+content/            docs-site pages
+eval/               agent-consistency eval
+docs/               ADRs, ENGINEERING.md, guardrail registry
+public/             manifest, llms.txt
 ```
 
 ## Primary docs
 
 - [`docs/CONSUMING.md`](docs/CONSUMING.md) — installing & using the published package
+- [`docs/ENGINEERING.md`](docs/ENGINEERING.md) — how the system is built (pipeline, gates, release, Figma sync)
 - `CLAUDE.md` — agent operating contract
 - `DESIGN.md` — lean visual spec
 - `DESIGN-HANDOFF.md` — verbose visual mirror

package/UPGRADING.md

@@ -1,6 +1,6 @@
 # Upgrading @hirobius/design-system
 
-This file only knows the releases up to the version you have installed, 0.23.2. For newer releases, run `npx @hirobius/design-system@latest upgrade`: it always fetches the newest steps.
+This file only knows the releases up to the version you have installed, 0.24.0. For newer releases, run `npx @hirobius/design-system@latest upgrade`: it always fetches the newest steps.
 
 ## How to upgrade
 
@@ -10,6 +10,51 @@ npx @hirobius/design-system@latest upgrade
 
 It finds the version you have, moves you to the newest release, runs each release's codemods (Fixed for you) and lists what is left for you (Do by hand). It works from 0.16.0 on; from an older version, first reach 0.16.0 with the notes in CHANGELOG.md. MIGRATIONS.md has longer guides for the big releases.
 
+## 0.24.0
+
+Released 2026-10-12 (minor). 11 changes to make by hand (11 breaking) and 24 that look different.
+
+### Looks different
+
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the code-font dial (--hds-font-family-mono) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- Accent-intent text and icons (such as links) now render in graphite instead of a dark apple green.
+- Hovered accent text now shifts within the graphite scale instead of toward a darker apple green.
+- The accent fill on hover is now a deeper graphite (light mode) or lighter warm-grey (dark mode) instead of a green.
+- The accent fill while pressed is now a darker graphite (light mode) or lighter warm-grey (dark mode) instead of a green.
+- Interactive accent fills at rest (primary buttons, selected controls) now render in warm graphite — a dark fill in light mode and a light warm-grey fill in dark mode — instead of a bright apple green.
+- The low-emphasis accent tint (hover and selection backgrounds) is now a faint graphite tint instead of a faint apple green.
+- Accent borders now render in graphite instead of apple green.
+- Accent-intent text and icons on page and card surfaces now render in graphite instead of a dark apple green.
+- Text and icons on accent fills are now near-white in light mode and dark graphite in dark mode (the fill inverts per theme), instead of a dark neutral in both modes.
+- Accent background surfaces now render in warm graphite that inverts per theme instead of a bright apple green.
+- Faint accent background surfaces are now a pale graphite tint instead of a pale apple green.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the code-font dial (--hds-font-family-mono) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+- This variable now follows the font dial (--hds-font-family) at any scope; if you overrode it directly, override the dial instead.
+
+### Do by hand
+
+- The --primitive-color-apple-100 variable is gone; use --primitive-color-graphite-100 for the same accent step.
+- The --primitive-color-apple-200 variable is gone; use --primitive-color-graphite-200 for the same accent step.
+- The --primitive-color-apple-300 variable is gone; use --primitive-color-graphite-300 for the same accent step.
+- The --primitive-color-apple-400 variable is gone; use --primitive-color-graphite-400 for the same accent step.
+- The --primitive-color-apple-50 variable is gone; use --primitive-color-graphite-50 for the same lightest accent step.
+- The --primitive-color-apple-500 variable is gone; use --primitive-color-graphite-500 (or a semantic accent token) instead.
+- The --primitive-color-apple-600 variable is gone; use --primitive-color-graphite-600 for the same accent step.
+- The --primitive-color-apple-700 variable is gone; use --primitive-color-graphite-700 for the rest accent step.
+- The --primitive-color-apple-800 variable is gone; use --primitive-color-graphite-800 for the same accent step.
+- The --primitive-color-apple-900 variable is gone; use --primitive-color-graphite-900 for the same accent step.
+- The --primitive-color-apple-950 variable is gone; use --primitive-color-graphite-950 for the darkest accent step.
+
 ## 0.23.2
 
 Released 2026-10-11 (patch). 2 that look different.