@hirobius/design-system 0.20.0 → 0.22.0

package/public/llms.txt

@@ -1,8 +1,67 @@
 # Hirobius Design System
 
-Generated: 2026-10-01T13:20:49.686Z
+Generated: 2026-10-07T16:09:09.631Z
 Primary sources: `public/hds-manifest.json`, `src/app/data/component-api.json`, `hirobius.tokens.json`
 
+## Agents Using The Package: Start Here
+
+- Read `AGENTS.md` (package root, `node_modules/@hirobius/design-system/AGENTS.md`) first: which component to use for each screen need, the imports, and the rules.
+- MCP server `hds` ships in the package: run `npx hds-mcp` (stdio). Tools: `list_core`, `search_components`, `get_component`, `search_tokens`; each answer is under 2 KB.
+- Lint before you finish: `import hds from '@hirobius/design-system/eslint-plugin'` and spread `hds.configs.recommended` into `eslint.config.mjs`.
+
+## Pick By Need
+
+One answer per need. Use the components after the arrow; what follows "Not:" is what agents reached for instead, which is the wrong answer for that need even where it has a purpose of its own. Generated from `mcp/guide.mjs`, the same list as `AGENTS.md`.
+
+- **Outermost wrapper of a screen** → `Page`, `Stack`. Not: `Container`, `Box`, a bare Stack as the root.
+  `<Page><Stack gap="spacious">…one child per section…</Stack></Page>`. `Container` is for a full-bleed surface that is not a page.
+- **Screen title with breadcrumb, status and actions** → `PageHeader`, `Breadcrumb`, `Badge`. Not: Text as the page title, a Stack row of Text and Badge.
+  Exactly one per screen: `<PageHeader breadcrumb={<Breadcrumb items={[{ label, href }, { label }]} />} title="…" status={<Badge tone="success">Active</Badge>} />`.
+- **Row of headline numbers (stats, KPIs, counts, totals)** → `MetricTiles`, `MetricTile`. Not: `Stat`, `StatusTile`, `CardMetric`, Card with Text.
+  `<MetricTiles><MetricTile label="Open projects" value="5" />…</MetricTiles>`; one MetricTile per number. `Stat` is for a number inside prose or a dense list, `Card.Metric` for one inside an existing `Card`, `StatusTile` for a state with notes (never a number).
+- **Table of records with row actions** → `DataTableSection`, `Badge`, `Button`. Not: Table on its own, Card around a Table.
+  `<DataTableSection title="Projects" columns={[{ key, label }]} rows={[{ key, cells: [...], actions: <Stack direction="row" gap="tight">…</Stack> }]} />`; leave the actions column out of `columns`.
+- **Switch between panels of related content** → `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`. Not: `SegmentedControl`, Button rows.
+  `<Tabs defaultValue="a"><TabsList><TabsTrigger value="a">A</TabsTrigger></TabsList><TabsContent value="a">…</TabsContent></Tabs>`.
+- **Status label in a header or table cell** → `Badge`. Not: `Tag`, `Text`.
+  `<Badge tone="success|info|warning|danger|neutral|inProgress">…</Badge>`; tone is the only styling input.
+- **Form with fields and a submit button** → `Form`, `Textarea`, `Input`, `FormActions`, `Button`. Not: a raw `<form>`, a Stack of Buttons as the footer.
+  `<Form onSubmit={…}><Textarea label="Notes" … /><FormActions primary={<Button type="submit">Save note</Button>} /></Form>`; every field takes its own `label`.
+- **Confirm a destructive or irreversible action (delete, archive, remove)** → `AlertDialog`, `Button`. Not: `Dialog`, `window.confirm`.
+  Trigger, title, description, Cancel and Action parts: `<AlertDialog><AlertDialog.Trigger asChild><Button …>Archive</Button></AlertDialog.Trigger><AlertDialog.Content><AlertDialog.Header><AlertDialog.Title>…</AlertDialog.Title><AlertDialog.Description>…</AlertDialog.Description></AlertDialog.Header><AlertDialog.Footer><AlertDialog.Cancel asChild><Button variant="secondary">Cancel</Button></AlertDialog.Cancel><AlertDialog.Action asChild><Button tone="danger" onClick={…}>Archive</Button></AlertDialog.Action></AlertDialog.Footer></AlertDialog.Content></AlertDialog>`. Focus moves in and returns to the trigger for you.
+- **Brief confirmation after an action (saved, archived, sent)** → `ToastProvider`, `useToast`. Not: `Badge`, `Alert`, `Text`.
+  Wrap the app root once in `<ToastProvider>`, then `toast({ title: "Note saved", tone: "success" })` from `useToast()`.
+- **Message that stays next to its content (error, warning, info)** → `Alert`. Not: Text in a coloured Surface.
+  `<Alert tone="warning">…</Alert>`.
+- **Button or row action** → `Button`. Not: a raw `<button>`, InlineLink for an action.
+  Row actions: `<Button variant="tertiary" size="sm" aria-label="View Brand refresh">View</Button>`; the destructive one adds `tone="danger"`.
+- **Space between sections or items** → `Stack`, `Grid`. Not: margins on children, raw px gaps such as px8.
+  Stack `gap`: `spacious` between page sections, `normal` inside a section, `tight` between buttons. `Grid` for two-dimensional layout.
+- **Padded background or a titled content object** → `Surface`, `Card`. Not: a Box with background and padding.
+  `Surface` for a plain padded background; `Card` only when the content has a title or can be pressed.
+- **Progress bar or ring** → `Progress`. Not: a hand-built bar.
+  `<Progress value={60} label="Upload" />`; inside an existing `Card`, `CardProgress`.
+- **Body copy** → `Text`. Not: Text as a section heading.
+  Section headings come from the pattern that owns the section (`PageHeader` `title`, `DataTableSection` `title`), not from extra Text.
+- **Empty state for a list or section** → `EmptyState`. Not: Text saying "No items".
+  `DataTableSection` shows its own through `emptyTitle`; use `EmptyState` elsewhere.
+- **The one irreversible action of a screen (delete the client, close the account)** → `DestructiveSection`. Not: a danger Button that acts without a confirm.
+  Last on the screen: `<DestructiveSection title="Delete client" description="…" actionLabel="Delete" onConfirm={…} />`; it opens its own AlertDialog. A per-row destructive action uses AlertDialog directly.
+- **Read-only details as label and value pairs** → `MetadataList`, `Field`. Not: a Table with two columns, Text pairs in a Stack.
+  `<MetadataList items={[{ term: "Owner", description: "Ada" }]} />` for a set; `Field` for one pair.
+- **A person, or a group of people** → `Avatar`, `AvatarGroup`. Not: an image in a rounded Box.
+  `<Avatar src alt initials />`; several in a row: `<AvatarGroup max={3}>…Avatars…</AvatarGroup>`.
+- **A date or time** → `Timestamp`. Not: a formatted string in Text.
+  `<Timestamp date="2026-10-14" />` renders a `<time dateTime>`; a date in a table cell may stay plain text.
+- **A keyboard key or shortcut hint** → `Kbd`. Not: `InlineCode`, Text in a Box.
+  `<Kbd>⌘K</Kbd>`.
+- **A quotation with attribution** → `Blockquote`. Not: Callout for a quote, italic Text.
+  `<Blockquote attribution="Ada Lovelace">…</Blockquote>`.
+- **A fixed-width side rail beside fluid content, or a row that stacks when narrow** → `Sidebar`, `Switcher`. Not: a Grid with media queries.
+  `Sidebar` (`side`, `sideWidth`) for rail + content; `Switcher` (`threshold`) for a row that flips to a column. Neither needs a media query.
+- **Keep an element stuck while its region scrolls** → `Pin`. Not: position: sticky in style.
+  `<Pin top="…">…</Pin>` inside the scrolling region.
+
 ## System Architecture
 
 - Engine: React + TypeScript
@@ -36,56 +95,105 @@ This file intentionally does not embed prop tables or long-form API docs.
 - Detailed prop types, unions, defaults, and descriptions: read `src/app/data/component-api.json`.
 - Runtime behavior: read the actual component source under `src/app/components/` (and associated styles).
 
+## Core set
+
+The 43 components of the ratified core set (hds#254, ADR-031): brand-neutral, composable, imported from the package root. Build a screen from these first. Each has `core: true` in `public/hds-manifest.json` and is marked `[core]` under "Which one when". Composed pattern modules (page shells, forms, code blocks, page sections) are imported from `@hirobius/design-system/patterns`.
+
+- Button (Actions)
+- Avatar (Display)
+- Card (Display)
+- EmptyState (Display)
+- Field (Display)
+- Icon (Display)
+- Kbd (Display)
+- Table (Display)
+- Alert (Feedback)
+- Badge (Feedback)
+- Progress (Feedback)
+- Skeleton (Feedback)
+- Spinner (Feedback)
+- ToastProvider (Feedback)
+- Checkbox (Inputs)
+- Combobox (Inputs)
+- Input (Inputs)
+- Radio (Inputs)
+- SegmentedControl (Inputs)
+- Select (Inputs)
+- Slider (Inputs)
+- Tag (Inputs)
+- Textarea (Inputs)
+- Toggle (Inputs)
+- Box (Layout)
+- Container (Layout)
+- Disclosure (Layout)
+- Divider (Layout)
+- Grid (Layout)
+- Stack (Layout)
+- Surface (Layout)
+- Breadcrumb (Navigation)
+- InlineLink (Navigation)
+- Pagination (Navigation)
+- Tabs (Navigation)
+- Dialog (Overlays)
+- Menu (Overlays)
+- Popover (Overlays)
+- Tooltip (Overlays)
+- HdsRouterProvider (Theming)
+- HdsThemeProvider (Theming)
+- Text (Typography)
+- VisuallyHidden (Utility)
+
 ## Which one when
 
-One line per component that declares when to use it (`@usage` / `@useInstead` in its JSDoc). Full detail, including `usage.whenNot`, `keyboard` and `aiRules`, is in `public/hds-manifest.json` and `src/app/data/component-api.json`.
-
-Alert: Show a persistent inline message with a severity, next to the content it concerns. Use instead: ToastProvider, Badge
-Avatar: Show a person or entity as an image with an initials fallback. Use instead: Icon, Badge
-Badge: Label a status, state or count with a compact neutral or semantic chip, or a dot. Use instead: Tag, Alert
-Box: Build one-off layout that no named layout primitive covers, using token keys through `sx`. Use instead: Stack, Grid, Container
-Breadcrumb: Show where the current page sits in a hierarchy and link back up it. Use instead: Tabs, Pagination
-Button: Trigger an action (submit, save, open a dialog) with a text label and optional icons; for an icon-only control pass iconOnly with iconLeft and label; for an on/off toggle pass pressed. Use instead: InlineLink
-Card: Group related content on a raised surface with header, body, footer and metric slots, or as one selectable option. Use instead: Surface, Card.Metric
-CardMetric: Show one headline figure (a KPI, a count, a total) with its label inside a Card.
-Checkbox: Let people tick one or more independent options, or a parent choice that is partly selected. Use instead: Toggle, Radio
-Combobox: Pick one value, or several with `multiple`, from a long list of options, with a search field that filters as you type. Use instead: Select, Menu
-Container: Constrain a page region to the content or maximum width and centre it. Use instead: Stack, Grid, Box
-Dialog: Interrupt the page with a modal that needs a decision or focused input before people continue. Use instead: Tooltip, Alert, ToastProvider
-Disclosure: Hide optional explanatory content behind a heading that people can expand. Use instead: Tabs
-Divider: Separate two regions of content with a thin semantic rule. Use instead: Stack, Surface
-EmptyState: Say that a list, grid or section has no data yet, with a title and an optional description. Use instead: Skeleton, Alert
-Field: Show a labelled read-only value, such as a name and its value in a detail view. Use instead: Input, Card.Metric
-Grid: Lay out content in responsive columns with token-governed gaps, or align nested content with subgrid. Use instead: Stack, Box
-HdsRouterProvider: Wrap the app root once so HDS links and navigation use your client router; with no provider they stay plain anchors.
-HdsThemeProvider: Wrap an app or region once to set theme, density and other root attributes for everything inside it. Use instead: Surface
-Icon: Draw a Lucide glyph at a size and colour from the design tokens. Use instead: Button, Avatar
-InlineLink: Link to a route or external URL from inside body copy. Use instead: Button, Text
-Input: Collect a single line of text, a number, an email, a password, a date or a time, with label, helper and error slots. Use instead: Textarea, Select, Combobox
-Kbd: Show a keyboard key or shortcut hint inline, as a native kbd element. Use instead: Text
-Menu: Offer a list of actions from a trigger, closed until opened. Use instead: Select
-Pagination: Move between pages of a long result set, with truncated page numbers. Use instead: Breadcrumb
-Popover: Anchor interactive content, such as a short form, a filter set or a picker, to a trigger people click to open. Use instead: Tooltip, Menu, Dialog
-Progress: Show how far a task has got, as a bar or ring that is determinate or indeterminate. Use instead: Spinner, Skeleton
-Radio: Choose exactly one option from a small set that should stay visible together. Use instead: Checkbox, Select, SegmentedControl
-SegmentedControl: Switch between two to five mutually exclusive views or modes in a compact row. Use instead: Radio, Tabs, Select
-Select: Choose one value from a short list of options in a form field. Use instead: Menu, Combobox
-Skeleton: Reserve the shape of content that is still loading, so the layout does not jump. Use instead: Progress, Spinner
-Slider: Pick a number within a known range by dragging, when the exact value matters less than the position. Use instead: Input
-Spinner: Show that something is loading when the wait is short or has no measurable end. Use instead: Progress, Skeleton
-Stack: Space a row or column of content with token gaps and simple flex alignment. Use instead: Grid, Surface
-Stat: Show one standalone headline figure with its label and an optional sub-line. Use instead: Card.Metric, StatusTile
-StatusTile: Show a titled status block with optional notes and a trailing badge or affordance. Use instead: Card.Metric, StatusListItem
-Surface: Wrap content in a padded, background-bearing inset surface with no header or footer anatomy. Use instead: Card, Stack
-Table: Show rows of structured data in aligned columns, with optional sorting. Use instead: Field, Stack
-Tabs: Switch between panels of related content in the same place, one visible at a time. Use instead: SegmentedControl, Disclosure
-Tag: Show an interactive filter or category chip that people can toggle. Use instead: Badge
-Text: Set any text on the type ramp, with the element chosen by `as`. Use instead: InlineLink, Kbd
-Textarea: Collect multi-line free text such as a message, note or description. Use instead: Input
-ToastProvider: Confirm an action with a brief message that appears and dismisses itself, through useToast. Use instead: Alert, Dialog
-Toggle: Switch one setting on or off, with the effect applying immediately. Use instead: Checkbox, Radio
-Tooltip: Name an icon-only control, or add a short hint that appears on hover and keyboard focus. Use instead: Popover, Text
-VisuallyHidden: Give assistive technology a label or description that sighted people do not need to see. Use instead: Text
+One line per component that declares when to use it (`@usage` / `@useInstead` in its JSDoc); `[core]` marks the core set. Full detail, including `usage.whenNot`, `keyboard` and `aiRules`, is in `public/hds-manifest.json` and `src/app/data/component-api.json`.
+
+Alert: [core] Show a persistent inline message with a severity, next to the content it concerns. Use instead: ToastProvider, Badge
+AlertDialog: Confirm a destructive or irreversible action (delete, archive, remove) before it runs, with Cancel and Action buttons. Use instead: Dialog, ToastProvider
+Avatar: [core] Show a person or entity as an image with an initials fallback. Use instead: Icon, Badge
+Badge: [core] Label a status, state or count with a compact neutral or semantic chip, or a dot. Use instead: Tag, Alert
+Box: [core] Build one-off layout that no named layout primitive covers, using token keys through `sx`. Use instead: Stack, Grid, Container
+Breadcrumb: [core] Show where the current page sits in a hierarchy and link back up it. Use instead: Tabs, Pagination
+Button: [core] Trigger an action (submit, save, open a dialog) with a text label and optional icons; for an icon-only control pass iconOnly with iconLeft and label; for an on/off toggle pass pressed. Use instead: InlineLink
+Card: [core] Group related content on a raised surface with header, body, footer and metric slots, or as one selectable option. Use instead: Surface, Card.Metric
+CardMetric: Show one headline figure (a KPI, a count, a total) with its label inside a Card. Use instead: MetricTiles
+Checkbox: [core] Let people tick one or more independent options, or a parent choice that is partly selected. Use instead: Toggle, Radio
+Combobox: [core] Pick one value, or several with `multiple`, from a long list of options, with a search field that filters as you type. Use instead: Select, Menu
+Container: [core] Constrain a page region to the content or maximum width and centre it. Use instead: Stack, Grid, Box
+Dialog: [core] Interrupt the page with a modal that needs a decision or focused input before people continue. Use instead: Tooltip, Alert, ToastProvider, AlertDialog
+Disclosure: [core] Hide optional explanatory content behind a heading that people can expand. Use instead: Tabs
+Divider: [core] Separate two regions of content with a thin semantic rule. Use instead: Stack, Surface
+EmptyState: [core] Say that a list, grid or section has no data yet, with a title and an optional description. Use instead: Skeleton, Alert
+Field: [core] Show a labelled read-only value, such as a name and its value in a detail view. Use instead: Input, Card.Metric
+Grid: [core] Lay out content in responsive columns with token-governed gaps, or align nested content with subgrid. Use instead: Stack, Box
+HdsRouterProvider: [core] Wrap the app root once so HDS links and navigation use your client router; with no provider they stay plain anchors.
+HdsThemeProvider: [core] Wrap an app or region once to set theme, density and other root attributes for everything inside it. Use instead: Surface
+Icon: [core] Draw a Lucide glyph at a size and colour from the design tokens. Use instead: Button, Avatar
+InlineLink: [core] Link to a route or external URL from inside body copy. Use instead: Button, Text
+Input: [core] Collect a single line of text, a number, an email, a password, a date or a time, with label, helper and error slots. Use instead: Textarea, Select, Combobox
+Kbd: [core] Show a keyboard key or shortcut hint inline, as a native kbd element. Use instead: Text
+Menu: [core] Offer a list of actions from a trigger, closed until opened. Use instead: Select
+Pagination: [core] Move between pages of a long result set, with truncated page numbers. Use instead: Breadcrumb
+Popover: [core] Anchor interactive content, such as a short form, a filter set or a picker, to a trigger people click to open. Use instead: Tooltip, Menu, Dialog
+Progress: [core] Show how far a task has got, as a bar or ring that is determinate or indeterminate. Use instead: Spinner, Skeleton
+Radio: [core] Choose exactly one option from a small set that should stay visible together. Use instead: Checkbox, Select, SegmentedControl
+SegmentedControl: [core] Switch between two to five mutually exclusive views or modes in a compact row. Use instead: Radio, Tabs, Select
+Select: [core] Choose one value from a short list of options in a form field. Use instead: Menu, Combobox
+Skeleton: [core] Reserve the shape of content that is still loading, so the layout does not jump. Use instead: Progress, Spinner
+Slider: [core] Pick a number within a known range by dragging, when the exact value matters less than the position. Use instead: Input
+Spinner: [core] Show that something is loading when the wait is short or has no measurable end. Use instead: Progress, Skeleton
+Stack: [core] Space a row or column of content with token gaps and simple flex alignment. Use instead: Grid, Surface
+Stat: Show one headline figure inline, inside prose or a dense list, with its label and an optional sub-line. Use instead: MetricTiles, Card.Metric, StatusTile
+StatusTile: Show a titled status block with optional notes and a trailing badge or affordance. Use instead: MetricTiles, Card.Metric, StatusListItem
+Surface: [core] Wrap content in a padded, background-bearing inset surface with no header or footer anatomy. Use instead: Card, Stack
+Table: [core] Show rows of structured data in aligned columns, with optional sorting. Use instead: Field, Stack
+Tabs: [core] Switch between panels of related content in the same place, one visible at a time. Use instead: SegmentedControl, Disclosure
+Tag: [core] Show an interactive filter or category chip that people can toggle. Use instead: Badge
+Text: [core] Set any text on the type ramp, with the element chosen by `as`. Use instead: InlineLink, Kbd
+Textarea: [core] Collect multi-line free text such as a message, note or description. Use instead: Input
+ToastProvider: [core] Confirm an action with a brief message that appears and dismisses itself, through useToast. Use instead: Alert, Dialog
+Toggle: [core] Switch one setting on or off, with the effect applying immediately. Use instead: Checkbox, Radio
+Tooltip: [core] Name an icon-only control, or add a short hint that appears on hover and keyboard focus. Use instead: Popover, Text
+VisuallyHidden: [core] Give assistive technology a label or description that sighted people do not need to see. Use instead: Text
 
 ## Tokens (Primary Source Of Truth)
 
@@ -114,7 +222,7 @@ Canonical skeleton, outermost to innermost:
 2. `Stack` (vertical rhythm between sections) or `Grid` (two-dimensional/column layout) for the structural skeleton. One section = one Section/Stack — never add a second wrapper to fake a section boundary.
 3. Reach for a named layout primitive before hand-rolling flex/grid math for a common intent: `Stack direction="row" wrap="wrap"` (wrapping row of same-ish things), `Sidebar` (fixed-width rail + fluid content, no media query), `Switcher` (row that flips to a column below a threshold, no media query). A full-height shell with a centered main region, an aspect-ratio-locked media box or a negative margin that escapes a parent padding is a `Box` with `style` (not `sx`, which applies on the client only).
 4. `Surface` for any background-bearing, padded wrapper (card, panel, inset). Never a raw element with backgroundColor + padding hand-rolled inline.
-5. Use the screen patterns (`@hirobius/design-system/patterns`) for the parts every screen repeats: `PageHeader` once at the top (breadcrumb, `heading2` title, status, actions), `MetricTiles` for any row of headline numbers, `FormActions` for a form footer (primary right-most and last in DOM order, destructive on the far left), `DataTableSection` for a titled table (toolbar slot, consumer row actions, empty state, scrolls on narrow widths without a caller `minWidth`), and `DestructiveSection` last for an irreversible action (danger button, then an `AlertDialog` confirm). Pick between `MetricTiles`, `Stat`, `Card.Metric` and `StatusTile`, and between `Card` and `Surface`, with the "Which one, when" table in `DESIGN.md`.
+5. Use the screen patterns (`@hirobius/design-system/patterns`) for the parts every screen repeats: `PageHeader` once at the top (breadcrumb, `heading2` title, status, actions), `MetricTiles` for any row of headline numbers, `FormActions` for a form footer (primary right-most and last in DOM order, destructive on the far left), `DataTableSection` for a titled table (toolbar slot, consumer row actions, empty state, scrolls on narrow widths without a caller `minWidth`), and `DestructiveSection` last for an irreversible action (danger button, then an `AlertDialog` confirm). A row of headline numbers is always `MetricTiles`; `Stat`, `Card.Metric` and `StatusTile` answer other needs (see "Pick By Need" in `llms.txt`). Pick between `Card` and `Surface` with the "Which one, when" table in `DESIGN.md`.
 6. `Box` `sx` LAST — only for genuinely one-off layout that no named primitive covers. `sx` spacing/color keys MUST be HDS token keys, never raw hex/px.
 
 Negative rules (apply everywhere, checked by `scripts/audit-tokens.mjs --full`, `check-hardcoded-spacing.mjs`, `check-hardcoded-colors.mjs`):

package/scripts/eslint-plugin-hds/index.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Types for `@hirobius/design-system/eslint-plugin` (scripts/eslint-plugin-hds/index.mjs).
+ * Self-contained on purpose: the shapes are structural, so a consumer's own
+ * `eslint` types accept them without this file importing `eslint`.
+ */
+type RuleLevel = 'off' | 'warn' | 'error';
+
+interface HdsPlugin {
+  meta: { name: string; version: string };
+  rules: Record<
+    | 'no-raw-controls'
+    | 'no-raw-hex'
+    | 'no-raw-px-spacing'
+    | 'prefer-hds-layout-primitive'
+    | 'sx-token-first',
+    unknown
+  >;
+  configs: {
+    /** Flat config array: spread it into eslint.config.mjs. */
+    recommended: Array<{
+      name: string;
+      plugins: { hds: HdsPlugin };
+      rules: Record<string, RuleLevel>;
+    }>;
+  };
+}
+
+declare const plugin: HdsPlugin;
+export default plugin;

package/scripts/eslint-plugin-hds/index.mjs

@@ -0,0 +1,55 @@
+/**
+ * @hirobius/eslint-plugin-hds
+ *
+ * Consumer-facing ESLint plugin for apps built on @hirobius/design-system.
+ * Complements the repo-internal scripts/check-*.mjs guardrails (which only
+ * run inside this repo) by shipping the same layout/token discipline as an
+ * installable plugin for downstream consumers. See README.md for install +
+ * usage. Ships inside @hirobius/design-system as the `./eslint-plugin`
+ * subpath (`import hds from '@hirobius/design-system/eslint-plugin'`).
+ *
+ * Flat-config only (ESLint 9+) — exports a self-referencing `recommended`
+ * config array, the standard pattern for ESLint 9/10 plugins.
+ */
+import { readFileSync } from 'node:fs';
+import noRawControls from './rules/no-raw-controls.mjs';
+import noRawHex from './rules/no-raw-hex.mjs';
+import noRawPxSpacing from './rules/no-raw-px-spacing.mjs';
+import preferHdsLayoutPrimitive from './rules/prefer-hds-layout-primitive.mjs';
+import sxTokenFirst from './rules/sx-token-first.mjs';
+
+// One source for name and version: the plugin's own package.json (shipped with it).
+const { name, version } = JSON.parse(
+  readFileSync(new URL('./package.json', import.meta.url), 'utf8'),
+);
+const packageMeta = { name, version };
+
+/** @type {import('eslint').ESLint.Plugin} */
+const plugin = {
+  meta: packageMeta,
+  rules: {
+    'no-raw-controls': noRawControls,
+    'no-raw-hex': noRawHex,
+    'no-raw-px-spacing': noRawPxSpacing,
+    'prefer-hds-layout-primitive': preferHdsLayoutPrimitive,
+    'sx-token-first': sxTokenFirst,
+  },
+};
+
+plugin.configs = {
+  recommended: [
+    {
+      name: 'hds/recommended',
+      plugins: { hds: plugin },
+      rules: {
+        'hds/no-raw-controls': 'error',
+        'hds/no-raw-hex': 'error',
+        'hds/no-raw-px-spacing': 'error',
+        'hds/prefer-hds-layout-primitive': 'warn',
+        'hds/sx-token-first': 'error',
+      },
+    },
+  ],
+};
+
+export default plugin;

package/scripts/eslint-plugin-hds/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@hirobius/eslint-plugin-hds",
+  "version": "0.2.0",
+  "description": "Consumer ESLint plugin for the Hirobius Design System — flags raw hex/px values in style, className and Box sx, and raw HTML form controls.",
+  "type": "module",
+  "main": "index.mjs",
+  "files": [
+    "index.mjs",
+    "index.d.mts",
+    "rules",
+    "README.md"
+  ],
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "hirobius",
+    "design-system"
+  ],
+  "peerDependencies": {
+    "eslint": "^9.0.0 || ^10.0.0"
+  },
+  "scripts": {
+    "test": "pnpm --dir ../.. exec vitest run scripts/eslint-plugin-hds"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "index.d.mts"
+}

package/scripts/eslint-plugin-hds/rules/no-raw-controls.mjs

@@ -0,0 +1,47 @@
+/**
+ * hds/no-raw-controls
+ *
+ * Errors on the raw HTML form controls an HDS component replaces: <button>,
+ * <input>, <select>, <textarea> and <form>. The HDS versions carry the label,
+ * focus ring, error slot and field rhythm, so a raw element is a control that
+ * looks and behaves unlike the rest of the screen. Only lowercase intrinsic
+ * JSX names are checked; `<Button>` and `<AlertDialog.Action>` are components.
+ */
+const REPLACEMENT = {
+  button: 'Button',
+  input: 'Input',
+  select: 'Select',
+  textarea: 'Textarea',
+  form: 'Form',
+};
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow raw <button>, <input>, <select>, <textarea> and <form>; use the HDS component.',
+      recommended: true,
+      url: 'https://github.com/hirobius/hds/blob/main/scripts/eslint-plugin-hds/README.md#hdsno-raw-controls',
+    },
+    schema: [],
+    messages: {
+      rawControl:
+        'Raw <{{element}}> — use the HDS `{{component}}` instead (Form, FormActions and the field components import from @hirobius/design-system or its /patterns subpath).',
+    },
+  },
+  create(context) {
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== 'JSXIdentifier') return;
+        const component = REPLACEMENT[node.name.name];
+        if (!component) return;
+        context.report({
+          node: node.name,
+          messageId: 'rawControl',
+          data: { element: node.name.name, component },
+        });
+      },
+    };
+  },
+};

package/scripts/eslint-plugin-hds/rules/no-raw-hex.mjs

@@ -0,0 +1,70 @@
+/**
+ * hds/no-raw-hex
+ *
+ * Disallows raw hex color literals (#rgb, #rrggbb, #rrggbbaa) in a JSX
+ * `style={{ ... }}` object or a `className` string/template literal.
+ * Mirrors the intent of the internal scripts/check-hardcoded-colors.mjs
+ * gate, scoped down to the two contexts a consumer app actually authors:
+ * inline style objects and Tailwind-style arbitrary-value classNames.
+ */
+import { attrName, jsxObjectExpression, propName, stringLiteralValue } from './utils.mjs';
+
+const HEX_RE = /#[0-9a-fA-F]{3,4}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{8}\b/;
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow raw hex color literals in style or className — use an HDS color token instead.',
+      recommended: true,
+      url: 'https://github.com/hirobius/hds/blob/main/scripts/eslint-plugin-hds/README.md#hdsno-raw-hex',
+    },
+    schema: [],
+    messages: {
+      rawHexStyle:
+        'Raw hex color "{{value}}" in style prop "{{prop}}" bypasses HDS color tokens. Use a token reference — Box sx prop color: "content.primary", or var(--semantic-color-...).',
+      rawHexClassName:
+        'Raw hex color "{{value}}" in className bypasses HDS color tokens. Use a token-backed utility class or Box sx instead of an arbitrary hex value.',
+    },
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        const name = attrName(node);
+        if (name === 'style') {
+          const obj = jsxObjectExpression(node.value);
+          if (!obj) return;
+          for (const prop of obj.properties) {
+            if (prop.type !== 'Property') continue;
+            const value = stringLiteralValue(prop.value);
+            if (value != null && HEX_RE.test(value)) {
+              context.report({
+                node: prop.value,
+                messageId: 'rawHexStyle',
+                data: { value, prop: propName(prop.key) ?? '?' },
+              });
+            }
+          }
+          return;
+        }
+
+        if (name === 'className') {
+          let value = null;
+          if (node.value && node.value.type === 'Literal' && typeof node.value.value === 'string') {
+            value = node.value.value;
+          } else if (node.value && node.value.type === 'JSXExpressionContainer') {
+            value = stringLiteralValue(node.value.expression);
+          }
+          if (typeof value === 'string' && HEX_RE.test(value)) {
+            context.report({
+              node: node.value,
+              messageId: 'rawHexClassName',
+              data: { value: value.match(HEX_RE)[0] },
+            });
+          }
+        }
+      },
+    };
+  },
+};

package/scripts/eslint-plugin-hds/rules/no-raw-px-spacing.mjs

@@ -0,0 +1,125 @@
+/**
+ * hds/no-raw-px-spacing
+ *
+ * Disallows raw pixel strings (`'16px'`) or bare numeric literals (`16`) on
+ * margin/padding/gap family properties inside a JSX `style={{ ... }}`
+ * object. Zero is exempt (a reset has no scale to violate). Mirrors the
+ * intent of scripts/check-hardcoded-spacing.mjs for consumer app code.
+ *
+ * The fix it offers is the t-shirt scale token, and, where Box `sx` has a
+ * key for the same CSS property, that key with a step name. Box `sx` resolves
+ * step names on its spacing keys only (`mb: 'md'`); a long-hand key
+ * (`marginBottom: 'md'`) passes through as invalid CSS and renders no
+ * spacing, so the message names the shorthand, never the flagged prop.
+ */
+import {
+  attrName,
+  jsxObjectExpression,
+  numberLiteralValue,
+  propName,
+  stringLiteralValue,
+} from './utils.mjs';
+
+const SPACING_PROPS = new Set([
+  'margin',
+  'marginTop',
+  'marginBottom',
+  'marginLeft',
+  'marginRight',
+  'marginBlock',
+  'marginInline',
+  'marginBlockStart',
+  'marginBlockEnd',
+  'marginInlineStart',
+  'marginInlineEnd',
+  'padding',
+  'paddingTop',
+  'paddingBottom',
+  'paddingLeft',
+  'paddingRight',
+  'paddingBlock',
+  'paddingInline',
+  'paddingBlockStart',
+  'paddingBlockEnd',
+  'paddingInlineStart',
+  'paddingInlineEnd',
+  'gap',
+  'rowGap',
+  'columnGap',
+]);
+
+// Long-hand style prop → the Box sx key that sets the same CSS property and
+// resolves t-shirt steps (src/app/components/box-sx.ts SPACING_PROP_MAP).
+// Logical props have none: sx `mx`/`my`/`px`/`py` set physical sides, which
+// match `*Inline`/`*Block` only in horizontal writing modes.
+const SX_SHORTHAND = {
+  margin: 'm',
+  marginTop: 'mt',
+  marginBottom: 'mb',
+  marginLeft: 'ml',
+  marginRight: 'mr',
+  padding: 'p',
+  paddingTop: 'pt',
+  paddingBottom: 'pb',
+  paddingLeft: 'pl',
+  paddingRight: 'pr',
+  gap: 'gap',
+  rowGap: 'rowGap',
+  columnGap: 'columnGap',
+};
+
+const PX_STRING_RE = /^-?\d+(?:\.\d+)?px$/;
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow raw px strings or bare numbers on margin/padding/gap in inline style — use an HDS spacing token.',
+      recommended: true,
+      url: 'https://github.com/hirobius/hds/blob/main/scripts/eslint-plugin-hds/README.md#hdsno-raw-px-spacing',
+    },
+    schema: [],
+    messages: {
+      rawPxSpacing:
+        'Raw spacing value "{{value}}" on "{{prop}}" bypasses the HDS spacing scale. Use hds.semantic.space.scale.* (var(--semantic-space-scale-*)), or Box sx prop "{{sxProp}}" with a t-shirt step such as "md".',
+      rawPxSpacingNoSxShorthand:
+        'Raw spacing value "{{value}}" on "{{prop}}" bypasses the HDS spacing scale. Use hds.semantic.space.scale.* (var(--semantic-space-scale-*)). Box sx has no shorthand for "{{prop}}", so its t-shirt steps do not apply.',
+    },
+  },
+  create(context) {
+    function report(node, prop, value) {
+      const sxProp = Object.hasOwn(SX_SHORTHAND, prop) ? SX_SHORTHAND[prop] : undefined;
+      context.report(
+        sxProp
+          ? { node, messageId: 'rawPxSpacing', data: { prop, value, sxProp } }
+          : { node, messageId: 'rawPxSpacingNoSxShorthand', data: { prop, value } },
+      );
+    }
+
+    return {
+      JSXAttribute(node) {
+        if (attrName(node) !== 'style') return;
+        const obj = jsxObjectExpression(node.value);
+        if (!obj) return;
+
+        for (const prop of obj.properties) {
+          if (prop.type !== 'Property') continue;
+          const name = propName(prop.key);
+          if (!name || !SPACING_PROPS.has(name)) continue;
+
+          const strVal = stringLiteralValue(prop.value);
+          if (strVal != null && PX_STRING_RE.test(strVal)) {
+            report(prop.value, name, strVal);
+            continue;
+          }
+
+          const numVal = numberLiteralValue(prop.value);
+          if (numVal != null && numVal !== 0) {
+            report(prop.value, name, String(numVal));
+          }
+        }
+      },
+    };
+  },
+};