@hirobius/design-system 0.22.0 → 0.23.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # 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 -->
+<!-- Generated by scripts/generate-agents-md.mjs from mcp/guide.mjs, src/app/data/component-api.json and content/docs/voice.mdx. 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.
 
@@ -79,6 +79,16 @@ One answer per need. Use the components after the arrow; what follows "Not:" is
 - 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.
 
+## Voice
+
+How these docs speak. Every page, and every agent writing for HDS, follows it. Source: `content/docs/voice.mdx` (published at `/docs/voice`).
+
+- Use plain words a reader already knows. Name a thing by what it does, not by how it is built.
+- Keep sentences short, one idea each.
+- Tell the reader what to do. Leave out brand adjectives.
+- Keep maintainer references off public pages: issue and ADR numbers, script names, internal counts.
+- Don't use: "systems-first".
+
 ## Finish with the lint plugin
 
 The ESLint plugin ships in this package. Pass its `recommended` rules before you report done:

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## 0.23.1
+
+### Upgrade
+
+```sh
+npx @hirobius/design-system@latest upgrade
+```
+
+- Looks different: The scoped HDS font variable now names Plus Jakarta Sans first instead of Satoshi.
+- Looks different: Display and title text now renders in Plus Jakarta Sans instead of Satoshi.
+- Looks different: Body, UI and caption text now renders in Plus Jakarta Sans instead of Satoshi.
+- Looks different: fonts.css no longer declares Satoshi 400; it declares Plus Jakarta Sans 400 instead, so drop any font-family: Satoshi of your own.
+- And 2 more: see [UPGRADING.md](https://github.com/hirobius/hds/blob/main/UPGRADING.md#0231).
+
+### Patch Changes
+
+- d907e73: CONSUMING.md points agents at the docs site (https://hirobius-hds-components.vercel.app/llms.txt), which now serves the llms files, the manifest, DESIGN.md and component-api.json.
+- 29af78f: feat(brand): the primary and display typeface is now Plus Jakarta Sans.
+
+  Satoshi's license (the Fontshare FF EULA) does not allow the font files to be redistributed, so HDS could not keep shipping them in the package or a public repo. Plus Jakarta Sans (Tokotype, SIL Open Font License 1.1) replaces it in the same three weights: 400 body, 500 UI and captions, 700 display and titles.
+  - `primitive.typography.family.primary` and `.display` now start with `"Plus Jakarta Sans"`, with the same system fallback stack.
+  - `@hirobius/design-system/fonts.css` now declares Plus Jakarta Sans 400/500/700, as Latin-subset woff2 files of about 15 KB each (Satoshi's were about 26 KB). The OFL license text ships beside the fonts in `dist/fonts/`.
+  - `package.json` `license` is now `MIT AND OFL-1.1`, since every bundled font is OFL.
+  - `ch`-based widths read a little wider in Figma, because the "0" advance is 0.732em instead of 0.683em.
+
+  Visual-only, with no API changes. If you import `fonts.css`, the new face loads with nothing else to do.
+
+## 0.23.0
+
+### Upgrade
+
+```sh
+npx @hirobius/design-system@latest upgrade
+```
+
+- Looks different: Accent-intent text and icons (such as links) now render in a dark apple green instead of a dark neutral.
+- Looks different: Hovered accent text now shifts to a darker apple green instead of a darker neutral.
+- Looks different: The accent fill on hover is now a deeper apple green instead of a dark neutral.
+- Looks different: The accent fill while pressed is now a darker apple green instead of a near-black neutral.
+- And 10 more: see [UPGRADING.md](https://github.com/hirobius/hds/blob/main/UPGRADING.md#0230).
+
+### Minor Changes
+
+- 8edd926: The code font is now IBM Plex Mono 400 (OFL-1.1), replacing Geist Mono. The `primitive.typography.family.mono` token value changes (names unchanged), `fonts.css` ships `ibm-plex-mono-400.woff2` instead of `geist-mono-400.woff2`, and the 13px mono role is unchanged. Figma needs the IBM Plex Mono font installed before `figma:push`.
+
+### Patch Changes
+
+- 66cb4e2: fix(a11y): Tier-2 accessibility fixes across the primitives.
+  - **Radio / Checkbox / Toggle** show a keyboard focus ring only on `:focus-visible` (not on mouse click), and focus is no longer masked by hover (focus now outranks hover in `useInteractionState`).
+  - **Input / Textarea / FormField** no longer point `aria-describedby` at a description that isn't rendered (error replaces helper); `Input`'s `loading` uses `readOnly` + `aria-busy` instead of `disabled`, so a search-as-you-type field keeps focus.
+  - **Select** renders a real `<label htmlFor>` wired to the trigger, so clicking the label focuses it.
+  - **Combobox** keyboard: options are not tab stops, Arrow keys skip disabled options and scroll the active one into view, option ids are index-based (no break on special chars), and the active index resets on open / option change.
+  - **Tabs** focus ring is `ring-inset` so it isn't clipped by the scroll container.
+  - **InlineLink** only treats a single-leading-slash path as an internal router link (not `//host`); `mailto:`/`tel:`/`#hash` are plain same-tab links; external links keep `target=_blank` + a visually-hidden "(opens in new tab)"; the internal branch gains `hds-focus`.
+
+- c88ab39: fix(feedback): unify Alert + Callout on one tinted-fill tone language.
+
+  The two feedback components carried tone in opposite ways — Alert by a tinted fill (`bg-feedback-bg-*`), Callout by a 3px colored left stripe — reading as two systems, and the stripe was the lone >1px colored side-rule anti-pattern left in the set. DESIGN.md also still claimed Alert carries tone "by left-border color, not by tinted fills", which the shipped Alert already contradicted.
+  - **Callout** now uses the same tinted feedback fill as Alert (rounded, no stripe); `accent` (not a feedback state) takes a neutral `bg-muted` fill. It stays distinct from Alert by role — no icon, no status role, optional `italic` — not by mechanism.
+  - **Alert** unchanged (already fill-based).
+  - **DESIGN.md** (via build-design-md.mjs) corrected: tone is carried by a tinted feedback fill, not a left-border stripe.
+
+  Visual change to Callout; no API change.
+
+- c88ab39: feat(brand): set the default accent to a bright apple green.
+
+  The base brand accent moves from a neutral (monochrome) to a bright apple green. A
+  new `primitive.color.apple` scale backs it, kept distinct from the emerald `green`
+  feedback/success scale so an accent and a success state never read as the same hue.
+  - `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.apple.*`.
+  - `semantic.color.content.onAccent` flips to a dark neutral (`neutral.900`) in both modes, since a bright accent fill needs dark text to clear AA — `content.onAccent / surface.accent` is 7.2:1 light / 9.3:1 dark.
+  - Per-tenant accents are unchanged: `accent-lilac` and `concrete-creations` set their own accent (and their own white `onAccent`); `brutalist-demo` inherits the new green base.
+
+  Visual-only; no API changes. The accent remains a single per-tenant knob — consumers who set their own accent overlay are unaffected.
+
+- c88ab39: docs(card): reconcile DESIGN.md with the shipped borderless-default Card.
+
+  The Card Anatomy / elevation tables said a resting card carries a 1px border, contradicting the 12d-3 outline rule (and DESIGN.md's own "don't default to outlined cards" guidance) that made the default `Card` variant borderless, with a resting border opt-in via `bordered` / a feedback `tone` / `accent`. Updated the elevation-role table, the component table, and the (mandatory) Card Anatomy Border row to document the borderless default + opt-in border, and corrected the stale card.tsx module docstring that claimed depth comes from a resting border. No component behavior change.
+
+- 0a6b830: fix(components): five Tier-1 component bugs from the audit.
+  - **Select** no longer crashes the page when `options` is empty (async list mid-load) or when `value` matches no option; the trigger label degrades to the field name.
+  - **Combobox** can now be closed by clicking its trigger again (the trigger was a `Popover.Anchor`, so Radix dismissed on pointerdown and the onClick reopened).
+  - **Button `asChild`** now enforces the disabled/loading contract on a slotted element (e.g. an `<a>`): non-interactive (`pointer-events-none`, `tabIndex=-1`) and dimmed, since native `disabled:` utilities can't apply to it.
+  - **AssetImg** and **Avatar** recover when `src` changes to a working image after a prior load error, instead of staying stuck on the fallback.
+
+- b43d6bc: The package now ships `dist/css-contract.json` (hds#449): for each stylesheet it exports, every CSS custom property with its value per context (`:root`, dark, compact, each `[data-brand]`, each `@media`), the class names, the `@font-face` entries and the `@layer` names, plus `publicClasses` (the classes you may write yourself: `hds-focus` and the `static.css` set, also listed in `public/hds-manifest.json`). The upgrade ledger reads it, so from the next release a removed CSS variable or `hds-*` class needs a breaking upgrade step, and a changed token value a look step that `npx @hirobius/design-system upgrade` reports where your code uses it. Nothing changes in the stylesheets themselves.
+- c88ab39: fix(disabled): unify the disabled state onto per-component tokens, off the global opacity multiplier.
+
+  DESIGN.md forbids a global disabled-state rule (opacity multiplier); disabled presentation must be governed per-component through its dedicated disabled tokens. Button, Combobox, Input, Textarea, Tabs and Tag were dimming with `disabled:opacity-50`/`opacity-70` — now they use `content.disabled` text (and a neutral `bg-muted` surface where a fill is needed), matching Checkbox/Radio/Toggle/SegmentedControl.
+  - **Button** — disabled is now `bg-muted` + `content-disabled` text for every variant AND tone (a disabled danger/success/… button now reads as disabled instead of fully coloured). Note: the pre-existing `component-button-primary-bgDisabled`/`textDisabled` tokens resolve to `accentSubtle` + `content-onAccent`, which render near-white-on-near-white under the neutral accent, so the component uses the neutral `bg-muted` pair instead (token fix tracked separately).
+  - **Input / Textarea** — drop the redundant `disabled:opacity-70`; keep `bg-muted`, switch disabled text to `content-disabled`.
+  - **Combobox / Tabs / Tag** — `disabled:opacity-50` → `content-disabled` text.
+
+  Visual-only; no API changes.
+
+- 2d2a874: Plain-language `@usage` lines for Button, Grid, Surface, Divider, Icon, Stack and every pattern. Docs pages now open with that line instead of the code note.
+- 8016b7a: AGENTS.md and llms.txt carry a Voice section generated from the Voice page (`content/docs/voice.mdx`, published at `/docs/voice`): how HDS docs and agents writing for HDS should speak, and the words not to use.
+- c88ab39: fix(polish): Table cell alignment + caption spacing, and reduced-motion guards (docs-site rubric findings).
+  - **Table**: data cells now `items-center` (was `items-start`), so a badge/status slot lines up on a shared vertical center with its text siblings instead of floating above them; the caption/description block gains a token gap so it no longer touches the table's header band.
+  - **Reduced motion**: the Button and Input loading spinners (`animate-spin`) and the Progress bar's width transition now carry a `motion-reduce:` guard, matching Spinner/Progress's existing policy, so they stop animating under `prefers-reduced-motion`.
+
 ## 0.22.0
 
 ### Upgrade

package/CONSUMING.md

@@ -29,7 +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)
+import '@hirobius/design-system/fonts.css'; // optional — the HDS brand fonts (Plus Jakarta Sans, IBM Plex Mono)
 
 export function Example() {
   return (
@@ -45,7 +45,7 @@ Available subpaths:
 | Import                               | What                                                                                                                                                                                                                                        |
 | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@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/fonts.css`  | Optional brand fonts (Plus Jakarta Sans, IBM Plex 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                                                                                                                                                                                                                   |
@@ -103,7 +103,7 @@ them without network access. Under `node_modules/@hirobius/design-system/`:
 - `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>
+The same files are served at <https://hirobius-hds-components.vercel.app/llms.txt>
 (and `/llms-full.txt`, `/llms/components.txt`, `/DESIGN.md`, `/component-api.json`).
 
 ## 3. Receiving updates

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 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.
+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.
 
 ## 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).
+- **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).
 - **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`.
@@ -28,9 +28,9 @@ 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 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.
+- **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.
+- **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.
 
@@ -92,14 +92,14 @@ Depth is communicated through 4 elevation roles bundled by `semantic.elevation.*
 
 ### 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                |
+| Surface                                | Role token                    | Background        | Shadow            | Border                                                   |
+| -------------------------------------- | ----------------------------- | ----------------- | ----------------- | -------------------------------------------------------- |
+| Card / panel resting                   | `semantic.elevation.flat`     | `surface.page`    | none              | none by default; opt-in 1px (`bordered`/`tone`/`accent`) |
+| 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.
+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. The default `Card` variant is **borderless** (12d-3 outline rule: repeated outlined cards crowd a layout, so the edge is not the default) — a resting 1px border is **opt-in** via `bordered`, a feedback `tone`, or the `accent` variant (`border.default` / feedback color / `border.accent` respectively). Rely on whitespace, dividers, and rails for grouping; reach for `bordered` only for a genuinely discrete standalone object.
 
 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.
 
@@ -142,9 +142,9 @@ Default most interactive feedback to `productive` (150ms, decelerate). Reserve `
 | --- | --- | --- | --- |
 | **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. |
+| **Cards** (`Card`) | `12px` (`rounded-lg`, role radius + 4px) | default · hover (optional parallax) · pressed (when interactive) | Cards default to `elevation.flat` (borderless by default; an opt-in 1px border via `bordered`/`tone`/`accent`, 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. |
+| **Alerts** (`Alert`) | `8px` (via `hds.borderRadius.4`) | info · success · warning · error | Inline banner pattern with icon + message + optional action. Tone is carried by a tinted feedback fill (`bg-feedback-bg-*`, matching Badge), NOT a left-border stripe. Callout shares this fill language and differs only by role (no icon, no status role, optional italic). |
 | **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`. |
@@ -156,16 +156,16 @@ See `public/hds-manifest.json` and `src/app/data/component-api.json` for the ful
 
 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.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                        |
+| Property                 | Required value                                                                                                                                                                            | Forbidden                                                                                   |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Background               | `var(--semantic-color-surface-raised)`                                                                                                                                                    | Any gradient, tinted fill, or custom color                                                  |
+| Border                   | Default variant: **borderless**. Opt-in (`bordered`/`tone`/`accent`): 1px solid the matching token (`border.default` / feedback color / `border.accent`). Never border + shadow together. | `box-shadow` as an elevation substitute; a border on the default variant (use `bordered`)   |
+| 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.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                        |
 
 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.
 
@@ -209,7 +209,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 neutral — 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 (#208) and defaults to a bright apple green — 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.
@@ -228,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` (389 tokens) and `public/hds-manifest.json` by `scripts/build-design-md.mjs`.
+> Generated from `hirobius.tokens.json` (400 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

@@ -1,9 +1,9 @@
 # License notice
 
-`@hirobius/design-system` is not under a single license.
+`@hirobius/design-system` is under two licenses: MIT for the code, and the SIL Open Font License 1.1 for the bundled fonts.
 
 - **HDS code** (components, compiled JavaScript, types, CSS, and token files): MIT. See [LICENSE](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.
+- **Plus Jakarta Sans** (weights 400, 500 and 700, by Tokotype, [source](https://github.com/tokotype/PlusJakartaSans), Latin subset): SIL Open Font License 1.1.
+- **IBM Plex Mono** (weight 400, by IBM, [source](https://github.com/IBM/plex)): 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.
+Both fonts ship as woff2 files in `dist/fonts/`, declared by the opt-in `dist/fonts.css`; each font's license text ships beside it as `dist/fonts/<family>-LICENSE.txt`. The MIT license does not cover the fonts. `dist/tokens.css`, `dist/styles.css` and `dist/variables.css` embed no fonts.

package/README.md

@@ -1,8 +1,11 @@
 # Hirobius Design System
 
-[![CI](https://github.com/hirobius/hds/actions/workflows/ci.yml/badge.svg)](https://github.com/hirobius/hds/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@hirobius/design-system)](https://www.npmjs.com/package/@hirobius/design-system) [![Storybook](https://img.shields.io/badge/Storybook-live-ff4785)](https://hirobius-design-system.vercel.app)
+[![CI](https://github.com/hirobius/hds/actions/workflows/ci.yml/badge.svg)](https://github.com/hirobius/hds/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@hirobius/design-system)](https://www.npmjs.com/package/@hirobius/design-system) [![Docs](https://img.shields.io/badge/Docs-live-000000)](https://hirobius-hds-components.vercel.app)
 
-React + TypeScript component library on a governed design-token pipeline. Live Storybook: **<https://hirobius-design-system.vercel.app>**
+**A governed, token-first React design system.** Components plus the system
+around them: a DTCG token pipeline (CSS variables + TypeScript constants),
+quality gates in git hooks and CI, one-way Figma sync, and WCAG-checked contrast
+and focus. Live docs: **<https://hirobius-hds-components.vercel.app>**
 
 ```bash
 pnpm add @hirobius/design-system
@@ -10,18 +13,23 @@ pnpm add @hirobius/design-system
 
 Upgrading: [UPGRADING.md](UPGRADING.md) lists what each release asks of you. From 0.22.0, `npx @hirobius/design-system@latest upgrade` does it for you.
 
-[![Buttons under the Brand and Theme dials: base and accent-lilac, light and dark](docs/images/storybook-brand-theme-dials.png)](https://hirobius-design-system.vercel.app)
+[![Buttons under the Brand and Theme dials: base and accent-lilac, light and dark](docs/images/storybook-brand-theme-dials.png)](https://hirobius-hds-components.vercel.app)
 
 <!-- auto:start:front-door-counts -->
 
 - **53** public component modules, exported from `src/index.ts`
-- **389** DTCG tokens in `hirobius.tokens.json`, compiled to CSS variables and TypeScript constants
+- **400** 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 -->
 
-- Theming through four root attributes and CSS variables (theme, density, brand, font) that need no JavaScript
-- Deterministic gates in git hooks and CI: typecheck, zero-warning ESLint, token validity and contrast, Vitest unit and contract tests, bundle budgets, a consumer smoke build, and a Storybook build
+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 Storybook build — run in git hooks and 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.
 
@@ -120,12 +128,12 @@ HDS theming is driven by root attributes + CSS variables, so it works with **zer
 JavaScript** — set them on any element (React, Astro, plain HTML) and every HDS
 descendant re-skins:
 
-| Dial    | Attribute / var                                | Values          | Default              |
-| ------- | ---------------------------------------------- | --------------- | -------------------- |
-| theme   | `data-theme`                                   | `dark`          | light (unset)        |
-| density | `data-density`                                 | `compact`       | comfortable (unset)  |
-| brand   | `data-brand` (+ `data-tenant` alias)           | overlay slug    | base (unset)         |
-| font    | `--hds-font-family` / `--hds-font-family-mono` | any font-family | Satoshi / Geist Mono |
+| Dial    | Attribute / var                                | Values          | Default                           |
+| ------- | ---------------------------------------------- | --------------- | --------------------------------- |
+| theme   | `data-theme`                                   | `dark`          | light (unset)                     |
+| density | `data-density`                                 | `compact`       | comfortable (unset)               |
+| brand   | `data-brand` (+ `data-tenant` alias)           | overlay slug    | base (unset)                      |
+| font    | `--hds-font-family` / `--hds-font-family-mono` | any font-family | Plus Jakarta Sans / IBM Plex Mono |
 
 ```html
 <!-- zero-JS: static markup (e.g. an Astro layout) -->
@@ -212,12 +220,13 @@ What CI and the hooks check today, and nothing more:
 - **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 `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).
+- **Docs site:** `scripts/check-docs-axe.mjs` (`pnpm check:docs-axe`, after `pnpm docs:publish`) scans the live demo of every `/docs/components/*` and `/docs/patterns/*` page of the built docs site in light and dark with the same axe rules, scoped to the demo frame so the Fumadocs chrome does not count. CI runs it and fails on serious or critical violations outside `scripts/docs-axe-allowlist.json`, which is empty.
 
 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
 
-The governing direction is "Editorial Enterprise" — enterprise rigor with editorial pacing. It favors sharp hierarchy, open whitespace, monochrome neutrals, and a single electric-blue accent. In practice:
+The governing direction is "Editorial Enterprise" — enterprise rigor with editorial pacing. It favors sharp hierarchy, open whitespace, monochrome neutrals, and a single tenant-set accent. In practice:
 
 - documentation reads like a designed publication, not a component dump
 - cards are used sparingly; whitespace, rails, dividers, and bands carry structure first
@@ -276,4 +285,4 @@ public/
 
 ## License
 
-The HDS code is MIT ([LICENSE](LICENSE)). The package CSS also embeds the Satoshi and Geist Mono fonts, which keep their own licenses and are not covered by MIT. See [NOTICE.md](NOTICE.md).
+The HDS code is MIT ([LICENSE](LICENSE)). The package CSS also embeds the Plus Jakarta Sans and IBM Plex Mono fonts, which keep their own licenses and are not covered by MIT. See [NOTICE.md](NOTICE.md).

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.22.0. 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.23.1. For newer releases, run `npx @hirobius/design-system@latest upgrade`: it always fetches the newest steps.
 
 ## How to upgrade
 
@@ -10,6 +10,40 @@ 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.23.1
+
+Released 2026-10-11 (patch). 6 that look different.
+
+### Looks different
+
+- The scoped HDS font variable now names Plus Jakarta Sans first instead of Satoshi.
+- Display and title text now renders in Plus Jakarta Sans instead of Satoshi.
+- Body, UI and caption text now renders in Plus Jakarta Sans instead of Satoshi.
+- fonts.css no longer declares Satoshi 400; it declares Plus Jakarta Sans 400 instead, so drop any font-family: Satoshi of your own.
+- fonts.css no longer declares Satoshi 500; it declares Plus Jakarta Sans 500 instead, so drop any font-family: Satoshi of your own.
+- fonts.css no longer declares Satoshi 700; it declares Plus Jakarta Sans 700 instead, so drop any font-family: Satoshi of your own.
+
+## 0.23.0
+
+Released 2026-10-10 (minor). 14 that look different.
+
+### Looks different
+
+- Accent-intent text and icons (such as links) now render in a dark apple green instead of a dark neutral.
+- Hovered accent text now shifts to a darker apple green instead of a darker neutral.
+- The accent fill on hover is now a deeper apple green instead of a dark neutral.
+- The accent fill while pressed is now a darker apple green instead of a near-black neutral.
+- Interactive accent fills at rest (primary buttons, selected controls) now render in a bright apple green instead of a dark neutral, paired with dark on-accent text.
+- The low-emphasis accent tint (hover and selection backgrounds) is now a faint apple green instead of a neutral tint.
+- Accent borders now render in apple green instead of a dark neutral.
+- Accent-intent text and icons on page and card surfaces now render in a dark apple green instead of a neutral.
+- Text and icons on accent fills are now a dark neutral instead of white, because the accent fill is a bright apple green that needs dark text for contrast.
+- Accent background surfaces now render in a bright apple green instead of a dark neutral.
+- Faint accent background surfaces are now a pale apple green instead of a neutral tint.
+- Callout now renders as a tinted feedback fill (rounded, no left stripe) matching Alert, with the accent tone using a neutral muted fill.
+- Code text now draws in IBM Plex Mono instead of Geist Mono, so if you preload or self-host geist-mono-400.woff2, point it at ibm-plex-mono-400.woff2 from fonts.css instead.
+- Table data cells vertically center their content (badge/status slots no longer float above text) and the caption gains spacing above the table; loading spinners and the progress bar stop animating under prefers-reduced-motion.
+
 ## 0.22.0
 
 Released 2026-10-08 (minor). 3 changes to make by hand (1 breaking), 1 that looks different and 2 deprecations.