@hirobius/design-system 0.19.0 → 0.20.0

package/llms.txt

@@ -1,6 +1,6 @@
 # Hirobius Design System
 
-Generated: 2026-09-30T14:27:19.090Z
+Generated: 2026-10-01T13:20:49.686Z
 Primary sources: `public/hds-manifest.json`, `src/app/data/component-api.json`, `hirobius.tokens.json`
 
 ## System Architecture
@@ -42,33 +42,31 @@ One line per component that declares when to use it (`@usage` / `@useInstead` in
 
 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
+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. 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
+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 from a long list of options, with a search field that filters as you type. Use instead: Select, Menu
+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
-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
+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
-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
+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
-Progress: Show how far a task has got, as a bar that is determinate or indeterminate. Use instead: Spinner, Skeleton
+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
@@ -86,6 +84,7 @@ Text: Set any text on the type ramp, with the element chosen by `as`. Use instea
 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
 
 ## Tokens (Primary Source Of Truth)
@@ -111,16 +110,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`.
 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 +174,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 +218,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
 

package/package.json

@@ -20,17 +20,12 @@
   "author": "Adrian Milsap",
   "license": "SEE LICENSE IN NOTICE.md",
   "private": false,
-  "version": "0.19.0",
+  "version": "0.20.0",
   "engines": {
     "node": ">=20",
     "pnpm": ">=8"
   },
   "type": "module",
-  "typeCoverage": {
-    "ignoreFiles": [
-      "src/app/components/mobius-distortion.ts"
-    ]
-  },
   "module": "./dist/hirobius-ui.js",
   "types": "./dist/types/src/index.d.ts",
   "sideEffects": [
@@ -112,7 +107,13 @@
     "docs/CONSUMING.md",
     "src/app/data/component-api.json",
     "codemods/patterns-subpath.mjs",
-    "codemods/patterns-subpath.names.json"
+    "codemods/patterns-subpath.names.json",
+    "codemods/removed-0.20.json",
+    "codemods/hds-prefix.mjs",
+    "codemods/unrewritable.mjs",
+    "codemods/jsx-fold.mjs",
+    "codemods/not-found-pattern.mjs",
+    "codemods/tile-grid.mjs"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -146,26 +147,19 @@
   },
   "dependencies": {
     "@radix-ui/react-alert-dialog": "^1.1.18",
-    "@radix-ui/react-aspect-ratio": "^1.1.11",
-    "@radix-ui/react-context-menu": "^2.3.2",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.18",
-    "@radix-ui/react-hover-card": "^1.1.18",
     "@radix-ui/react-popover": "^1.1.17",
     "@radix-ui/react-select": "^2.3.1",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-toast": "^1.2.17",
-    "@radix-ui/react-toggle": "^1.1.13",
     "@radix-ui/react-toggle-group": "^1.1.13",
-    "@radix-ui/react-toolbar": "^1.1.14",
     "@radix-ui/react-tooltip": "^1.1.8",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "date-fns": "^4.4.0",
     "lucide-react": "0.487.0",
     "motion": "12.23.24",
-    "react-day-picker": "^10.0.1",
     "tailwind-merge": "^3.5.0"
   },
   "devDependencies": {
@@ -174,6 +168,7 @@
     "@changesets/cli": "^2.27.10",
     "@cyclonedx/cyclonedx-npm": "^4.2.1",
     "@figma/code-connect": "^2.0.1",
+    "@guidepup/virtual-screen-reader": "^0.33.0",
     "@hookform/resolvers": "^5.4.0",
     "@lhci/cli": "0.15.1",
     "@microsoft/api-extractor": "7.58.7",
@@ -190,7 +185,6 @@
     "@testing-library/user-event": "^14.6.7",
     "@types/react": "^18.3.0",
     "@types/react-dom": "^18.3.0",
-    "@types/three": "^0.183.1",
     "@typescript-eslint/eslint-plugin": "^8.59.1",
     "@typescript-eslint/parser": "^8.59.1",
     "@vitejs/plugin-react": "4.7.0",
@@ -210,7 +204,6 @@
     "eslint-plugin-tailwindcss": "^3.18.3",
     "express": "^5.2.1",
     "fast-check": "^4.7.0",
-    "fuse.js": "^7.1.0",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
     "jscodeshift": "^17.3.0",
@@ -234,21 +227,22 @@
     "storybook": "^8.6.18",
     "style-dictionary": "^5.4.0",
     "tailwindcss": "^4.2.4",
-    "three": "^0.183.2",
     "type-coverage": "^2.29.7",
     "typescript": "^6.0.2",
     "vite": "6.4.2",
     "vite-bundle-visualizer": "^1.2.1",
     "vitest": "^4.1.0",
     "yaml": "^2.8.1",
-    "zod": "^4.4.3",
-    "zustand": "^5.0.12"
+    "zod": "^4.4.3"
   },
   "lint-staged": {
     "*.{ts,tsx,js,jsx,mjs,cjs,json,md,mdx,css,scss,html,yaml,yml}": "prettier --write"
   },
   "bin": {
-    "hds-patterns-subpath": "codemods/patterns-subpath.mjs"
+    "hds-patterns-subpath": "codemods/patterns-subpath.mjs",
+    "hds-prefix": "codemods/hds-prefix.mjs",
+    "hds-not-found-pattern": "codemods/not-found-pattern.mjs",
+    "hds-tile-grid": "codemods/tile-grid.mjs"
   },
   "scripts": {
     "_comment:a11y-high-value": "The following check:* validators are high-value accessibility checks that catch real violations (check:focus found 1 missing focus class). Kept dormant/manual-only to avoid pre-commit performance regression. Candidates to wire into pretest after CI stability review.",
@@ -270,7 +264,7 @@
     "changelog:generate": "node scripts/generate-changelog.mjs",
     "changeset": "changeset",
     "changeset:add": "changeset",
-    "changeset:version": "changeset version",
+    "changeset:version": "changeset version && node scripts/audit-component-integrity.mjs --api --update-baseline",
     "check": "pnpm check:full",
     "check:a11y": "pnpm lint --rule '{\"jsx-a11y/alt-text\":\"error\",\"jsx-a11y/img-redundant-alt\":\"error\"}'",
     "check:attributions": "node scripts/check-attributions.mjs",
@@ -302,12 +296,14 @@
     "check:knip": "knip",
     "check:knip-ratchet": "knip --max-issues 60",
     "check:layout-discipline": "node scripts/check-layout-discipline.mjs",
+    "check:layout-gap-vocabulary": "node scripts/check-layout-gap-vocabulary.mjs",
     "check:licenses": "node scripts/check-licenses.mjs",
     "check:lockfile": "pnpm install --frozen-lockfile --offline --prefer-offline --ignore-scripts --silent 2>/dev/null || (echo 'Lockfile drift: run pnpm install' && exit 1)",
     "check:manifest-drift": "node scripts/check-manifest-drift.mjs",
     "check:micromotion": "node scripts/check-motion.mjs",
     "check:mojibake": "node scripts/lib/mojibake.mjs",
     "check:motion": "node scripts/check-reduced-motion.mjs",
+    "check:pure-annotations": "node scripts/check-pure-annotations.mjs",
     "check:refs": "node scripts/check-ref-forwarding.mjs",
     "check:registry": "node scripts/check-registry.mjs",
     "check:release": "pnpm check:full && node scripts/check-style-discipline.mjs && pnpm build:lib && pnpm check:size",
@@ -377,7 +373,7 @@
     "prebuild-storybook": "node scripts/generate-component-api.mjs",
     "prebuild:lib": "node scripts/generate-component-api.mjs",
     "prestorybook": "node scripts/generate-component-api.mjs",
-    "pretest": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/check-manifest-schema-semver.mjs && node scripts/audit-component-integrity.mjs --completeness && node scripts/check-source-canon.mjs && node scripts/check-binding-drift.mjs && node scripts/check-registry.mjs && node scripts/check-tenant-tokens.mjs && node scripts/check-props-exports.mjs && knip --no-exit-code && node scripts/check-dark-alias-flip.mjs && node scripts/check-focus-states.mjs && node scripts/generate-staging-inventory.mjs --check && node scripts/generate-consumer-skill.mjs --check",
+    "pretest": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/check-manifest-schema-semver.mjs && node scripts/audit-component-integrity.mjs --completeness && node scripts/audit-component-integrity.mjs --api && node scripts/check-source-canon.mjs && node scripts/check-binding-drift.mjs && node scripts/check-registry.mjs && node scripts/check-tenant-tokens.mjs && node scripts/check-props-exports.mjs && knip --no-exit-code && node scripts/check-dark-alias-flip.mjs && node scripts/check-focus-states.mjs && node scripts/generate-staging-inventory.mjs --check && node scripts/generate-consumer-skill.mjs --check && node scripts/check-deprecations.mjs",
     "pretypecheck": "node scripts/audit-tokens.mjs --report-only",
     "preview:build": "vite build --config preview/vite.config.mjs",
     "promote": "node scripts/promote.mjs",