@hirobius/design-system 0.22.0 → 0.23.0

package/dist/tokens.js

@@ -42,6 +42,19 @@ const a = {
         700: "#047857",
         950: "#022c22"
       },
+      apple: {
+        50: "#f2faeb",
+        100: "#e2f3cf",
+        200: "#c7e7a4",
+        300: "#a6d873",
+        400: "#85c84c",
+        500: "#66b239",
+        600: "#54922d",
+        700: "#416f20",
+        800: "#34571b",
+        900: "#2b4518",
+        950: "#16250c"
+      },
       violet: {
         50: "#f5f3ff",
         400: "#a78bfa",
@@ -122,7 +135,7 @@ const a = {
       family: {
         primary: ["Satoshi", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"],
         display: ["Satoshi", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"],
-        mono: ["Geist Mono", "Courier New", "monospace"]
+        mono: ["IBM Plex Mono", "Courier New", "monospace"]
       },
       size: {
         xs: "12px",

package/dist/types/src/app/components/asset-img.d.ts

@@ -2,6 +2,7 @@
  * AssetImg - responsive asset frame with fallback placeholder handling.
  * Contexts: default, lightbox, and detail.
  * @category Display
+ * @usage Show an image that scales to its frame, with a placeholder if it fails to load.
  * @tier primitive
  * @figma https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2041-67
  */

package/dist/types/src/app/components/button.d.ts

@@ -65,7 +65,7 @@ export interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonE
 }
 /**
  * Triggers an action when activated.
- * @usage 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.
+ * @usage 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.
  * @whenNot Navigating to another page, where a link is the correct element.
  * @useInstead InlineLink navigation to another page
  */

package/dist/types/src/app/components/callout.d.ts

@@ -18,7 +18,8 @@ export interface CalloutProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     italic?: boolean;
 }
 /**
- * Tone-driven side-rule callout for status, quotes, hypotheses.
+ * Tone-driven tinted callout for notes, quotes, hypotheses — the same feedback
+ * fill language as Alert, without Alert's icon or status role.
  */
 export declare const Callout: React.ForwardRefExoticComponent<CalloutProps & React.RefAttributes<HTMLDivElement>>;
 export default Callout;

package/dist/types/src/app/components/card.d.ts

@@ -39,9 +39,11 @@
  * Existing callers that pass raw children continue to work; new callers
  * should prefer compound parts + `padding="none"`.
  *
- * Depth comes from semantic.color.border.default (role.border) at rest;
- * elevation tokens are not bound by default — pass `className="shadow-..."`
- * for a hover/floating treatment on interactive cards.
+ * The default variant is BORDERLESS at rest (12d-3 outline rule) — depth comes
+ * from whitespace/dividers, not an edge. A resting 1px border is opt-in via
+ * `bordered` (border.default), a feedback `tone`, or `accent` (border.accent).
+ * Elevation tokens are not bound by default — pass `className="shadow-..."` for
+ * a hover/floating treatment on interactive cards.
  */
 import * as React from 'react';
 import hds from '../design-system/tokens.js';

package/dist/types/src/app/components/code-block.d.ts

@@ -1,6 +1,7 @@
 /**
  * CodeBlock - code display with copy button and optional collapsible toggle.
  * @category Display
+ * @usage Show a code sample with a copy button, optionally collapsed.
  * @tier primitive
  * @figma https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-154
  */

package/dist/types/src/app/components/combobox.d.ts

@@ -7,7 +7,7 @@
  * @useInstead Select a short list without search
  * @useInstead Menu firing actions from a trigger
  * @keyboard Enter/Space Opens the list from the trigger and moves focus to the search field.
- * @keyboard ArrowDown/ArrowUp Moves the active option and wraps at the ends.
+ * @keyboard ArrowDown/ArrowUp Moves the active option, skipping disabled ones, and wraps at the ends.
  * @keyboard Character Filters the options to those matching the typed text.
  * @keyboard Enter Commits the active option and closes the list; with `multiple`, toggles it and keeps the list open.
  * @keyboard Escape Closes the list.

package/dist/types/src/app/components/data-table-section.d.ts

@@ -1,6 +1,7 @@
 /**
  * DataTableSection - a titled table with a toolbar, row actions and an empty state.
  * @category Display
+ * @usage Put a heading and toolbar above a Table.
  * @tier pattern
  * @figma https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2075-268
  */

package/dist/types/src/app/components/destructive-section.d.ts

@@ -1,6 +1,7 @@
 /**
  * DestructiveSection - the one place a screen puts an irreversible action.
  * @category Actions
+ * @usage Put a dangerous action, such as delete, in its own section with a warning and a confirm step.
  * @tier pattern
  * @figma https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2076-3
  */

package/dist/types/src/app/components/divider.d.ts

@@ -2,7 +2,7 @@
  * Divider — semantic separator between content regions.
  * @category Layout
  * @tier primitive
- * @usage Separate two regions of content with a thin semantic rule.
+ * @usage Separate two blocks of content with a thin line.
  * @whenNot Spacing alone would do, or the separation needs a container.
  * @useInstead Stack gap-based spacing between siblings
  * @useInstead Surface a bounded region with its own background

package/dist/types/src/app/components/form-actions.d.ts

@@ -1,6 +1,7 @@
 /**
  * FormActions - the footer row of a form: primary right-most, secondary to its left.
  * @category Actions
+ * @usage Lay out a form's buttons in a fixed order: danger on the left, then secondary, then primary on the right.
  * @tier pattern
  * @figma https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2075-87
  */

package/dist/types/src/app/components/form.d.ts

@@ -34,6 +34,7 @@ import * as React from 'react';
 export type FormProps = React.FormHTMLAttributes<HTMLFormElement>;
 /**
  * Styled `<form>` with consistent vertical field rhythm.
+ * @usage Wrap form fields so they stack with even spacing.
  *
  * Tagged per-export: FormField and FormFieldShell share this module and have no
  * Figma node, so a file-level @figma would claim this one for all three.

package/dist/types/src/app/components/grid.d.ts

@@ -2,7 +2,7 @@
  * Grid — responsive grid composition primitive.
  * @category Layout
  * @tier primitive
- * @usage Lay out content in responsive columns with token-governed gaps, or align nested content with subgrid.
+ * @usage Lay out content in columns that adapt to the screen width, or line up nested content with subgrid.
  * @whenNot A single row or column, or styling a surface.
  * @useInstead Stack a single row or column
  * @useInstead Box one-off layout that no named primitive covers

package/dist/types/src/app/components/icon.d.ts

@@ -3,7 +3,7 @@
  * @category Display
  * @tier primitive
  * @figma https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=27-2
- * @usage Draw a Lucide glyph at a size and colour from the design tokens.
+ * @usage Show a Lucide icon at a set size and color.
  * @whenNot A control someone can activate, or a picture that carries content.
  * @useInstead Button a clickable control, with iconOnly for an icon-only one
  * @useInstead Avatar a picture of a person or entity

package/dist/types/src/app/components/metric-tiles.d.ts

@@ -1,6 +1,7 @@
 /**
  * MetricTiles - the default row of headline numbers on a screen.
  * @category Display
+ * @usage Show a row of key numbers, one tile each.
  * @tier pattern
  */
 import * as React from 'react';
@@ -22,6 +23,7 @@ export interface MetricTileProps extends Omit<React.HTMLAttributes<HTMLDivElemen
  * surface at one fixed min-height. Wraps `Card.Metric` (the sibling with the
  * eyebrow / h2 / caption scale) and adds the surface and the fixed height, so a
  * tile needs no enclosing `Card`.
+ * @usage Show one key number with its label, inside a MetricTiles row.
  * @figma https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2075-114
  */
 export declare const MetricTile: React.ForwardRefExoticComponent<MetricTileProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types/src/app/components/page-header.d.ts

@@ -1,6 +1,7 @@
 /**
  * PageHeader - the one header every screen opens with.
  * @category Layout
+ * @usage Open a screen with its title, plus optional breadcrumb, status and actions.
  * @tier pattern
  */
 import * as React from 'react';

package/dist/types/src/app/components/page.d.ts

@@ -1,6 +1,7 @@
 /**
  * Page — standard page shell.
  * @category Layout
+ * @usage Wrap a screen in the standard width and padding.
  * @tier primitive
  *
  * Wraps page content in Container (width constraint) and applies the

package/dist/types/src/app/components/reveal.d.ts

@@ -1,6 +1,7 @@
 /**
  * Reveal — reveal-on-scroll primitive via CSS scroll-driven animation.
  * @category Motion
+ * @usage Fade content in as it scrolls into view.
  * @tier primitive
  * @ai-intent Fades/slides/scales content in as it enters the viewport, driven
  * purely by scroll position (`animation-timeline: view()`) — no JS, no deps, no

package/dist/types/src/app/components/stack.d.ts

@@ -2,7 +2,7 @@
  * Stack — one-dimensional layout primitive.
  * @category Layout
  * @tier primitive
- * @usage Space a row or column of content with token gaps and simple flex alignment.
+ * @usage Space items in a row or column with even gaps.
  * @whenNot Multi-column layout, or giving content a background or padding.
  * @useInstead Grid multi-column layout
  * @useInstead Surface content that needs a background or padding

package/dist/types/src/app/components/tabs.d.ts

@@ -15,7 +15,9 @@
  * Overflow:
  *   TabsList is horizontally scrollable (`overflow-x-auto whitespace-nowrap`)
  *   for cases like /ops/atlas with 8 tabs at narrow viewports. Scrollbar
- *   chrome is hidden cross-browser (-webkit / firefox / IE).
+ *   chrome is hidden cross-browser (-webkit / firefox / IE). The trigger's
+ *   focus ring is `ring-inset` because `overflow-x-auto` clips anything drawn
+ *   outside the list box (an outer ring was cut on the first/last tab).
  *
  * @category Navigation
  * @tier primitive

package/dist/types/src/app/context/hds-theme.d.ts

@@ -16,7 +16,7 @@
  *   theme    data-theme                "dark" (light = unset)          light
  *   density  data-density              "compact" (comfortable = unset) comfortable
  *   brand    data-brand + data-tenant  overlay slug (e.g. "acme")      base
- *   font     --hds-font-family(-mono)  any CSS font-family value       Satoshi / Geist Mono
+ *   font     --hds-font-family(-mono)  any CSS font-family value       Satoshi / IBM Plex Mono
  *
  * This provider is a thin, typed convenience that renders a `data-hds` scope
  * wrapper carrying those attributes — it does NOT own state, storage, or a

package/dist/types/src/app/design-system/generated-token-refs.d.ts

@@ -55,6 +55,19 @@ export declare const tokenRefs: {
                 readonly "700": "var(--primitive-color-green-700)";
                 readonly "950": "var(--primitive-color-green-950)";
             };
+            readonly apple: {
+                readonly "50": "var(--primitive-color-apple-50)";
+                readonly "100": "var(--primitive-color-apple-100)";
+                readonly "200": "var(--primitive-color-apple-200)";
+                readonly "300": "var(--primitive-color-apple-300)";
+                readonly "400": "var(--primitive-color-apple-400)";
+                readonly "500": "var(--primitive-color-apple-500)";
+                readonly "600": "var(--primitive-color-apple-600)";
+                readonly "700": "var(--primitive-color-apple-700)";
+                readonly "800": "var(--primitive-color-apple-800)";
+                readonly "900": "var(--primitive-color-apple-900)";
+                readonly "950": "var(--primitive-color-apple-950)";
+            };
             readonly violet: {
                 readonly "50": "var(--primitive-color-violet-50)";
                 readonly "400": "var(--primitive-color-violet-400)";

package/dist/types/src/app/design-system/generated-token-values.d.ts

@@ -56,6 +56,19 @@ export declare const tokenValues: {
                 readonly "700": "#047857";
                 readonly "950": "#022c22";
             };
+            readonly apple: {
+                readonly "50": "#f2faeb";
+                readonly "100": "#e2f3cf";
+                readonly "200": "#c7e7a4";
+                readonly "300": "#a6d873";
+                readonly "400": "#85c84c";
+                readonly "500": "#66b239";
+                readonly "600": "#54922d";
+                readonly "700": "#416f20";
+                readonly "800": "#34571b";
+                readonly "900": "#2b4518";
+                readonly "950": "#16250c";
+            };
             readonly violet: {
                 readonly "50": "#f5f3ff";
                 readonly "400": "#a78bfa";
@@ -136,7 +149,7 @@ export declare const tokenValues: {
             readonly family: {
                 readonly primary: readonly ["Satoshi", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"];
                 readonly display: readonly ["Satoshi", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"];
-                readonly mono: readonly ["Geist Mono", "Courier New", "monospace"];
+                readonly mono: readonly ["IBM Plex Mono", "Courier New", "monospace"];
             };
             readonly size: {
                 readonly xs: "12px";

package/dist/types/src/app/hooks/useInteractionState.d.ts

@@ -6,7 +6,13 @@ export interface InteractionHandlers {
     onPointerDown: () => void;
     onPointerUp: () => void;
     onPointerCancel: () => void;
-    onFocus: () => void;
+    /**
+     * Pass the focused element (`e.currentTarget`) so only keyboard-modality focus
+     * (`:focus-visible`) counts. Called with no argument it counts unconditionally.
+     */
+    onFocus: (target?: Element | null) => void;
+    /** Re-checks `:focus-visible` once a key is pressed on an already-focused element. */
+    onKeyDown: (target?: Element | null) => void;
     onBlur: () => void;
 }
 export interface InteractionState {

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

@@ -204,6 +204,53 @@ export declare const tokens: {
                 };
                 $description: string;
             };
+            apple: {
+                "50": {
+                    $value: string;
+                    $description: string;
+                };
+                "100": {
+                    $value: string;
+                    $description: string;
+                };
+                "200": {
+                    $value: string;
+                    $description: string;
+                };
+                "300": {
+                    $value: string;
+                    $description: string;
+                };
+                "400": {
+                    $value: string;
+                    $description: string;
+                };
+                "500": {
+                    $value: string;
+                    $description: string;
+                };
+                "600": {
+                    $value: string;
+                    $description: string;
+                };
+                "700": {
+                    $value: string;
+                    $description: string;
+                };
+                "800": {
+                    $value: string;
+                    $description: string;
+                };
+                "900": {
+                    $value: string;
+                    $description: string;
+                };
+                "950": {
+                    $value: string;
+                    $description: string;
+                };
+                $description: string;
+            };
             violet: {
                 "50": {
                     $value: string;

package/dist/variables.css

@@ -48,6 +48,17 @@
   --primitive-color-green-400: #34d399;
   --primitive-color-green-700: #047857;
   --primitive-color-green-950: #022c22;
+  --primitive-color-apple-50: #f2faeb;
+  --primitive-color-apple-100: #e2f3cf;
+  --primitive-color-apple-200: #c7e7a4;
+  --primitive-color-apple-300: #a6d873;
+  --primitive-color-apple-400: #85c84c;
+  --primitive-color-apple-500: #66b239;
+  --primitive-color-apple-600: #54922d;
+  --primitive-color-apple-700: #416f20;
+  --primitive-color-apple-800: #34571b;
+  --primitive-color-apple-900: #2b4518;
+  --primitive-color-apple-950: #16250c;
   --primitive-color-violet-50: #f5f3ff;
   --primitive-color-violet-400: #a78bfa;
   --primitive-color-violet-700: #6d28d9;
@@ -107,7 +118,7 @@
   --primitive-radius-full: 9999px;
   --primitive-typography-family-primary: Satoshi, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
   --primitive-typography-family-display: Satoshi, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-  --primitive-typography-family-mono: "Geist Mono", "Courier New", monospace;
+  --primitive-typography-family-mono: "IBM Plex Mono", "Courier New", monospace;
   --primitive-typography-size-xs: 12px;
   --primitive-typography-size-sm: 14px;
   --primitive-typography-size-base: 16px;
@@ -197,8 +208,8 @@
   --semantic-color-surface-overlay: var(--primitive-color-neutral-100);
   --semantic-color-surface-scrim: var(--primitive-color-neutral-900);
   --semantic-color-surface-inverse: var(--primitive-color-neutral-black);
-  --semantic-color-surface-accent: var(--primitive-color-neutral-900);
-  --semantic-color-surface-accentSubtle: var(--primitive-color-neutral-100);
+  --semantic-color-surface-accent: var(--primitive-color-apple-500);
+  --semantic-color-surface-accentSubtle: var(--primitive-color-apple-50);
   --semantic-color-surface-hover: var(--primitive-color-neutral-100);
   --semantic-color-surface-pressed: var(--primitive-color-neutral-50);
   --semantic-color-surface-selected: var(--primitive-color-neutral-200);
@@ -208,8 +219,8 @@
   --semantic-color-content-secondary: var(--primitive-color-neutral-600);
   --semantic-color-content-disabled: var(--primitive-color-neutral-300);
   --semantic-color-content-inverse: var(--primitive-color-neutral-100);
-  --semantic-color-content-accent: var(--primitive-color-neutral-900);
-  --semantic-color-content-onAccent: var(--primitive-color-neutral-white);
+  --semantic-color-content-accent: var(--primitive-color-apple-700);
+  --semantic-color-content-onAccent: var(--primitive-color-neutral-900);
   --semantic-color-content-success: var(--primitive-color-green-700);
   --semantic-color-content-warning: var(--primitive-color-amber-800);
   --semantic-color-content-danger: var(--primitive-color-red-700);
@@ -218,7 +229,7 @@
   --semantic-color-border-subdued: var(--primitive-color-neutral-200);
   --semantic-color-border-subtle: var(--primitive-color-neutral-100);
   --semantic-color-border-strong: var(--primitive-color-neutral-300);
-  --semantic-color-border-accent: var(--primitive-color-neutral-900);
+  --semantic-color-border-accent: var(--primitive-color-apple-600);
   --semantic-color-border-success: var(--primitive-color-green-400);
   --semantic-color-border-warning: var(--primitive-color-amber-400);
   --semantic-color-feedback-error: var(--primitive-color-red-700);
@@ -335,14 +346,14 @@
   --semantic-docs-space-section: var(--primitive-space-12);
   --semantic-docs-space-paragraph: var(--primitive-space-6);
   --semantic-docs-space-inline: var(--primitive-space-2);
-  --semantic-accent-rest: var(--primitive-color-neutral-900);
-  --semantic-accent-hover: var(--primitive-color-neutral-800);
-  --semantic-accent-pressed: var(--primitive-color-neutral-950);
+  --semantic-accent-rest: var(--primitive-color-apple-500);
+  --semantic-accent-hover: var(--primitive-color-apple-600);
+  --semantic-accent-pressed: var(--primitive-color-apple-700);
   --semantic-accent-inactive: var(--primitive-color-neutral-400);
   --semantic-accent-disabled: var(--primitive-color-neutral-300);
-  --semantic-accent-content: var(--primitive-color-neutral-900);
-  --semantic-accent-contentHover: var(--primitive-color-neutral-700);
-  --semantic-accent-subtle: var(--primitive-color-neutral-100);
+  --semantic-accent-content: var(--primitive-color-apple-700);
+  --semantic-accent-contentHover: var(--primitive-color-apple-800);
+  --semantic-accent-subtle: var(--primitive-color-apple-50);
   --semantic-radius-action: var(--primitive-radius-8);
   --semantic-radius-control: var(--primitive-radius-4);
   --semantic-borderWidth-default: var(--primitive-borderWidth-xs);
@@ -493,8 +504,8 @@
   --semantic-color-surface-overlay: var(--primitive-color-neutral-850);
   --semantic-color-surface-scrim: var(--primitive-color-neutral-black);
   --semantic-color-surface-inverse: var(--primitive-color-neutral-white);
-  --semantic-color-surface-accent: var(--primitive-color-neutral-100);
-  --semantic-color-surface-accentSubtle: var(--primitive-color-neutral-900);
+  --semantic-color-surface-accent: var(--primitive-color-apple-400);
+  --semantic-color-surface-accentSubtle: var(--primitive-color-apple-900);
   --semantic-color-surface-hover: var(--primitive-color-neutral-900);
   --semantic-color-surface-pressed: var(--primitive-color-neutral-950);
   --semantic-color-surface-selected: var(--primitive-color-neutral-800);
@@ -504,7 +515,7 @@
   --semantic-color-content-secondary: var(--primitive-color-neutral-400);
   --semantic-color-content-disabled: var(--primitive-color-neutral-600);
   --semantic-color-content-inverse: var(--primitive-color-neutral-900);
-  --semantic-color-content-accent: var(--primitive-color-neutral-100);
+  --semantic-color-content-accent: var(--primitive-color-apple-400);
   --semantic-color-content-onAccent: var(--primitive-color-neutral-900);
   --semantic-color-content-success: var(--primitive-color-green-400);
   --semantic-color-content-warning: var(--primitive-color-amber-400);
@@ -514,7 +525,7 @@
   --semantic-color-border-subdued: var(--primitive-color-neutral-800);
   --semantic-color-border-subtle: var(--primitive-color-neutral-850);
   --semantic-color-border-strong: var(--primitive-color-neutral-600);
-  --semantic-color-border-accent: var(--primitive-color-neutral-100);
+  --semantic-color-border-accent: var(--primitive-color-apple-400);
   --semantic-color-border-success: var(--primitive-color-green-400);
   --semantic-color-border-warning: var(--primitive-color-amber-400);
   --semantic-color-feedback-error: var(--primitive-color-red-400);
@@ -528,14 +539,14 @@
   --semantic-color-feedback-bg-info: var(--primitive-color-blue-900);
   --semantic-color-feedback-bg-inProgress: var(--primitive-color-violet-950);
   --semantic-color-state-pressed-overlay: var(--primitive-color-neutral-white);
-  --semantic-accent-rest: var(--primitive-color-neutral-100);
-  --semantic-accent-hover: var(--primitive-color-neutral-200);
-  --semantic-accent-pressed: var(--primitive-color-neutral-300);
+  --semantic-accent-rest: var(--primitive-color-apple-400);
+  --semantic-accent-hover: var(--primitive-color-apple-500);
+  --semantic-accent-pressed: var(--primitive-color-apple-600);
   --semantic-accent-inactive: var(--primitive-color-neutral-600);
   --semantic-accent-disabled: var(--primitive-color-neutral-700);
-  --semantic-accent-content: var(--primitive-color-neutral-100);
-  --semantic-accent-contentHover: var(--primitive-color-neutral-300);
-  --semantic-accent-subtle: var(--primitive-color-neutral-800);
+  --semantic-accent-content: var(--primitive-color-apple-400);
+  --semantic-accent-contentHover: var(--primitive-color-apple-300);
+  --semantic-accent-subtle: var(--primitive-color-apple-900);
   --component-badge-bg: var(--semantic-color-feedback-bg-info);
   --component-button-primary-textDisabled: var(--semantic-color-content-disabled);
   --semantic-elevation-flat-surface: var(--semantic-color-surface-page);

package/docs/CONSUMING.md

@@ -70,7 +70,7 @@ All three:
 ### Brand fonts (optional)
 
 ```ts
-import '@hirobius/design-system/fonts.css'; // Satoshi 400/500/700 + Geist Mono 400
+import '@hirobius/design-system/fonts.css'; // Satoshi 400/500/700 + IBM Plex Mono 400
 ```
 
 `fonts.css` declares the four `@font-face` blocks with `font-display: swap`. Its
@@ -229,7 +229,7 @@ export function Example() {
 | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@hirobius/design-system`               | The 43-component core set ([README → What belongs in the system](../README.md#what-belongs-in-the-system)), the rest of the allow-list, and the router seam (`HdsRouterProvider`, `useHdsRouter`); the `pattern` tier is in `/patterns` |
 | `@hirobius/design-system/styles.css`    | Components + utilities + tokens, NO global reset (host-safe; recommended for embedding)                                                                                                                                                 |
-| `@hirobius/design-system/fonts.css`     | Optional brand fonts: Satoshi 400/500/700 + Geist Mono 400 (`@font-face`, relative woff2 URLs)                                                                                                                                          |
+| `@hirobius/design-system/fonts.css`     | Optional brand fonts: Satoshi 400/500/700 + IBM Plex Mono 400 (`@font-face`, relative woff2 URLs)                                                                                                                                       |
 | `@hirobius/design-system/tokens.css`    | The complete stylesheet — styles.css PLUS a global Tailwind-preflight reset                                                                                                                                                             |
 | `@hirobius/design-system/variables.css` | Design tokens as CSS custom properties ONLY — no reset/preflight (host-safe)                                                                                                                                                            |
 | `@hirobius/design-system/tokens`        | Design-token values as typed TS                                                                                                                                                                                                         |