@hirobius/design-system 0.20.0 → 0.22.0

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

@@ -35,7 +35,6 @@ export * from './app/components/table.js';
 export * from './app/components/tag.js';
 export * from './app/components/text.js';
 export * from './app/components/kbd.js';
-export * from './app/components/status-dot.js';
 export * from './app/components/timestamp.js';
 export * from './app/components/blockquote.js';
 export * from './app/components/visually-hidden.js';
@@ -607,6 +606,13 @@ export declare const tokens: {
                     };
                     $description: string;
                 };
+                code: {
+                    $value: {
+                        value: number;
+                        unit: string;
+                    };
+                    $description: string;
+                };
             };
             weight: {
                 $type: string;
@@ -642,6 +648,14 @@ export declare const tokens: {
                     $value: number;
                     $description: string;
                 };
+                display: {
+                    $value: number;
+                    $description: string;
+                };
+                body: {
+                    $value: number;
+                    $description: string;
+                };
             };
             letterSpacing: {
                 $type: string;
@@ -712,14 +726,20 @@ export declare const tokens: {
                 $description: string;
             };
             elastic: {
-                $type: string;
-                $value: {
-                    type: string;
-                    stiffness: number;
-                    damping: number;
-                    mass: number;
-                };
+                $value: number[];
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $type: string;
+                        $value: {
+                            type: string;
+                            stiffness: number;
+                            damping: number;
+                            mass: number;
+                        };
+                        bezierSource: string;
+                    };
+                };
             };
         };
         shadow: {
@@ -1000,31 +1020,52 @@ export declare const tokens: {
     semantic: {
         motion: {
             $type: string;
+            $extensions: {
+                "com.hirobius.hds": {
+                    $type: string;
+                };
+            };
             productive: {
                 $value: {
                     duration: string;
-                    easing: string;
+                    delay: {
+                        value: number;
+                        unit: string;
+                    };
+                    timingFunction: string;
                 };
                 $description: string;
             };
             expressive: {
                 $value: {
                     duration: string;
-                    easing: string;
+                    delay: {
+                        value: number;
+                        unit: string;
+                    };
+                    timingFunction: string;
                 };
                 $description: string;
             };
             spatial: {
                 $value: {
                     duration: string;
-                    easing: string;
+                    delay: {
+                        value: number;
+                        unit: string;
+                    };
+                    timingFunction: string;
                 };
                 $description: string;
             };
             exit: {
                 $value: {
                     duration: string;
-                    easing: string;
+                    delay: {
+                        value: number;
+                        unit: string;
+                    };
+                    timingFunction: string;
                 };
                 $description: string;
             };
@@ -1729,14 +1770,8 @@ export declare const tokens: {
                     lineHeight: string;
                 };
                 $description: string;
-                $extensions: {
-                    "com.figma.variables": {
-                        fontSize: string;
-                        note: string;
-                    };
-                };
             };
-            h1: {
+            title: {
                 $value: {
                     fontFamily: string;
                     fontSize: string;
@@ -1745,30 +1780,36 @@ export declare const tokens: {
                     lineHeight: string;
                 };
                 $description: string;
-                $extensions: {
-                    "com.figma.variables": {
-                        fontSize: string;
-                        note: string;
-                    };
-                };
             };
-            h2: {
+            body: {
                 $value: {
                     fontFamily: string;
                     fontSize: string;
                     fontWeight: string;
                     letterSpacing: string;
                     lineHeight: string;
+                    maxWidth: {
+                        value: number;
+                        unit: string;
+                    };
                 };
                 $description: string;
-                $extensions: {
-                    "com.figma.variables": {
-                        fontSize: string;
-                        note: string;
+            };
+            ui: {
+                $value: {
+                    fontFamily: string;
+                    fontSize: string;
+                    fontWeight: string;
+                    letterSpacing: string;
+                    lineHeight: string;
+                    maxWidth: {
+                        value: number;
+                        unit: string;
                     };
                 };
+                $description: string;
             };
-            h3: {
+            caption: {
                 $value: {
                     fontFamily: string;
                     fontSize: string;
@@ -1777,14 +1818,8 @@ export declare const tokens: {
                     lineHeight: string;
                 };
                 $description: string;
-                $extensions: {
-                    "com.figma.variables": {
-                        fontSize: string;
-                        note: string;
-                    };
-                };
             };
-            body: {
+            mono: {
                 $value: {
                     fontFamily: string;
                     fontSize: string;
@@ -1798,21 +1833,18 @@ export declare const tokens: {
                 };
                 $description: string;
             };
-            ui: {
+            h1: {
                 $value: {
                     fontFamily: string;
                     fontSize: string;
                     fontWeight: string;
                     letterSpacing: string;
                     lineHeight: string;
-                    maxWidth: {
-                        value: number;
-                        unit: string;
-                    };
                 };
                 $description: string;
+                $deprecated: string;
             };
-            caption: {
+            h2: {
                 $value: {
                     fontFamily: string;
                     fontSize: string;
@@ -1821,31 +1853,29 @@ export declare const tokens: {
                     lineHeight: string;
                 };
                 $description: string;
+                $deprecated: string;
             };
-            eyebrow: {
+            h3: {
                 $value: {
                     fontFamily: string;
                     fontSize: string;
                     fontWeight: string;
                     letterSpacing: string;
                     lineHeight: string;
-                    textTransform: string;
                 };
                 $description: string;
+                $deprecated: string;
             };
-            mono: {
+            eyebrow: {
                 $value: {
                     fontFamily: string;
                     fontSize: string;
                     fontWeight: string;
                     letterSpacing: string;
                     lineHeight: string;
-                    maxWidth: {
-                        value: number;
-                        unit: string;
-                    };
                 };
                 $description: string;
+                $deprecated: string;
             };
             lineHeight: {
                 none: {
@@ -2012,38 +2042,58 @@ export declare const tokens: {
             };
         };
         elevation: {
-            $type: string;
-            flat: {
-                $value: {
-                    surface: string;
-                    shadow: null;
-                    border: string;
+            $extensions: {
+                "com.hirobius.hds": {
+                    $type: string;
                 };
+            };
+            flat: {
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $value: {
+                            surface: string;
+                            shadow: null;
+                            border: string;
+                        };
+                    };
+                };
             };
             raised: {
-                $value: {
-                    surface: string;
-                    shadow: string;
-                    border: null;
-                };
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $value: {
+                            surface: string;
+                            shadow: string;
+                            border: null;
+                        };
+                    };
+                };
             };
             floating: {
-                $value: {
-                    surface: string;
-                    shadow: string;
-                    border: null;
-                };
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $value: {
+                            surface: string;
+                            shadow: string;
+                            border: null;
+                        };
+                    };
+                };
             };
             overlay: {
-                $value: {
-                    surface: string;
-                    shadow: string;
-                    border: null;
-                };
                 $description: string;
+                $extensions: {
+                    "com.hirobius.hds": {
+                        $value: {
+                            surface: string;
+                            shadow: string;
+                            border: null;
+                        };
+                    };
+                };
             };
         };
         size: {

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;
@@ -267,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);

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