@hirobius/design-system 0.22.0 → 0.23.1

package/hirobius.tokens.json

@@ -149,6 +149,53 @@
         },
         "$description": "Discrete values within the green range at defined lightness steps."
       },
+      "apple": {
+        "50": {
+          "$value": "#f2faeb",
+          "$description": "Apple-green accent tint — faintest step."
+        },
+        "100": {
+          "$value": "#e2f3cf",
+          "$description": "Apple-green accent — very light tint."
+        },
+        "200": {
+          "$value": "#c7e7a4",
+          "$description": "Apple-green accent — light tint."
+        },
+        "300": {
+          "$value": "#a6d873",
+          "$description": "Apple-green accent — soft mid-light step."
+        },
+        "400": {
+          "$value": "#85c84c",
+          "$description": "Apple-green accent — bright step; dark-mode rest accent."
+        },
+        "500": {
+          "$value": "#66b239",
+          "$description": "Apple-green accent rest — bright, rich apple green; AA for dark (neutral.900) text as a fill."
+        },
+        "600": {
+          "$value": "#54922d",
+          "$description": "Apple-green accent — hover / border step."
+        },
+        "700": {
+          "$value": "#416f20",
+          "$description": "Apple-green accent — pressed and accent-intent text (AA for text on page and card surfaces)."
+        },
+        "800": {
+          "$value": "#34571b",
+          "$description": "Apple-green accent — deep step."
+        },
+        "900": {
+          "$value": "#2b4518",
+          "$description": "Apple-green accent — darkest usable step."
+        },
+        "950": {
+          "$value": "#16250c",
+          "$description": "Apple-green accent — near-black green substrate."
+        },
+        "$description": "Discrete values within the apple-green (brand accent) range at defined lightness steps. Distinct from the emerald `green` feedback/success scale."
+      },
       "violet": {
         "50": {
           "$value": "#f5f3ff",
@@ -468,29 +515,29 @@
         "$type": "fontFamily",
         "primary": {
           "$value": [
-            "Satoshi",
+            "Plus Jakarta Sans",
             "system-ui",
             "-apple-system",
             "BlinkMacSystemFont",
             "Segoe UI",
             "sans-serif"
           ],
-          "$description": "Self-hosted Satoshi (ITF) body typeface; falls back to system-ui sans-serif stack."
+          "$description": "Self-hosted Plus Jakarta Sans (OFL) body typeface; falls back to system-ui sans-serif stack."
         },
         "display": {
           "$value": [
-            "Satoshi",
+            "Plus Jakarta Sans",
             "system-ui",
             "-apple-system",
             "BlinkMacSystemFont",
             "Segoe UI",
             "sans-serif"
           ],
-          "$description": "Display face: Satoshi Bold (ITF), bound to the display and title composites."
+          "$description": "Display face: Plus Jakarta Sans Bold (OFL), bound to the display and title composites."
         },
         "mono": {
-          "$value": ["Geist Mono", "Courier New", "monospace"],
-          "$description": "Monospace face: Geist Mono. Falls back to Courier New, monospace."
+          "$value": ["IBM Plex Mono", "Courier New", "monospace"],
+          "$description": "Monospace face: IBM Plex Mono. Falls back to Courier New, monospace."
         }
       },
       "size": {
@@ -1098,25 +1145,25 @@
           }
         },
         "accent": {
-          "$value": "{primitive.color.neutral.900}",
-          "$description": "Accent-colored background (neutral/monochrome; inverts to a light neutral on dark surfaces).",
+          "$value": "{primitive.color.apple.500}",
+          "$description": "Accent-colored background — bright apple green (stays green on dark surfaces; pair with content.onAccent dark text).",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.900}",
-                "Dark": "{primitive.color.neutral.100}"
+                "Light": "{primitive.color.apple.500}",
+                "Dark": "{primitive.color.apple.400}"
               }
             }
           }
         },
         "accentSubtle": {
-          "$value": "{primitive.color.neutral.100}",
+          "$value": "{primitive.color.apple.50}",
           "$description": "Faint accent tint for hover states or highlights",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.100}",
-                "Dark": "{primitive.color.neutral.900}"
+                "Light": "{primitive.color.apple.50}",
+                "Dark": "{primitive.color.apple.900}"
               }
             }
           }
@@ -1228,24 +1275,24 @@
           }
         },
         "accent": {
-          "$value": "{primitive.color.neutral.900}",
-          "$description": "Accent-intent text/icon color (monochrome). Pair with underline/weight for link affordance.",
+          "$value": "{primitive.color.apple.700}",
+          "$description": "Accent-intent text/icon color — a dark apple green legible on page and card surfaces. Pair with underline/weight for link affordance.",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.900}",
-                "Dark": "{primitive.color.neutral.100}"
+                "Light": "{primitive.color.apple.700}",
+                "Dark": "{primitive.color.apple.400}"
               }
             }
           }
         },
         "onAccent": {
-          "$value": "{primitive.color.neutral.white}",
-          "$description": "Text/icon color on accent fills. Flips to a dark neutral in dark mode, where accent fills are light.",
+          "$value": "{primitive.color.neutral.900}",
+          "$description": "Text/icon color on accent fills — a dark neutral, since the brand accent fill is a bright apple green in both light and dark mode.",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.white}",
+                "Light": "{primitive.color.neutral.900}",
                 "Dark": "{primitive.color.neutral.900}"
               }
             }
@@ -1347,13 +1394,13 @@
           }
         },
         "accent": {
-          "$value": "{primitive.color.neutral.900}",
-          "$description": "Accent border (neutral/monochrome; inverts on dark surfaces).",
+          "$value": "{primitive.color.apple.600}",
+          "$description": "Accent border — apple green, dark enough to read as a boundary on page and card surfaces.",
           "$extensions": {
             "com.figma.variables": {
               "modes": {
-                "Light": "{primitive.color.neutral.900}",
-                "Dark": "{primitive.color.neutral.100}"
+                "Light": "{primitive.color.apple.600}",
+                "Dark": "{primitive.color.apple.400}"
               }
             }
           }
@@ -1865,37 +1912,37 @@
     "accent": {
       "$type": "color",
       "rest": {
-        "$value": "{primitive.color.neutral.900}",
-        "$description": "Default accent fill for interactive elements at rest. Neutral (monochrome) accent — inverts to a light neutral on dark surfaces.",
+        "$value": "{primitive.color.apple.500}",
+        "$description": "Default accent fill for interactive elements at rest — bright apple green. Pair with content.onAccent (a dark neutral).",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.900}",
-              "Dark": "{primitive.color.neutral.100}"
+              "Light": "{primitive.color.apple.500}",
+              "Dark": "{primitive.color.apple.400}"
             }
           }
         }
       },
       "hover": {
-        "$value": "{primitive.color.neutral.800}",
+        "$value": "{primitive.color.apple.600}",
         "$description": "Accent fill on pointer hover.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.800}",
-              "Dark": "{primitive.color.neutral.200}"
+              "Light": "{primitive.color.apple.600}",
+              "Dark": "{primitive.color.apple.500}"
             }
           }
         }
       },
       "pressed": {
-        "$value": "{primitive.color.neutral.950}",
+        "$value": "{primitive.color.apple.700}",
         "$description": "Accent fill during active press.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.950}",
-              "Dark": "{primitive.color.neutral.300}"
+              "Light": "{primitive.color.apple.700}",
+              "Dark": "{primitive.color.apple.600}"
             }
           }
         }
@@ -1925,37 +1972,37 @@
         }
       },
       "content": {
-        "$value": "{primitive.color.neutral.900}",
-        "$description": "Text and icon color on neutral surfaces with accent intent. Monochrome — pair with underline/weight for link affordance.",
+        "$value": "{primitive.color.apple.700}",
+        "$description": "Accent-intent text/icon color on neutral surfaces (a dark apple green) — pair with underline/weight for link affordance.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.900}",
-              "Dark": "{primitive.color.neutral.100}"
+              "Light": "{primitive.color.apple.700}",
+              "Dark": "{primitive.color.apple.400}"
             }
           }
         }
       },
       "contentHover": {
-        "$value": "{primitive.color.neutral.700}",
+        "$value": "{primitive.color.apple.800}",
         "$description": "Accent content color on pointer hover.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.700}",
-              "Dark": "{primitive.color.neutral.300}"
+              "Light": "{primitive.color.apple.800}",
+              "Dark": "{primitive.color.apple.300}"
             }
           }
         }
       },
       "subtle": {
-        "$value": "{primitive.color.neutral.100}",
+        "$value": "{primitive.color.apple.50}",
         "$description": "Low-emphasis accent tint for hover backgrounds and selection highlights.",
         "$extensions": {
           "com.figma.variables": {
             "modes": {
-              "Light": "{primitive.color.neutral.100}",
-              "Dark": "{primitive.color.neutral.800}"
+              "Light": "{primitive.color.apple.50}",
+              "Dark": "{primitive.color.apple.900}"
             }
           }
         }

package/llms.txt

@@ -1,6 +1,6 @@
 # Hirobius Design System
 
-Generated: 2026-10-07T16:09:09.631Z
+Generated: 2026-10-09T13:43:23.079Z
 Primary sources: `public/hds-manifest.json`, `src/app/data/component-api.json`, `hirobius.tokens.json`
 
 ## Agents Using The Package: Start Here
@@ -9,6 +9,16 @@ Primary sources: `public/hds-manifest.json`, `src/app/data/component-api.json`,
 - 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`.
 
+## Voice
+
+How these docs speak. Every page, and every agent writing for HDS, follows it. Source: `content/docs/voice.mdx` (published at `/docs/voice`).
+
+- Use plain words a reader already knows. Name a thing by what it does, not by how it is built.
+- Keep sentences short, one idea each.
+- Tell the reader what to do. Leave out brand adjectives.
+- Keep maintainer references off public pages: issue and ADR numbers, script names, internal counts.
+- Don't use: "systems-first".
+
 ## 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`.
@@ -149,42 +159,54 @@ One line per component that declares when to use it (`@usage` / `@useInstead` in
 
 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
+AssetImg: Show an image that scales to its frame, with a placeholder if it fails to load.
 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
+Button: [core] Run an action, such as submit, save or open a dialog. For an icon-only control pass iconOnly, 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
+CodeBlock: Show a code sample with a copy button, optionally collapsed.
 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
+DataTableSection: Put a heading and toolbar above a Table.
+DestructiveSection: Put a dangerous action, such as delete, in its own section with a warning and a confirm step.
 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
+Divider: [core] Separate two blocks of content with a thin line. 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
+ErrorPattern: Show an error with a short message and a Back button, in place or as a full page.
 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
+Form: Wrap form fields so they stack with even spacing.
+FormActions: Lay out a form's buttons in a fixed order: danger on the left, then secondary, then primary on the right.
+Grid: [core] Lay out content in columns that adapt to the screen width, or line up 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
+Icon: [core] Show a Lucide icon at a set size and color. 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
+MetricTile: Show one key number with its label, inside a MetricTiles row.
+MetricTiles: Show a row of key numbers, one tile each.
+Page: Wrap a screen in the standard width and padding.
+PageHeader: Open a screen with its title, plus optional breadcrumb, status and actions.
 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
+Reveal: Fade content in as it scrolls into view.
 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
+Stack: [core] Space items in a row or column with even gaps. 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
+Surface: [core] Give a block of content a background and padding, with no header or footer. 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

package/package.json

@@ -18,9 +18,9 @@
     "url": "git+https://github.com/hirobius/hds.git"
   },
   "author": "Adrian Milsap",
-  "license": "SEE LICENSE IN NOTICE.md",
+  "license": "MIT AND OFL-1.1",
   "private": false,
-  "version": "0.22.0",
+  "version": "0.23.1",
   "engines": {
     "node": ">=20",
     "pnpm": ">=8"
@@ -191,6 +191,7 @@
     "@arethetypeswrong/cli": "^0.18.4",
     "@axe-core/playwright": "^4.11.1",
     "@changesets/cli": "^2.27.10",
+    "@chromatic-com/playwright": "^1.0.0",
     "@cyclonedx/cyclonedx-npm": "^4.2.1",
     "@figma/code-connect": "^2.0.1",
     "@guidepup/virtual-screen-reader": "^0.33.0",
@@ -241,6 +242,7 @@
     "pixelmatch": "^7.1.0",
     "playwright": "^1.58.2",
     "pngjs": "^7.0.0",
+    "postcss": "8.5.10",
     "prettier": "^3.8.3",
     "publint": "^0.3.21",
     "react": "18.3.1",
@@ -286,13 +288,13 @@
     "audit:sidecar": "node scripts/generate-security-posture.mjs",
     "audit:style-dictionary": "bash scripts/poc/style-dictionary-poc/run.sh",
     "build-storybook": "storybook build",
-    "build:lib": "vite build -c vite.config.lib.ts && pnpm build:types && node scripts/build-vars-css.mjs && node scripts/build-fonts-css.mjs && node scripts/build-styles-css.mjs && node scripts/build-static-css.mjs",
+    "build:lib": "vite build -c vite.config.lib.ts && pnpm build:types && node scripts/build-vars-css.mjs && node scripts/build-fonts-css.mjs && node scripts/build-styles-css.mjs && node scripts/build-static-css.mjs && node scripts/build-css-contract.mjs",
     "build:types": "tsc -p tsconfig.dts.json && node scripts/strip-dts-side-effects.mjs && node scripts/add-dts-extensions.mjs",
     "catalog": "node scripts/generate-visual-catalog.mjs",
     "changelog:generate": "node scripts/generate-changelog.mjs",
     "changeset": "changeset",
     "changeset:add": "changeset",
-    "changeset:version": "changeset version && node scripts/upgrade/compile.mjs --release && node scripts/audit-component-integrity.mjs --api --update-baseline",
+    "changeset:version": "changeset version && pnpm build:lib && node scripts/upgrade/compile.mjs --release && 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",
@@ -343,12 +345,13 @@
     "check:secrets": "node scripts/check-secrets.mjs",
     "check:security": "node scripts/check-security-baseline.mjs",
     "check:semantic-report": "node scripts/audit-tokens.mjs --report-only",
-    "check:size": "pnpm build:lib && node scripts/build-button-probe.mjs && size-limit",
+    "check:size": "pnpm build:lib && node scripts/build-button-probe.mjs && pnpm size-limit",
     "check:spacing": "node scripts/check-hardcoded-spacing.mjs",
     "check:spacing-vocabulary": "node scripts/check-spacing-vocabulary.mjs",
     "check:story-coverage": "node scripts/check-story-coverage.mjs",
     "check:layout-contract": "node scripts/check-layout-contract.mjs",
     "check:spacing-scale": "node scripts/check-tailwind-spacing-scale.mjs",
+    "check:docs-axe": "node scripts/check-docs-axe.mjs",
     "check:storybook-axe": "node scripts/check-storybook-axe.mjs",
     "check:style-props": "node scripts/check-style-discipline.mjs --style-props-only",
     "check:sync-map": "node scripts/check-sync-map.mjs",
@@ -366,11 +369,13 @@
     "check:tokens": "node scripts/check-hardcoded-colors.mjs && pnpm lint --rule '{\"tailwindcss/no-custom-classname\":\"error\"}' && node scripts/audit-tokens.mjs --forbidden && node scripts/check-tier-bypass.mjs && node scripts/check-hardcoded-spacing.mjs && node scripts/check-typography-discipline.mjs --fonts-only",
     "check:type-coverage": "pnpm exec type-coverage --at-least 99.9",
     "chromatic": "chromatic --exit-zero-on-changes",
+    "test:visual-docs": "playwright test",
     "closure:plan": "node scripts/run-gates.mjs --channel pre-commit --emit-inventory docs/guardrails/full-strictness-inventory.json && node scripts/generate-closure-plan.mjs",
     "closure:plan:check": "node scripts/generate-closure-plan.mjs --check",
     "docs:api": "node scripts/generate-component-api.mjs",
     "docs:changelogs": "node scripts/generate-component-changelogs.mjs",
     "docs:build": "pnpm docs:prepare && pnpm --dir docs-site build",
+    "docs:publish": "pnpm docs:build && node scripts/generate-manifest-projection.mjs && node scripts/copy-agent-context.mjs --out docs-site/out --with-public && node scripts/figma-push.mjs --bundle docs-site/out/figma/sync-bundle.json",
     "docs:components": "node scripts/generate-docs-components.mjs",
     "docs:component": "node scripts/generate-component-page.mjs",
     "docs:dev": "pnpm docs:prepare && pnpm --dir docs-site dev",
@@ -416,11 +421,11 @@
     "release": "pnpm build:lib && pnpm smoke:consumer --skip-build && changeset publish",
     "scaffold:component": "node scripts/scaffold-component.mjs",
     "scaffold:tenant": "node scripts/scaffold-tenant.mjs",
-    "size-limit": "size-limit --config .size-limit.cjs",
+    "size-limit": "node scripts/run-size-limit.mjs",
     "layout-contract:generate": "node scripts/generate-layout-contract.mjs",
     "status:touch": "node scripts/status-touch.mjs",
     "status:fold": "node scripts/status-fold.mjs",
-    "smoke:consumer": "node scripts/smoke-consumer.mjs && node scripts/check-published-types.mjs && node scripts/check-rsc-directives.mjs && node scripts/check-pack-contents.mjs",
+    "smoke:consumer": "node scripts/smoke-consumer.mjs && node scripts/check-published-types.mjs && node scripts/check-rsc-directives.mjs && node scripts/check-pack-contents.mjs && node scripts/check-upgrade-css.mjs",
     "storybook": "storybook dev -p 6006",
     "storybook:deploy": "node scripts/deploy-storybook.mjs",
     "sync": "node scripts/build-tokens.mjs && node scripts/audit-tokens.mjs --forbidden && node scripts/build-handoff.mjs && node scripts/build-design-md.mjs && node scripts/build-figma-variables.mjs",