@hirobius/design-system 0.15.0 → 0.16.0

package/dist/tokens.js

@@ -125,7 +125,6 @@ const a = {
         mono: ["Geist Mono", "Courier New", "monospace"]
       },
       size: {
-        "2xs": "10px",
         xs: "13px",
         sm: "15px",
         base: "17px",
@@ -138,10 +137,8 @@ const a = {
         "6xl": "80px"
       },
       weight: {
-        light: "300",
         regular: "400",
         medium: "500",
-        semibold: "600",
         bold: "700"
       },
       lineHeight: {
@@ -153,11 +150,8 @@ const a = {
         relaxed: "1.625"
       },
       letterSpacing: {
-        tighter: "-0.02em",
         tight: "-0.01em",
         normal: "0em",
-        wide: "0.01em",
-        wider: "0.02em",
         caps: "0.06em"
       }
     },
@@ -197,10 +191,12 @@ const a = {
       80: "80px",
       96: "96px",
       interactive: {
-        min: "44px"
+        min: "44px",
+        minCompact: "24px"
       },
       width: {
         96: "96px",
+        280: "280px",
         760: "760px",
         1200: "1200px",
         "50ch": "50ch"
@@ -399,8 +395,14 @@ const o = "var(--primitive-typography-family-primary)", n = "var(--primitive-typ
     brandRGB: "30,46,253",
     white: "var(--primitive-color-neutral-white)",
     surface: {
-      page: { dark: "var(--semantic-color-surface-page)", light: "var(--semantic-color-surface-page)" },
-      raised: { dark: "var(--semantic-color-surface-raised)", light: "var(--semantic-color-surface-raised)" }
+      page: {
+        dark: "var(--semantic-color-surface-page)",
+        light: "var(--semantic-color-surface-page)"
+      },
+      raised: {
+        dark: "var(--semantic-color-surface-raised)",
+        light: "var(--semantic-color-surface-raised)"
+      }
     },
     blue: {
       50: "var(--primitive-color-blue-50)",
@@ -416,17 +418,28 @@ const o = "var(--primitive-typography-family-primary)", n = "var(--primitive-typ
       900: "var(--primitive-color-blue-900)"
     },
     feedback: {
-      success: { dark: a.primitive.color.green[400], light: a.primitive.color.green[700] },
-      warning: { dark: a.primitive.color.amber[400], light: a.primitive.color.amber[800] },
-      error: { dark: a.primitive.color.red[400], light: a.primitive.color.red[700] },
-      info: { dark: a.primitive.color.blue[300], light: a.primitive.color.blue[500] }
+      success: {
+        dark: a.primitive.color.green[400],
+        light: a.primitive.color.green[700]
+      },
+      warning: {
+        dark: a.primitive.color.amber[400],
+        light: a.primitive.color.amber[800]
+      },
+      error: {
+        dark: a.primitive.color.red[400],
+        light: a.primitive.color.red[700]
+      },
+      info: {
+        dark: a.primitive.color.blue[300],
+        light: a.primitive.color.blue[500]
+      }
     }
   },
   // ── Typography ───────────────────────────────────────────────────────────────
   fontFamily: o,
   monoFamily: n,
   fontSize: {
-    "2xs": "var(--primitive-typography-size-2xs)",
     xs: "var(--primitive-typography-size-xs)",
     sm: "var(--primitive-typography-size-sm)",
     base: "var(--primitive-typography-size-base)",
@@ -440,7 +453,6 @@ const o = "var(--primitive-typography-family-primary)", n = "var(--primitive-typ
   fontWeight: {
     regular: "var(--primitive-typography-weight-regular)",
     medium: "var(--primitive-typography-weight-medium)",
-    semibold: "var(--primitive-typography-weight-semibold)",
     bold: "var(--primitive-typography-weight-bold)"
   },
   lineHeight: {
@@ -452,11 +464,8 @@ const o = "var(--primitive-typography-family-primary)", n = "var(--primitive-typ
     relaxed: "var(--primitive-typography-lineHeight-relaxed)"
   },
   letterSpacing: {
-    tighter: "var(--primitive-typography-letterSpacing-tighter)",
     tight: "var(--primitive-typography-letterSpacing-tight)",
-    normal: "var(--primitive-typography-letterSpacing-normal)",
-    wide: "var(--primitive-typography-letterSpacing-wide)",
-    wider: "var(--primitive-typography-letterSpacing-wider)"
+    normal: "var(--primitive-typography-letterSpacing-normal)"
   },
   semantic: {
     color: {
@@ -547,12 +556,21 @@ const o = "var(--primitive-typography-family-primary)", n = "var(--primitive-typ
     labelTechnical: i.semantic.typography.mono
   },
   // ── Icons ────────────────────────────────────────────────────────────────────
+  // Sized off primitive.size, NOT the type ramp. An icon is geometry: it sits
+  // beside text, it does not scale with it. These were pointed at
+  // typography.size.base/lg/xl, which happened to read 16/20/24 — so the
+  // coupling was invisible until the ramp moved. Rescaling the ramp (hds#283)
+  // would have silently shrunk every medium icon 20→18 and every large 24→20,
+  // for no typographic reason, and no gate would have said a word.
+  //
+  // component.button.size.*.iconSize already referenced primitive.size; this
+  // brings the global bridge in line with what the component tokens do.
   iconSize: {
-    small: "var(--primitive-typography-size-base)",
+    small: "var(--primitive-size-16)",
     // 16px — default icon size
-    medium: "var(--primitive-typography-size-lg)",
+    medium: "var(--primitive-size-20)",
     // 20px — prominent icons
-    large: "var(--primitive-typography-size-xl)"
+    large: "var(--primitive-size-24)"
     // 24px — hero / large empty states
   },
   // ── Density-aware spacing ────────────────────────────────────────────────────

package/dist/types/src/app/components/cinematic-link.d.ts

@@ -8,5 +8,11 @@ export interface CinematicLinkProps extends Omit<React.AnchorHTMLAttributes<HTML
     href: string;
     children: string;
 }
-/** @public */
+/**
+ * CinematicLink - cinematic editorial link treatment for portfolio surfaces.
+ *
+ * @public
+ * @deprecated CinematicLink is an HDS docs/lab internal (editorial link treatment for portfolio/case-study specimen surfaces), not a consumer-facing HDS surface. It will be retiered to `utility` (dropped from the published barrel) at the named major.
+ * @removeIn 1.0.0
+ */
 export declare function CinematicLink({ href, children, style, className, ...rest }: CinematicLinkProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/src/app/components/component-instance-matrix.d.ts

@@ -6,7 +6,13 @@
  * @doc-exempt: specimen matrix helper used by docs pages, not a consumer-facing HDS surface.
  */
 import React from 'react';
-/** @public */
+/**
+ * ComponentInstanceMatrix — responsive specimen matrix for variant and state parity.
+ *
+ * @public
+ * @deprecated ComponentInstanceMatrix is an HDS docs/lab internal (specimen matrix helper for the component doc pages), not a consumer-facing HDS surface. It will be retiered to `utility` (dropped from the published barrel) at the named major.
+ * @removeIn 1.0.0
+ */
 export declare function ComponentInstanceMatrix({ componentName, dimensionX, dimensionY, title, isMobile: _isMobile, rowLabelWidth: _rowLabelWidth, rowLabelTone, freezeRowState, renderInstance, }: {
     componentName: string;
     dimensionX: string;

package/dist/types/src/app/components/foundation-swatch.d.ts

@@ -35,5 +35,11 @@ export type FoundationSwatchProps = {
     /** Explicit color value (hex or CSS var name) to pin the token chip's swatch square, overriding auto-resolution from tokenPath. */
     swatchVar?: string;
 };
+/**
+ * FoundationSwatch - governed foundation specimen for color and semantic role previews.
+ *
+ * @deprecated FoundationSwatch is an HDS docs/lab internal (foundation specimen preview for the token/foundation doc pages), not a consumer-facing HDS surface. It will be retiered to `utility` (dropped from the published barrel) at the named major.
+ * @removeIn 1.0.0
+ */
 export declare function FoundationSwatch({ label, hidePreviewLabel, tokenPath, tokenDisplayPreset, previewPosition, background, value, details, foreground, specimen, note, bordered, swatchVar, }: FoundationSwatchProps): import("react/jsx-runtime").JSX.Element;
 export {};

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

@@ -0,0 +1,29 @@
+/**
+ * HdsSelect — dropdown selector built on Radix Select.
+ * @category Inputs
+ * @tier primitive
+ * @figma https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-49
+ */
+/**
+ * HdsSelect — dropdown selector built on Radix Select (ADR-001 Radix convention).
+ * Radix owns the listbox a11y contract: managed focus + active-descendant, typeahead,
+ * full keyboard (Home/End/PageUp-Down/wrap), Popper collision/flip positioning, and
+ * dismissal. The HDS surface is styled with the token-backed Tailwind idiom used by
+ * tabs.tsx / command-palette.tsx; `ref` targets the trigger button.
+ */
+export interface SelectProps {
+    /** Select label rendered above the control. */
+    label: string;
+    /** Controls whether the label is rendered. */
+    showLabel?: boolean;
+    /** Select options displayed in the dropdown. */
+    options: {
+        value: string;
+        label: string;
+    }[];
+    /** Currently selected value. */
+    value: string;
+    /** Called when the user picks a different option. */
+    onChange: (v: string) => void;
+}
+export declare const HdsSelect: import("react").ForwardRefExoticComponent<SelectProps & import("react").RefAttributes<HTMLButtonElement>>;

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

@@ -10,4 +10,10 @@ export interface SketchProps {
     children: ReactNode;
     controls?: ReactNode;
 }
+/**
+ * Sketch — shared shell for generative canvases and WebGL sketches.
+ *
+ * @deprecated Sketch is an HDS docs/lab internal (shell for generative canvas/WebGL specimen pages), not a consumer-facing HDS surface. It will be retiered to `utility` (dropped from the published barrel) at the named major.
+ * @removeIn 1.0.0
+ */
 export declare function Sketch({ title, children, controls }: SketchProps): import("react/jsx-runtime").JSX.Element;

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

@@ -78,7 +78,13 @@ export type TokenProps = TokenNodeSurfaceProps | TokenDiagramProps;
  * @removeIn 1.0.0) that now resolves to the same node treatment.
  * Node content can use a left-side slot for swatches or other compact previews.
  */
-/** @public */
+/**
+ * Token - reflective token specimen for unified node-based token views. The `variant` axis (node | diagram — diagram is a deprecated alias that resolves to the same node treatment) plus the `selected` / `fullWidth` / `asButton` / `nowrap` / `sourceNode` states used to be a Token.module.css `[data-*]` attribute stylesheet, with a duplicate `isSelected` branch re-painted inline on top of it. Both now live as one `cva` variant set — same `--semantic-*`/`--component-*`/`--primitive-*` custom properties, same pixels, no CSS module.
+ *
+ * @public
+ * @deprecated Token is an HDS docs/lab internal (reflective token specimen for the token/foundation doc pages), not a consumer-facing HDS surface. It will be retiered to `utility` (dropped from the published barrel) at the named major.
+ * @removeIn 1.0.0
+ */
 export declare function Token(props: TokenProps): import("react/jsx-runtime").JSX.Element;
 /** @internal — CVA variant helpers; compose via Token props instead. */
 export { tokenShellVariants, tokenNodeInlineVariants, tokenLabelVariants };

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

@@ -138,7 +138,6 @@ export declare const tokenRefs: {
                 readonly mono: "var(--primitive-typography-family-mono)";
             };
             readonly size: {
-                readonly "2xs": "var(--primitive-typography-size-2xs)";
                 readonly xs: "var(--primitive-typography-size-xs)";
                 readonly sm: "var(--primitive-typography-size-sm)";
                 readonly base: "var(--primitive-typography-size-base)";
@@ -151,10 +150,8 @@ export declare const tokenRefs: {
                 readonly "6xl": "var(--primitive-typography-size-6xl)";
             };
             readonly weight: {
-                readonly light: "var(--primitive-typography-weight-light)";
                 readonly regular: "var(--primitive-typography-weight-regular)";
                 readonly medium: "var(--primitive-typography-weight-medium)";
-                readonly semibold: "var(--primitive-typography-weight-semibold)";
                 readonly bold: "var(--primitive-typography-weight-bold)";
             };
             readonly lineHeight: {
@@ -166,11 +163,8 @@ export declare const tokenRefs: {
                 readonly relaxed: "var(--primitive-typography-lineHeight-relaxed)";
             };
             readonly letterSpacing: {
-                readonly tighter: "var(--primitive-typography-letterSpacing-tighter)";
                 readonly tight: "var(--primitive-typography-letterSpacing-tight)";
                 readonly normal: "var(--primitive-typography-letterSpacing-normal)";
-                readonly wide: "var(--primitive-typography-letterSpacing-wide)";
-                readonly wider: "var(--primitive-typography-letterSpacing-wider)";
                 readonly caps: "var(--primitive-typography-letterSpacing-caps)";
             };
         };
@@ -211,9 +205,11 @@ export declare const tokenRefs: {
             readonly "96": "var(--primitive-size-96)";
             readonly interactive: {
                 readonly min: "var(--primitive-size-interactive-min)";
+                readonly minCompact: "var(--primitive-size-interactive-minCompact)";
             };
             readonly width: {
                 readonly "96": "var(--primitive-size-width-96)";
+                readonly "280": "var(--primitive-size-width-280)";
                 readonly "760": "var(--primitive-size-width-760)";
                 readonly "1200": "var(--primitive-size-width-1200)";
                 readonly "50ch": "var(--primitive-size-width-50ch)";
@@ -335,6 +331,7 @@ export declare const tokenRefs: {
                 readonly gap: "var(--semantic-space-sidebar-gap)";
                 readonly sectionGap: "var(--semantic-space-sidebar-sectionGap)";
                 readonly railPadding: "var(--semantic-space-sidebar-railPadding)";
+                readonly railWidth: "var(--semantic-space-sidebar-railWidth)";
             };
         };
         readonly layout: {

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

@@ -139,7 +139,6 @@ export declare const tokenValues: {
                 readonly mono: readonly ["Geist Mono", "Courier New", "monospace"];
             };
             readonly size: {
-                readonly "2xs": "10px";
                 readonly xs: "13px";
                 readonly sm: "15px";
                 readonly base: "17px";
@@ -152,10 +151,8 @@ export declare const tokenValues: {
                 readonly "6xl": "80px";
             };
             readonly weight: {
-                readonly light: "300";
                 readonly regular: "400";
                 readonly medium: "500";
-                readonly semibold: "600";
                 readonly bold: "700";
             };
             readonly lineHeight: {
@@ -167,11 +164,8 @@ export declare const tokenValues: {
                 readonly relaxed: "1.625";
             };
             readonly letterSpacing: {
-                readonly tighter: "-0.02em";
                 readonly tight: "-0.01em";
                 readonly normal: "0em";
-                readonly wide: "0.01em";
-                readonly wider: "0.02em";
                 readonly caps: "0.06em";
             };
         };
@@ -212,9 +206,11 @@ export declare const tokenValues: {
             readonly "96": "96px";
             readonly interactive: {
                 readonly min: "44px";
+                readonly minCompact: "24px";
             };
             readonly width: {
                 readonly "96": "96px";
+                readonly "280": "280px";
                 readonly "760": "760px";
                 readonly "1200": "1200px";
                 readonly "50ch": "50ch";

package/dist/types/src/app/design-system/tokens.d.ts

@@ -67,7 +67,6 @@ declare const hds: {
     fontFamily: string;
     monoFamily: string;
     fontSize: {
-        '2xs': string;
         xs: string;
         sm: string;
         base: string;
@@ -81,7 +80,6 @@ declare const hds: {
     fontWeight: {
         regular: string;
         medium: string;
-        semibold: string;
         bold: string;
     };
     lineHeight: {
@@ -93,11 +91,8 @@ declare const hds: {
         relaxed: string;
     };
     letterSpacing: {
-        tighter: string;
         tight: string;
         normal: string;
-        wide: string;
-        wider: string;
     };
     semantic: {
         color: {

package/dist/types/src/app/layouts/DocLayout.d.ts

@@ -1,6 +1,4 @@
 import { type ReactNode } from 'react';
-export declare const DOC_LAYOUT_STICKY_OFFSET: string;
-export declare const DOC_LAYOUT_STICKY_VIEWPORT_HEIGHT: string;
 declare const DOC_LAYOUT_CONTENT_WIDTHS: {
     readonly content: "var(--semantic-layout-width-content)";
     readonly max: "var(--semantic-layout-width-max)";

package/dist/types/src/app/layouts/HdsDocsShell.d.ts

@@ -0,0 +1,72 @@
+/**
+ * HdsDocsShell — three-region docs shell (left nav rail, content, right TOC
+ * rail), driven by grid columns that default to 0 and are set per breakpoint.
+ * @category Layout
+ * @tier pattern
+ * @public
+ *
+ * hds#280 slice: this is the SHELL MECHANICS ONLY — the smallest shippable
+ * piece of the docs-shell epic. It ships:
+ *
+ *   - A 3-column grid (`leftRail | content | rightRail`), both rail columns
+ *     defaulting to `0px` and set to `semantic.space.sidebar.railWidth`
+ *     (hds#280 token, our own 280px — not HeroUI's 268px) per breakpoint via
+ *     Tailwind's arbitrary-property + responsive-variant syntax, the same
+ *     technique Fumadocs/HeroUI uses. `md768:` brings in the left rail,
+ *     `xl1280:` brings in the right rail — matching the three-stage table in
+ *     hds#280.
+ *   - Each rail is `position: sticky` and scrolls independently of content
+ *     and of the other rail, clipped to the viewport minus `topOffset`.
+ *   - `topOffset` composes (it is one CSS length a caller supplies, e.g. its
+ *     own sticky header's height token) rather than a hardcoded pixel value —
+ *     the first stage of the row-cascade pattern hds#280 asks for. A second
+ *     region (a tabs row, hds#280's PR-comment addendum) would extend this by
+ *     adding its own height into the same `calc()` chain, not by hardcoding a
+ *     second offset.
+ *
+ * Deliberately NOT in this slice (tracked as proposed follow-up issues, not
+ * filed — see the PR/commit this ships in):
+ *   - Below the TOC breakpoint, `rightRail` is omitted from the grid rather
+ *     than becoming a reachable popover. The DoD explicitly wants a popover,
+ *     not "merely hidden" — that is real, separate UI work (a sticky
+ *     current-section breadcrumb bar), not shell mechanics.
+ *   - Left-rail collapsible groups (chevron, active-section pill) and
+ *     right-rail active-anchor styling (vertical rule, filled pill) are
+ *     content the caller supplies via `leftRail`/`rightRail` — this shell
+ *     does not build SideNav/Disclosure/NavItem composition for the caller.
+ *   - `check-rendered-geometry` verification at every breakpoint in the DoD's
+ *     table (needs a built Storybook + a live run, not exercised here).
+ *   - Named CSS `grid-template-areas` (the DoD's literal ask) — this ships a
+ *     3-column grid with DOM order instead, which is behaviorally identical
+ *     for a single linear row of regions and needs no separate stylesheet.
+ *     Areas earn their keep once a 4th region (a tabs row spanning full
+ *     width) is added — call out then, not before.
+ */
+import * as React from 'react';
+/** @public */
+export interface HdsDocsShellProps {
+    /** Left nav rail. Hidden below the `md768` breakpoint (grid column width 0). */
+    leftRail?: React.ReactNode;
+    /** Main content column. Always rendered, always fluid. */
+    children: React.ReactNode;
+    /**
+     * Right "on this page" rail. Hidden below the `xl1280` breakpoint (grid
+     * column width 0) — see the deferred-popover note above; it is REMOVED
+     * from the grid at that breakpoint, not merely visually hidden, so no
+     * hidden interactive content sits in the DOM unreachable.
+     */
+    rightRail?: React.ReactNode;
+    /**
+     * CSS length a caller supplies for a sticky header ABOVE this shell (e.g.
+     * TopNav's height token), so each rail's sticky offset and scrollable
+     * height compose against it instead of assuming the shell owns the whole
+     * viewport. Defaults to `'0px'`.
+     */
+    topOffset?: string;
+    /** Escape hatch: only for narrow layout adjustments that don't belong in the primitive API. */
+    className?: string;
+    /** Escape hatch: only for narrow layout adjustments that don't belong in the primitive API. */
+    style?: React.CSSProperties;
+}
+/** @public */
+export declare const HdsDocsShell: React.ForwardRefExoticComponent<HdsDocsShellProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types/src/app/layouts/HdsSystemDocLayout.d.ts

@@ -1,6 +1,13 @@
 import type { ReactNode } from 'react';
 import { type DocLayoutContentMaxWidth } from './DocLayout.js';
-/** @public */
+/**
+ * HdsSystemDocLayout — single centered content column for documentation pages.
+ * Thin wrapper around DocLayout: takes only `contentSlot` and `contentMaxWidth`,
+ * with no sidebar or nav region to pass one into. Not the three-column docs
+ * shell (left rail + content + right rail) — that is tracked as its own shell
+ * component (hds#280).
+ * @public
+ */
 export declare function HdsSystemDocLayout({ contentSlot, contentMaxWidth, }: {
     contentSlot: ReactNode;
     contentMaxWidth?: DocLayoutContentMaxWidth;

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

@@ -36,6 +36,7 @@ export * from './app/components/progress.js';
 export * from './app/components/skeleton.js';
 export * from './app/components/spinner.js';
 export * from './app/components/segmented-control.js';
+export * from './app/components/select.js';
 export * from './app/components/stack.js';
 export * from './app/components/surface.js';
 export * from './app/components/table.js';
@@ -108,6 +109,7 @@ export * from './app/components/toast.js';
 export * from './app/layouts/CaseStudyLayout.js';
 export * from './app/components/error-pattern.js';
 export * from './app/layouts/HdsSystemDocLayout.js';
+export * from './app/layouts/HdsDocsShell.js';
 export { default as hds } from './app/design-system/tokens.js';
 /** Raw DTCG design tokens (the contents of `hirobius.tokens.json`). */
 export declare const tokens: {
@@ -593,12 +595,6 @@ export declare const tokens: {
             };
             size: {
                 $type: string;
-                "2xs": {
-                    $value: {
-                        value: number;
-                        unit: string;
-                    };
-                };
                 xs: {
                     $value: {
                         value: number;
@@ -663,19 +659,12 @@ export declare const tokens: {
             };
             weight: {
                 $type: string;
-                light: {
-                    $value: number;
-                    $description: string;
-                };
                 regular: {
                     $value: number;
                 };
                 medium: {
                     $value: number;
                 };
-                semibold: {
-                    $value: number;
-                };
                 bold: {
                     $value: number;
                 };
@@ -705,12 +694,6 @@ export declare const tokens: {
             };
             letterSpacing: {
                 $type: string;
-                tighter: {
-                    $value: {
-                        value: number;
-                        unit: string;
-                    };
-                };
                 tight: {
                     $value: {
                         value: number;
@@ -723,18 +706,6 @@ export declare const tokens: {
                         unit: string;
                     };
                 };
-                wide: {
-                    $value: {
-                        value: number;
-                        unit: string;
-                    };
-                };
-                wider: {
-                    $value: {
-                        value: number;
-                        unit: string;
-                    };
-                };
                 caps: {
                     $value: {
                         value: number;
@@ -961,6 +932,14 @@ export declare const tokens: {
                     };
                     $description: string;
                 };
+                minCompact: {
+                    $type: string;
+                    $value: {
+                        value: number;
+                        unit: string;
+                    };
+                    $description: string;
+                };
             };
             width: {
                 "96": {
@@ -992,6 +971,14 @@ export declare const tokens: {
                         unit: string;
                     };
                 };
+                "280": {
+                    $type: string;
+                    $value: {
+                        value: number;
+                        unit: string;
+                    };
+                    $description: string;
+                };
             };
         };
         grid: {
@@ -1629,6 +1616,11 @@ export declare const tokens: {
                     $value: string;
                     $description: string;
                 };
+                railWidth: {
+                    $type: string;
+                    $value: string;
+                    $description: string;
+                };
             };
         };
         layout: {