@hirobius/design-system 0.20.0 → 0.21.0

package/docs/CONSUMING.md

@@ -15,7 +15,7 @@ is the canonical consumption guide — point other teams here.
 >
 > 1. **`react-router` is now optional** — components route through an adapter and
 >    fall back to plain anchors when no router is provided (§5).
-> 2. **Fonts are bundled** — `tokens.css` embeds the typefaces; no font files to copy (§3).
+> 2. **Fonts are opt-in** — `import '@hirobius/design-system/fonts.css'` for the brand typefaces; the woff2 ship in the package, nothing to copy (§3).
 > 3. **Base styles are scoped to `[data-hds]`** — add that attribute to your root
 >    or section so HDS doesn't fight a host app's resets/fonts (§4, §6).
 
@@ -43,7 +43,7 @@ HDS ships **three** stylesheets. Pick one by how much you want HDS to own:
 
 ```ts
 // RECOMMENDED for embedding in an existing app (e.g. MUI): tokens + component
-// styles + utilities + embedded fonts, with NO global reset. Styles every HDS
+// styles + utilities, with NO global reset. Styles every HDS
 // component and changes ZERO host-element styles.
 import '@hirobius/design-system/styles.css';
 
@@ -56,17 +56,31 @@ import '@hirobius/design-system/tokens.css';
 import '@hirobius/design-system/variables.css';
 ```
 
-| Stylesheet          | Tokens | Components + utilities | Embedded fonts |     Global reset      |
-| ------------------- | :----: | :--------------------: | :------------: | :-------------------: |
-| **`styles.css`**    |   ✅   |           ✅           |       ✅       |        ❌ none        |
-| **`tokens.css`**    |   ✅   |           ✅           |       ✅       | ⚠️ Tailwind preflight |
-| **`variables.css`** |   ✅   |           ❌           |       ❌       |        ❌ none        |
+| Stylesheet          | Tokens | Components + utilities |     Global reset      |
+| ------------------- | :----: | :--------------------: | :-------------------: |
+| **`styles.css`**    |   ✅   |           ✅           |        ❌ none        |
+| **`tokens.css`**    |   ✅   |           ✅           | ⚠️ Tailwind preflight |
+| **`variables.css`** |   ✅   |           ❌           |        ❌ none        |
 
 All three:
 
 - **Need no Tailwind config** in the consumer — utilities ship compiled.
-- **Need no font files** — the woff2 are inlined (the file is correspondingly
-  larger; woff2 is already compressed so gzip recovers most of it).
+- **Carry no font files.** Fonts are a separate, optional import (below).
+
+### Brand fonts (optional)
+
+```ts
+import '@hirobius/design-system/fonts.css'; // Satoshi 400/500/700 + Geist Mono 400
+```
+
+`fonts.css` declares the four `@font-face` blocks with `font-display: swap`. Its
+URLs are relative (`./fonts/satoshi-400.woff2`), and the woff2 files ship in the
+package, so Vite, Next and webpack resolve and hash them; there is nothing to
+copy. Import it alongside one of the stylesheets above to keep the HDS fonts.
+Skip it to bring your own: `tokens.css` and `styles.css` keep the
+`--hds-font-family*` variables, so text falls back to the family stack
+(`"Satoshi", system-ui, …`) and uses your font if you declare that family
+yourself.
 
 HDS's own base styles (type baseline, resets) are scoped to the `[data-hds]`
 subtree (§4) in **all** bundles, so they never touch host elements. The only
@@ -155,7 +169,7 @@ If your app runs MUI `<CssBaseline>` + Emotion (or any opinionated global CSS),
   resets will fight if both target `body`.
 - **Styled path (recommended for MUI/host embedding):** import
   `@hirobius/design-system/styles.css` instead of `tokens.css`. It ships the full
-  component styling (tokens + utilities + fonts) but **no global reset** — HDS's
+  component styling (tokens + utilities) but **no global reset** — HDS's
   own base is scoped to `[data-hds]`, so it styles every HDS component and
   **cannot** restyle your host's `*`, `body`, headings, `button`, `a`, or form
   controls. This is the clean way to run HDS next to `<CssBaseline>`: no reset
@@ -211,23 +225,25 @@ export function Example() {
 
 ### Subpath exports
 
-| Import                                  | What you get                                                                                                                  |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `@hirobius/design-system`               | The core components + the router seam (`HdsRouterProvider`, `useHdsRouter`); the `pattern` tier is in `/patterns`             |
-| `@hirobius/design-system/styles.css`    | Components + utilities + tokens + fonts, NO global reset (host-safe; recommended for embedding)                               |
-| `@hirobius/design-system/tokens.css`    | The complete stylesheet — styles.css PLUS a global Tailwind-preflight reset                                                   |
-| `@hirobius/design-system/variables.css` | Design tokens as CSS custom properties ONLY — no reset/preflight (host-safe)                                                  |
-| `@hirobius/design-system/tokens`        | Design-token values as typed TS                                                                                               |
-| `@hirobius/design-system/cn`            | The `cn()` className-merge helper                                                                                             |
-| `@hirobius/design-system/manifest`      | Machine-readable component inventory (`hds-manifest.json`)                                                                    |
-| `@hirobius/design-system/contexts`      | React context providers, incl. the router seam (see below)                                                                    |
-| `@hirobius/design-system/form`          | Optional React Hook Form + Zod form adapter (see §8.5)                                                                        |
-| `@hirobius/design-system/mui`           | Optional Material UI theme preset — maps HDS tokens to an MUI palette (see §6)                                                |
-| `@hirobius/design-system/brand`         | Framework-free palette → HDS-semantic overlay bridge for static/SSR targets (see §12)                                         |
-| `@hirobius/design-system/scroll`        | Opt-in scroll-motion: `SmoothScroll` (Lenis) + `useScrollProgress` (Motion). Optional peer `lenis` (see §13)                  |
-| `@hirobius/design-system/static.css`    | CSS-only static-primitive layer — `.hds-badge`/`.hds-card`/`.hds-alert`/`.hds-divider`/`.hds-tag` classes, no React (see §14) |
-| `@hirobius/design-system/patterns`      | The `pattern`-tier components (`Page`, `PageHeader`, `Form`, `FormField`, `CodeBlock`); root copies removed in 0.20.0         |
-| `@hirobius/design-system/icons`         | Curated Lucide icon set for `Icon` and `Button iconOnly` (see §15)                                                            |
+| Import                                  | What you get                                                                                                                                                                                                                            |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@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 router seam (`HdsRouterProvider`, `useHdsRouter`); the `pattern` tier is in `/patterns` |
+| `@hirobius/design-system/styles.css`    | Components + utilities + tokens, NO global reset (host-safe; recommended for embedding)                                                                                                                                                 |
+| `@hirobius/design-system/fonts.css`     | Optional brand fonts: Satoshi 400/500/700 + Geist Mono 400 (`@font-face`, relative woff2 URLs)                                                                                                                                          |
+| `@hirobius/design-system/tokens.css`    | The complete stylesheet — styles.css PLUS a global Tailwind-preflight reset                                                                                                                                                             |
+| `@hirobius/design-system/variables.css` | Design tokens as CSS custom properties ONLY — no reset/preflight (host-safe)                                                                                                                                                            |
+| `@hirobius/design-system/tokens`        | Design-token values as typed TS                                                                                                                                                                                                         |
+| `@hirobius/design-system/cn`            | The `cn()` className-merge helper                                                                                                                                                                                                       |
+| `@hirobius/design-system/manifest`      | Machine-readable component inventory (`hds-manifest.json`)                                                                                                                                                                              |
+| `@hirobius/design-system/contexts`      | React context providers, incl. the router seam (see below)                                                                                                                                                                              |
+| `@hirobius/design-system/form`          | Optional React Hook Form + Zod form adapter (see §8.5)                                                                                                                                                                                  |
+| `@hirobius/design-system/mui`           | Optional Material UI theme preset — maps HDS tokens to an MUI palette (see §6)                                                                                                                                                          |
+| `@hirobius/design-system/brand`         | Framework-free palette → HDS-semantic overlay bridge for static/SSR targets (see §12)                                                                                                                                                   |
+| `@hirobius/design-system/scroll`        | Opt-in scroll-motion: `SmoothScroll` (Lenis) + `useScrollProgress` (Motion). Optional peer `lenis` (see §13)                                                                                                                            |
+| `@hirobius/design-system/static.css`    | CSS-only static-primitive layer — `.hds-badge`/`.hds-card`/`.hds-alert`/`.hds-divider`/`.hds-tag` classes, no React (see §14)                                                                                                           |
+| `@hirobius/design-system/patterns`      | The 12 pattern modules (`Page`, `PageHeader`, `Form`, `FormField`, `CodeBlock`, …); root copies removed in 0.20.0                                                                                                                       |
+| `@hirobius/design-system/icons`         | Curated Lucide icon set for `Icon` and `Button iconOnly` (see §15)                                                                                                                                                                      |
+| `@hirobius/design-system/eslint-plugin` | The consumer ESLint plugin; spread `configs.recommended` into `eslint.config.mjs` (see §11)                                                                                                                                             |
 
 ### Semantic feedback / status tokens
 
@@ -432,16 +448,15 @@ by `scripts/check-hardcoded-colors.mjs`, `scripts/check-hardcoded-spacing.mjs`,
 and `scripts/check-layout-discipline.mjs` — internal scripts that only run
 here. `@hirobius/eslint-plugin-hds` (`scripts/eslint-plugin-hds/`) ships the
 same discipline as an installable ESLint plugin for consumer apps, flagging
-raw hex/px values in `style`, `className`, and `Box` `sx` props before they
-reach code review.
+raw hex/px values in `style`, `className`, and `Box` `sx` props, and raw HTML
+form controls, before they reach code review.
 
-```bash
-pnpm add -D "@hirobius/eslint-plugin-hds@github:hirobius/hds#path:/scripts/eslint-plugin-hds"
-```
+It ships inside this package as the `@hirobius/design-system/eslint-plugin`
+subpath, so an app that has the design system installed needs only `eslint`:
 
 ```js
 // eslint.config.mjs
-import hds from '@hirobius/eslint-plugin-hds';
+import hds from '@hirobius/design-system/eslint-plugin';
 
 export default [
   {
@@ -452,12 +467,21 @@ export default [
 ];
 ```
 
-Four rules ship in `recommended`: `no-raw-hex` (error), `no-raw-px-spacing`
-(error), `sx-token-first` (error — raw hex/px inside `Box` `sx`, where token
-keys are mandatory), and `prefer-hds-layout-primitive` (warn — ad-hoc
-`display: flex`/`grid` where Stack/Grid likely fits). Full rule docs, examples,
-and the "why `scripts/eslint-plugin-hds/` and not a top-level workspace
-package" packaging note live in
+Without the package (for example in a repo that only lints), install the same
+plugin from git:
+
+```bash
+pnpm add -D "@hirobius/eslint-plugin-hds@github:hirobius/hds#path:/scripts/eslint-plugin-hds"
+```
+
+and import it as `@hirobius/eslint-plugin-hds`.
+
+Five rules ship in `recommended`: `no-raw-hex` (error), `no-raw-px-spacing`
+(error), `no-raw-controls` (error — raw `<button>`, `<input>`, `<select>`,
+`<textarea>` or `<form>` where an HDS component exists), `sx-token-first`
+(error — raw hex/px inside `Box` `sx`, where token keys are mandatory), and
+`prefer-hds-layout-primitive` (warn — ad-hoc `display: flex`/`grid` where
+Stack/Grid likely fits). Full rule docs and examples live in
 [`scripts/eslint-plugin-hds/README.md`](../scripts/eslint-plugin-hds/README.md).
 
 ### Agent skill

package/hirobius.tokens.json

@@ -486,7 +486,7 @@
             "Segoe UI",
             "sans-serif"
           ],
-          "$description": "Display face: Satoshi Bold (ITF), bound to display/h1/h2/h3 composites."
+          "$description": "Display face: Satoshi Bold (ITF), bound to the display and title composites."
         },
         "mono": {
           "$value": ["Geist Mono", "Courier New", "monospace"],
@@ -564,6 +564,13 @@
             "unit": "px"
           },
           "$description": "Swiss-canon display size (hds#283 ramp). Static desktop value; fluid in theme.css. Tailwind 4 default text-6xl."
+        },
+        "code": {
+          "$value": {
+            "value": 13,
+            "unit": "px"
+          },
+          "$description": "13px code size. The mono role (hds#485): one px below ui so code sits level with 14px prose."
         }
       },
       "weight": {
@@ -599,6 +606,14 @@
         "relaxed": {
           "$value": 1.625,
           "$description": "Swiss-canon relaxed rhythm (10t-5). Used by body/small/mono composites for long-form prose comfort."
+        },
+        "display": {
+          "$value": 1.05,
+          "$description": "Display role leading (hds#485)."
+        },
+        "body": {
+          "$value": 1.6,
+          "$description": "Body role leading (hds#485)."
         }
       },
       "letterSpacing": {
@@ -1677,84 +1692,40 @@
     },
     "typography": {
       "$type": "typography",
-      "$description": "8-style Swiss-canon type ramp: display, h1–h3, body, small, caption, mono.",
+      "$description": "5-role type ramp plus mono (hds#483): display, title, body, ui, caption, mono. h1, h2, h3 and eyebrow are deprecated aliases.",
       "display": {
-        "$value": {
-          "fontFamily": "{primitive.typography.family.display}",
-          "fontSize": "{primitive.typography.size.6xl}",
-          "fontWeight": "{primitive.typography.weight.bold}",
-          "letterSpacing": "{primitive.typography.letterSpacing.tight}",
-          "lineHeight": "{primitive.typography.lineHeight.none}"
-        },
-        "$description": "Display headline. 60px / Satoshi bold 700 / leading-none (hds#283: was 72px/5xl).",
-        "$extensions": {
-          "com.figma.variables": {
-            "fontSize": "clamp(40px, 8vw, 60px)",
-            "note": "Figma stores the 60px desktop-max static value. Browser CSS overrides with fluid scaling (40px min → 60px max). See src/styles/theme.css."
-          }
-        }
-      },
-      "h1": {
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
           "fontSize": "{primitive.typography.size.5xl}",
           "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.tight}",
-          "lineHeight": "{primitive.typography.lineHeight.tight}"
+          "lineHeight": "{primitive.typography.lineHeight.display}"
         },
-        "$description": "Primary section headings (h1). 48px / Satoshi bold 700 / leading-tight (hds#283: rung renamed 4xl→5xl, px unchanged).",
-        "$extensions": {
-          "com.figma.variables": {
-            "fontSize": "clamp(32px, 6vw, 48px)",
-            "note": "Figma stores the 48px desktop-max static value. Browser CSS overrides with fluid scaling (32px min → 48px max). See src/styles/theme.css."
-          }
-        }
+        "$description": "One per page, hero only. 48px / 1.05 / 700. Role 1 of 6."
       },
-      "h2": {
+      "title": {
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
-          "fontSize": "{primitive.typography.size.3xl}",
+          "fontSize": "{primitive.typography.size.2xl}",
           "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.tight}",
-          "lineHeight": "40px"
-        },
-        "$description": "Secondary section headings (h2). Satoshi bold 700, 30px, line-height 40px (hds#283: rung renamed, was 42px).",
-        "$extensions": {
-          "com.figma.variables": {
-            "fontSize": "clamp(24px, 3.5vw, 30px)",
-            "note": "Figma stores the 30px desktop-max static value. Browser CSS overrides with fluid scaling (24px min → 30px max). See src/styles/theme.css."
-          }
-        }
-      },
-      "h3": {
-        "$value": {
-          "fontFamily": "{primitive.typography.family.display}",
-          "fontSize": "{primitive.typography.size.xl}",
-          "fontWeight": "{primitive.typography.weight.bold}",
-          "letterSpacing": "{primitive.typography.letterSpacing.normal}",
-          "lineHeight": "28px"
+          "lineHeight": "{primitive.typography.lineHeight.tight}"
         },
-        "$description": "Component and card headers (h3). 20px / Satoshi bold 700 500 / leading-snug (hds#283: rung renamed lg→xl, px unchanged).",
-        "$extensions": {
-          "com.figma.variables": {
-            "fontSize": "clamp(18px, 2vw, 20px)",
-            "note": "Figma stores the 20px desktop-max static value. Browser CSS overrides with fluid scaling (18px min → 20px max). See src/styles/theme.css."
-          }
-        }
+        "$description": "Section and card headings. 24px / 1.25 / 700. Role 2 of 6."
       },
       "body": {
         "$value": {
           "fontFamily": "{primitive.typography.family.primary}",
           "fontSize": "{primitive.typography.size.base}",
-          "fontWeight": "{primitive.typography.weight.medium}",
+          "fontWeight": "{primitive.typography.weight.regular}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
-          "lineHeight": "24px",
+          "lineHeight": "{primitive.typography.lineHeight.body}",
           "maxWidth": {
             "value": 60,
             "unit": "ch"
           }
         },
-        "$description": "Body prose. Satoshi medium, 16px, line-height 24px, max 60ch measure (hds#283: was 17px/28px)."
+        "$description": "Prose. 16px / 1.6 / 400, 60ch measure. Role 3 of 6."
       },
       "ui": {
         "$value": {
@@ -1762,13 +1733,13 @@
           "fontSize": "{primitive.typography.size.sm}",
           "fontWeight": "{primitive.typography.weight.medium}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
-          "lineHeight": "20px",
+          "lineHeight": "{primitive.typography.lineHeight.normal}",
           "maxWidth": {
             "value": 60,
             "unit": "ch"
           }
         },
-        "$description": "UI text for nav, labels, captions. Satoshi medium, 14px, line-height 20px (hds#283: was 15px/24px)."
+        "$description": "Controls, nav, table text, values. 14px / 1.5 / 500. Role 4 of 6."
       },
       "caption": {
         "$value": {
@@ -1776,34 +1747,67 @@
           "fontSize": "{primitive.typography.size.xs}",
           "fontWeight": "{primitive.typography.weight.medium}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
-          "lineHeight": "16px"
+          "lineHeight": "{primitive.typography.lineHeight.normal}"
         },
-        "$description": "Caption / helper text. Satoshi medium, 12px, line-height 16px. Matches the Figma typography/caption text style; now sourced from primitive.xs (hds#283)."
-      },
-      "eyebrow": {
-        "$value": {
-          "fontFamily": "{primitive.typography.family.primary}",
-          "fontSize": "{primitive.typography.size.xs}",
-          "fontWeight": "{primitive.typography.weight.medium}",
-          "letterSpacing": "{primitive.typography.letterSpacing.caps}",
-          "lineHeight": "16px",
-          "textTransform": "uppercase"
-        },
-        "$description": "Eyebrow / kicker label. Satoshi medium, 12px, caps tracking, uppercase (hds#283: was 13px/20px)."
+        "$description": "Metadata, help text and labels, in sentence case. 12px / 1.5 / 500. Role 5 of 6."
       },
       "mono": {
         "$value": {
           "fontFamily": "{primitive.typography.family.mono}",
-          "fontSize": "{primitive.typography.size.sm}",
+          "fontSize": "{primitive.typography.size.code}",
           "fontWeight": "{primitive.typography.weight.regular}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
-          "lineHeight": "20px",
+          "lineHeight": "{primitive.typography.lineHeight.normal}",
           "maxWidth": {
             "value": 60,
             "unit": "ch"
           }
         },
-        "$description": "Monospace for code, token names, shortcuts. Geist Mono regular, 14px (hds#283: repointed xs→sm; xs alone would give 12px)."
+        "$description": "Code and ids. 13px / 1.5 / 400. The mono companion, role 6 of 6."
+      },
+      "h1": {
+        "$value": {
+          "fontFamily": "{primitive.typography.family.display}",
+          "fontSize": "{primitive.typography.size.2xl}",
+          "fontWeight": "{primitive.typography.weight.bold}",
+          "letterSpacing": "{primitive.typography.letterSpacing.tight}",
+          "lineHeight": "{primitive.typography.lineHeight.tight}"
+        },
+        "$description": "deprecated: use semantic.typography.title",
+        "$deprecated": "hds#483 — use semantic.typography.title"
+      },
+      "h2": {
+        "$value": {
+          "fontFamily": "{primitive.typography.family.display}",
+          "fontSize": "{primitive.typography.size.2xl}",
+          "fontWeight": "{primitive.typography.weight.bold}",
+          "letterSpacing": "{primitive.typography.letterSpacing.tight}",
+          "lineHeight": "{primitive.typography.lineHeight.tight}"
+        },
+        "$description": "deprecated: use semantic.typography.title",
+        "$deprecated": "hds#483 — use semantic.typography.title"
+      },
+      "h3": {
+        "$value": {
+          "fontFamily": "{primitive.typography.family.display}",
+          "fontSize": "{primitive.typography.size.2xl}",
+          "fontWeight": "{primitive.typography.weight.bold}",
+          "letterSpacing": "{primitive.typography.letterSpacing.tight}",
+          "lineHeight": "{primitive.typography.lineHeight.tight}"
+        },
+        "$description": "deprecated: use semantic.typography.title",
+        "$deprecated": "hds#483 — use semantic.typography.title"
+      },
+      "eyebrow": {
+        "$value": {
+          "fontFamily": "{primitive.typography.family.primary}",
+          "fontSize": "{primitive.typography.size.xs}",
+          "fontWeight": "{primitive.typography.weight.medium}",
+          "letterSpacing": "{primitive.typography.letterSpacing.normal}",
+          "lineHeight": "{primitive.typography.lineHeight.normal}"
+        },
+        "$description": "deprecated: use semantic.typography.caption",
+        "$deprecated": "hds#483 — use semantic.typography.caption"
       },
       "lineHeight": {
         "none": {