@hirobius/design-system 0.19.1 → 0.21.0

package/llms.txt

@@ -1,8 +1,67 @@
 # Hirobius Design System
 
-Generated: 2026-09-30T14:27:19.090Z
+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,57 +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. 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. Use instead: InlineLink
-ButtonGroup: Attach related Buttons into one segmented row or column that reads as a single control. Use instead: SegmentedControl, Stack
-Card: Group related content on a raised surface with header, body, footer and metric slots. 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 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
-ContextMenu: Offer actions for an item on right-click, or the equivalent keyboard gesture. Use instead: Menu
-Dialog: Interrupt the page with a modal that needs a decision or focused input before people continue. Use instead: HoverCard, 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
-HdsThemeProvider: Wrap an app or region once to set theme, density and other root attributes for everything inside it. Use instead: Surface
-HoverCard: Preview extra detail about a link or mention when it is hovered or focused, without navigating. Use instead: Dialog, Tooltip
-Icon: Draw a Lucide glyph at a size and colour from the design tokens. Use instead: Button, Avatar
-IconButton: Trigger an action from a compact icon-only control, always with an accessible label. Use instead: Button
-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 or a password, 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
-Progress: Show how far a task has got, as a bar 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
-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)
 
@@ -111,16 +218,16 @@ VisuallyHidden: Give assistive technology a label or description that sighted pe
 
 Canonical skeleton, outermost to innermost:
 
-1. `Page` (or `Container`/`Center` for a full-bleed, non-page surface) for the outermost width constraint. Never import `Container` directly inside `src/app/pages/**` — use `Page`, which wraps it and owns vertical rhythm.
+1. `Page` (from `@hirobius/design-system/patterns`; or `Container` for a full-bleed, non-page surface, with a `Box` inside it for a horizontal gutter) for the outermost width constraint. Never import `Container` directly inside `src/app/pages/**` — use `Page`, which wraps it and owns vertical rhythm.
 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 every-layout primitive before hand-rolling flex/grid math for a common intent: `Cluster` (wrapping row of same-ish things), `Center` (centered max-width column with optional gutter), `Sidebar` (fixed-width rail + fluid content, no media query), `Switcher` (row that flips to a column below a threshold, no media query), `Cover` (full-height shell with a centered main region), `Frame` (aspect-ratio-locked clipped media box), `Bleed` (controlled negative margin to escape a parent padding).
+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`):
 
-- No inline margins on children to fake spacing between siblings — gap/spacing on the parent (Stack/Grid/Cluster/Switcher/Sidebar/Cover) owns rhythm, not margin on the child.
+- No inline margins on children to fake spacing between siblings — gap/spacing on the parent (Stack/Grid/Switcher/Sidebar) owns rhythm, not margin on the child.
 - No raw px or hex values in any layout or color prop — every spacing value comes from the semantic gap scale (`tight | normal | inset | spacious`, or a component/subgrid step) and every color comes from a `semantic.color.*` token.
 - No repeated outlined cards as the default structure for roadmap/status/process/overview UI — use open bands, dividers, rails, disclosures, and whitespace instead.
 
@@ -175,7 +282,7 @@ When building any card component or card-like surface, ALL of the following rule
 
 Cards default to `elevation.flat`. Popovers/tooltips/dropdowns use `elevation.floating`. Dialogs/sheets use `elevation.overlay`. Interactive cards lift to `elevation.raised` on hover. Never combine `raised` with a border — depth is one mechanism (border OR shadow), not both stacked.
 
-Overlays (Dialog, AlertDialog, Menu, ContextMenu, Popover, Select, HoverCard, Tooltip) portal into the nearest `data-hds` scope, so they inherit its theme (for example `<div data-hds data-theme="dark">`); pass `container` on the Content part to override.
+Overlays (Dialog, AlertDialog, Menu, Popover, Select, Tooltip) portal into the nearest `data-hds` scope, so they inherit its theme (for example `<div data-hds data-theme="dark">`); pass `container` on the Content part to override.
 
 ## Slices And Full Bundle
 
@@ -219,19 +326,19 @@ On-demand only (load only if explicitly requested or the task clearly requires i
 Icons come from the curated subpath `@hirobius/design-system/icons`; nothing extra to install.
 
 ```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} />} />
 ```
 
-Rule: icon-only actions (row menus, close, edit) use `IconButton`; do not hand-roll a button with a glyph or text "...".
+Rule: icon-only actions (row menus, close, edit) use `Button iconOnly` with a `label` and an `Icon` in `iconLeft`; do not hand-roll a button with a glyph or text "...".
 
 Names: Archive, ArrowDown, ArrowLeft, ArrowRight, ArrowUp, Bell, Bookmark, Calendar, Check, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, CircleAlert, CircleCheck, CircleHelp, Clock, Copy, Download, Ellipsis, EllipsisVertical, ExternalLink, Eye, EyeOff, FileText, Funnel, Heart, House, Image, Info, Link, Lock, LogIn, LogOut, Mail, Menu, Minus, Pencil, Plus, RefreshCw, Save, Search, Settings, Share, Star, Trash2, TriangleAlert, Upload, User, X
 
 Legacy names map to canonical ones: MoreHorizontal -> Ellipsis, MoreVertical -> EllipsisVertical, AlertTriangle -> TriangleAlert, Home -> House, Filter -> Funnel.
 
-Name collisions: `Calendar` and `Menu` share names with HDS components; alias the icon: `import { Calendar as CalendarIcon, Menu as MenuIcon } from '@hirobius/design-system/icons'`. For an icon outside the set, install `lucide-react@0.487.0` (same version keeps the `LucideIcon` type identical).
+Name collisions: `Menu` shares a name with an HDS component; alias the icon: `import { Menu as MenuIcon } from '@hirobius/design-system/icons'`. For an icon outside the set, install `lucide-react@0.487.0` (same version keeps the `LucideIcon` type identical).
 
 ## Token Rules