@hirobius/design-system 0.19.1 → 0.21.0

package/dist/types/src/patterns.d.ts

@@ -1,42 +1,37 @@
 /**
  * @hirobius/design-system/patterns
  *
- * The 22 `pattern`-tier components (hds#254 disposition table, ratified
- * 2026-09-26): composed, higher-level surfaces (nav shells, feeds, rails,
- * pickers) as opposed to the `core` primitives the main barrel is trending
- * toward. Split into their own subpath so a consumer that only needs
+ * The `pattern`-tier modules (hds#254 disposition table, ratified
+ * 2026-09-26): composed, higher-level surfaces (page shells, forms, code
+ * blocks, page sections) as opposed to the `core` primitives the main barrel
+ * is trending toward. Split into their own subpath so a consumer that only needs
  * primitives doesn't pull in this tier's weight.
  *
- * Every one of these is STILL re-exported from the package root today —
- * hds#254 keeps the root re-export for one minor with a `@deprecated` /
- * `@removeIn` notice on each component (see the JSDoc in each module under
- * `src/app/components/`). Prefer importing from here; the root re-export is
- * scheduled for removal at the next major once ops has a codemod (hds#124).
+ * This is the only entry that exports them. Until 0.20.0 the package root
+ * also re-exported 21 of these modules behind `@deprecated` aliases (hds#254);
+ * hds#389 R1 removed those root re-exports, and
+ * `npx -p @hirobius/design-system@^0.20.0 hds-patterns-subpath`
+ * (codemods/patterns-subpath.mjs) moves consumer imports here.
+ *
+ * The same release removed 16 of these modules outright (hds#394 wave 4a, no
+ * survivor): ActivityFeed, AppShell, Calendar, Carousel, CommandPalette,
+ * DocLinkCard, FileInput, Lightbox, NavItem, OverflowList, SideNav,
+ * StackedCardRail, Stepper, Toolbar, TopNav and TreeList. The codemod reports
+ * an import of any of them for a manual edit (codemods/removed-0.20.json).
+ *
+ * StatusTile joined this entry in the same release (hds#389 D5, hds#395): the
+ * root stopped exporting it, and hds-patterns-subpath moves a root import of
+ * StatusTile, StatusTileProps or StatusTileTone here.
  */
-export * from './app/components/calendar.js';
-export * from './app/components/file-input.js';
 export * from './app/components/form.js';
-export * from './app/components/app-shell.js';
-export * from './app/components/overflow-list.js';
 export * from './app/components/page.js';
-export * from './app/components/activity-feed.js';
 export * from './app/components/asset-img.js';
-export * from './app/components/carousel.js';
 export * from './app/components/code-block.js';
-export * from './app/components/stacked-card-rail.js';
-export * from './app/components/doc-link-card.js';
-export * from './app/components/nav-item.js';
-export * from './app/components/side-nav.js';
-export * from './app/components/stepper.js';
-export * from './app/components/top-nav.js';
-export * from './app/components/tree-list.js';
 export * from './app/components/error-pattern.js';
-export * from './app/components/toolbar.js';
-export * from './app/components/command-palette.js';
-export * from './app/components/image-lightbox.js';
 export * from './app/components/reveal.js';
 export * from './app/components/page-header.js';
 export * from './app/components/metric-tiles.js';
 export * from './app/components/form-actions.js';
 export * from './app/components/destructive-section.js';
 export * from './app/components/data-table-section.js';
+export * from './app/components/status-tile.js';

package/dist/variables.css

@@ -118,6 +118,7 @@
   --primitive-typography-size-4xl: 36px;
   --primitive-typography-size-5xl: 48px;
   --primitive-typography-size-6xl: 60px;
+  --primitive-typography-size-code: 13px;
   --primitive-typography-weight-regular: 400;
   --primitive-typography-weight-medium: 500;
   --primitive-typography-weight-bold: 700;
@@ -127,6 +128,8 @@
   --primitive-typography-lineHeight-snug: 1.375;
   --primitive-typography-lineHeight-normal: 1.5;
   --primitive-typography-lineHeight-relaxed: 1.625;
+  --primitive-typography-lineHeight-display: 1.05;
+  --primitive-typography-lineHeight-body: 1.6;
   --primitive-typography-letterSpacing-tight: -0.01em;
   --primitive-typography-letterSpacing-normal: 0em;
   --primitive-typography-letterSpacing-caps: 0.06em;
@@ -156,6 +159,7 @@
   --primitive-size-64: 64px;
   --primitive-size-80: 80px;
   --primitive-size-96: 96px;
+  --primitive-size-120: 120px;
   --primitive-size-interactive-min: 44px;
   --primitive-size-interactive-minCompact: 24px;
   --primitive-size-width-96: 96px;
@@ -227,6 +231,7 @@
   --semantic-color-feedback-bg-warning: var(--primitive-color-amber-50);
   --semantic-color-feedback-bg-info: var(--primitive-color-blue-50);
   --semantic-color-feedback-bg-inProgress: var(--primitive-color-violet-50);
+  --semantic-color-state-pressed-overlay: var(--primitive-color-neutral-black);
   --semantic-space-scale-xs: var(--primitive-space-2);
   --semantic-space-scale-sm: var(--primitive-space-4);
   --semantic-space-scale-md: var(--primitive-space-6);
@@ -265,62 +270,67 @@
   --semantic-layout-grid-columns-desktop: var(--primitive-grid-columns-3);
   /* semantic.typography.display */
   --semantic-typography-display-font-family: var(--primitive-typography-family-display);
-  --semantic-typography-display-font-size: var(--primitive-typography-size-6xl);
+  --semantic-typography-display-font-size: var(--primitive-typography-size-5xl);
   --semantic-typography-display-font-weight: var(--primitive-typography-weight-bold);
   --semantic-typography-display-letter-spacing: var(--primitive-typography-letterSpacing-tight);
-  --semantic-typography-display-line-height: var(--primitive-typography-lineHeight-none);
-  /* semantic.typography.h1 */
-  --semantic-typography-h1-font-family: var(--primitive-typography-family-display);
-  --semantic-typography-h1-font-size: var(--primitive-typography-size-5xl);
-  --semantic-typography-h1-font-weight: var(--primitive-typography-weight-bold);
-  --semantic-typography-h1-letter-spacing: var(--primitive-typography-letterSpacing-tight);
-  --semantic-typography-h1-line-height: var(--primitive-typography-lineHeight-tight);
-  /* semantic.typography.h2 */
-  --semantic-typography-h2-font-family: var(--primitive-typography-family-display);
-  --semantic-typography-h2-font-size: var(--primitive-typography-size-3xl);
-  --semantic-typography-h2-font-weight: var(--primitive-typography-weight-bold);
-  --semantic-typography-h2-letter-spacing: var(--primitive-typography-letterSpacing-tight);
-  --semantic-typography-h2-line-height: 40px;
-  /* semantic.typography.h3 */
-  --semantic-typography-h3-font-family: var(--primitive-typography-family-display);
-  --semantic-typography-h3-font-size: var(--primitive-typography-size-xl);
-  --semantic-typography-h3-font-weight: var(--primitive-typography-weight-bold);
-  --semantic-typography-h3-letter-spacing: var(--primitive-typography-letterSpacing-normal);
-  --semantic-typography-h3-line-height: 28px;
+  --semantic-typography-display-line-height: var(--primitive-typography-lineHeight-display);
+  /* semantic.typography.title */
+  --semantic-typography-title-font-family: var(--primitive-typography-family-display);
+  --semantic-typography-title-font-size: var(--primitive-typography-size-2xl);
+  --semantic-typography-title-font-weight: var(--primitive-typography-weight-bold);
+  --semantic-typography-title-letter-spacing: var(--primitive-typography-letterSpacing-tight);
+  --semantic-typography-title-line-height: var(--primitive-typography-lineHeight-tight);
   /* semantic.typography.body */
   --semantic-typography-body-font-family: var(--primitive-typography-family-primary);
   --semantic-typography-body-font-size: var(--primitive-typography-size-base);
-  --semantic-typography-body-font-weight: var(--primitive-typography-weight-medium);
+  --semantic-typography-body-font-weight: var(--primitive-typography-weight-regular);
   --semantic-typography-body-letter-spacing: var(--primitive-typography-letterSpacing-normal);
-  --semantic-typography-body-line-height: 24px;
+  --semantic-typography-body-line-height: var(--primitive-typography-lineHeight-body);
   --semantic-typography-body-max-width: 60ch;
   /* semantic.typography.ui */
   --semantic-typography-ui-font-family: var(--primitive-typography-family-primary);
   --semantic-typography-ui-font-size: var(--primitive-typography-size-sm);
   --semantic-typography-ui-font-weight: var(--primitive-typography-weight-medium);
   --semantic-typography-ui-letter-spacing: var(--primitive-typography-letterSpacing-normal);
-  --semantic-typography-ui-line-height: 20px;
+  --semantic-typography-ui-line-height: var(--primitive-typography-lineHeight-normal);
   --semantic-typography-ui-max-width: 60ch;
   /* semantic.typography.caption */
   --semantic-typography-caption-font-family: var(--primitive-typography-family-primary);
   --semantic-typography-caption-font-size: var(--primitive-typography-size-xs);
   --semantic-typography-caption-font-weight: var(--primitive-typography-weight-medium);
   --semantic-typography-caption-letter-spacing: var(--primitive-typography-letterSpacing-normal);
-  --semantic-typography-caption-line-height: 16px;
-  /* semantic.typography.eyebrow */
-  --semantic-typography-eyebrow-font-family: var(--primitive-typography-family-primary);
-  --semantic-typography-eyebrow-font-size: var(--primitive-typography-size-xs);
-  --semantic-typography-eyebrow-font-weight: var(--primitive-typography-weight-medium);
-  --semantic-typography-eyebrow-letter-spacing: var(--primitive-typography-letterSpacing-caps);
-  --semantic-typography-eyebrow-line-height: 16px;
-  --semantic-typography-eyebrow-text-transform: uppercase;
+  --semantic-typography-caption-line-height: var(--primitive-typography-lineHeight-normal);
   /* semantic.typography.mono */
   --semantic-typography-mono-font-family: var(--primitive-typography-family-mono);
-  --semantic-typography-mono-font-size: var(--primitive-typography-size-sm);
+  --semantic-typography-mono-font-size: var(--primitive-typography-size-code);
   --semantic-typography-mono-font-weight: var(--primitive-typography-weight-regular);
   --semantic-typography-mono-letter-spacing: var(--primitive-typography-letterSpacing-normal);
-  --semantic-typography-mono-line-height: 20px;
+  --semantic-typography-mono-line-height: var(--primitive-typography-lineHeight-normal);
   --semantic-typography-mono-max-width: 60ch;
+  /* semantic.typography.h1 */
+  --semantic-typography-h1-font-family: var(--primitive-typography-family-display);
+  --semantic-typography-h1-font-size: var(--primitive-typography-size-2xl);
+  --semantic-typography-h1-font-weight: var(--primitive-typography-weight-bold);
+  --semantic-typography-h1-letter-spacing: var(--primitive-typography-letterSpacing-tight);
+  --semantic-typography-h1-line-height: var(--primitive-typography-lineHeight-tight);
+  /* semantic.typography.h2 */
+  --semantic-typography-h2-font-family: var(--primitive-typography-family-display);
+  --semantic-typography-h2-font-size: var(--primitive-typography-size-2xl);
+  --semantic-typography-h2-font-weight: var(--primitive-typography-weight-bold);
+  --semantic-typography-h2-letter-spacing: var(--primitive-typography-letterSpacing-tight);
+  --semantic-typography-h2-line-height: var(--primitive-typography-lineHeight-tight);
+  /* semantic.typography.h3 */
+  --semantic-typography-h3-font-family: var(--primitive-typography-family-display);
+  --semantic-typography-h3-font-size: var(--primitive-typography-size-2xl);
+  --semantic-typography-h3-font-weight: var(--primitive-typography-weight-bold);
+  --semantic-typography-h3-letter-spacing: var(--primitive-typography-letterSpacing-tight);
+  --semantic-typography-h3-line-height: var(--primitive-typography-lineHeight-tight);
+  /* semantic.typography.eyebrow */
+  --semantic-typography-eyebrow-font-family: var(--primitive-typography-family-primary);
+  --semantic-typography-eyebrow-font-size: var(--primitive-typography-size-xs);
+  --semantic-typography-eyebrow-font-weight: var(--primitive-typography-weight-medium);
+  --semantic-typography-eyebrow-letter-spacing: var(--primitive-typography-letterSpacing-normal);
+  --semantic-typography-eyebrow-line-height: var(--primitive-typography-lineHeight-normal);
   --semantic-typography-lineHeight-none: var(--primitive-typography-lineHeight-none);
   --semantic-docs-space-section: var(--primitive-space-12);
   --semantic-docs-space-paragraph: var(--primitive-space-6);
@@ -363,6 +373,7 @@
   --semantic-size-icon-md: var(--primitive-size-20);
   --semantic-size-icon-lg: var(--primitive-size-24);
   --semantic-size-avatar: var(--primitive-size-40);
+  --semantic-size-tile: var(--primitive-size-120);
   --semantic-size-row-compact: var(--primitive-size-40);
   --semantic-size-row-comfortable: var(--primitive-size-48);
   --semantic-zIndex-control: var(--primitive-zIndex-10);
@@ -456,6 +467,7 @@
   --role-card-foreground: var(--semantic-color-content-primary);
   --role-popover: var(--semantic-color-surface-overlay);
   --role-scrim: var(--semantic-color-surface-scrim);
+  --role-pressed-overlay: var(--semantic-color-state-pressed-overlay);
   --role-popover-foreground: var(--semantic-color-content-primary);
   --role-primary: var(--semantic-color-surface-accent);
   --role-primary-foreground: var(--semantic-color-content-onAccent);
@@ -515,6 +527,7 @@
   --semantic-color-feedback-bg-warning: var(--primitive-color-amber-950);
   --semantic-color-feedback-bg-info: var(--primitive-color-blue-900);
   --semantic-color-feedback-bg-inProgress: var(--primitive-color-violet-950);
+  --semantic-color-state-pressed-overlay: var(--primitive-color-neutral-white);
   --semantic-accent-rest: var(--primitive-color-neutral-100);
   --semantic-accent-hover: var(--primitive-color-neutral-200);
   --semantic-accent-pressed: var(--primitive-color-neutral-300);
@@ -567,6 +580,7 @@
   --role-card-foreground: var(--semantic-color-content-primary);
   --role-popover: var(--semantic-color-surface-overlay);
   --role-scrim: var(--semantic-color-surface-scrim);
+  --role-pressed-overlay: var(--semantic-color-state-pressed-overlay);
   --role-popover-foreground: var(--semantic-color-content-primary);
   --role-primary: var(--semantic-color-surface-accent);
   --role-primary-foreground: var(--semantic-color-content-onAccent);

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
@@ -101,7 +115,7 @@ Without `data-hds`, components still get their own token-driven styling, but the
 global type baseline and resets won't apply (text falls back to the host font).
 Put `data-hds` as high as makes sense — on `<html>`/`<body>` for an
 HDS-first app, or on a wrapper for a section. Overlays (Dialog, AlertDialog,
-Menu, ContextMenu, Popover, Select, HoverCard, Tooltip) inherit the nearest
+Menu, Popover, Select, Tooltip) inherit the nearest
 `data-hds` scope, so a `<div data-hds data-theme="dark">` themes them too; pass
 `container` on the Content part to portal elsewhere. If the scope element
 creates a containing block or stacking context (`transform`, `filter`, `z-index`,
@@ -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,21 +225,25 @@ export function Example() {
 
 ### Subpath exports
 
-| Import                                  | What you get                                                                                                                  |
-| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `@hirobius/design-system`               | All public components + the router seam (`HdsRouterProvider`, `useHdsRouter`)                                                 |
-| `@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) |
+| 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
 
@@ -287,8 +305,9 @@ import {
 
 ## 8.5 Optional — typed, schema-validated forms (React Hook Form + Zod)
 
-The main barrel is validation-agnostic: `FormField` takes a plain `error`
-string, so you bring your own validation. If you want a batteries-included
+The plain `FormField` (from `@hirobius/design-system/patterns`) is
+validation-agnostic: it takes a plain `error` string, so you bring your own
+validation. If you want a batteries-included
 layer, the `/form` subpath wires [React Hook Form](https://react-hook-form.com)
 to [Zod](https://zod.dev). It's opt-in — `react-hook-form`, `zod`, and
 `@hookform/resolvers` are **optional peer deps**, so they only land in your
@@ -338,7 +357,8 @@ function ApplyForm() {
   validation (no native browser popups racing your schema).
 - `HdsFormField` — a **render-prop**: spread the supplied props onto your
   control. It binds the control to RHF by `name` and shows the field's Zod
-  error through the same label/error/aria markup as the core `FormField`. (It's
+  error through the same label/error/aria markup as the `FormField` in
+  `@hirobius/design-system/patterns`. (It's
   a render-prop, not a cloned child, so RHF's callback ref attaches cleanly.)
 
 **SSR / Astro / Next.js RSC:** this layer is client-only (RHF uses hooks +
@@ -428,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/hirobius-design-system#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 [
   {
@@ -448,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
@@ -736,23 +764,27 @@ CSS, only the visual surface of the five primitives above.
 
 ## 15. Icons — the `/icons` subpath
 
-`IconButton` and `Icon` take an `icon` prop. Get one from the curated subpath;
-`lucide-react` does not need to be installed separately.
+`Icon` takes an `icon` prop. Get one from the curated subpath;
+`lucide-react` does not need to be installed separately. An icon-only button is
+`Button iconOnly` with a `label` (its accessible name) and the `Icon` in
+`iconLeft`.
 
 ```tsx
-import { IconButton } from '@hirobius/design-system';
+import { Button, Icon } from '@hirobius/design-system';
 import { Ellipsis } from '@hirobius/design-system/icons';
 
-<IconButton icon={Ellipsis} label="Row actions" />;
+<Button iconOnly label="Row actions" iconLeft={<Icon icon={Ellipsis} />} />;
 ```
 
 The full name list is `iconSet.names` in the manifest (and the Icons section of
 `llms.txt`). Canonical Lucide 0.487.0 names only: `MoreHorizontal` is
 `Ellipsis`, `MoreVertical` is `EllipsisVertical`, `AlertTriangle` is
 `TriangleAlert`, `Home` is `House`, `Filter` is `Funnel`. Icon-only actions (row
-menus, close, edit) use `IconButton`; do not hand-roll a button with a glyph. For
+menus, close, edit) use `Button iconOnly`; do not hand-roll a button with a glyph. For
 an icon outside the set, install `lucide-react@0.487.0` so the `LucideIcon` type
 stays identical.
 
-`Calendar` and `Menu` share names with HDS components; alias them:
-`import { Calendar as CalendarIcon, Menu as MenuIcon } from '@hirobius/design-system/icons'`.
+`Menu` shares its name with the HDS `Menu` component; alias it:
+`import { Menu as MenuIcon } from '@hirobius/design-system/icons'`. (`Calendar`
+collided too until the HDS `Calendar` was removed in 0.20.0, hds#394; it imports
+under its own name now.)