@hirobius/design-system 0.8.1

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

@@ -0,0 +1,223 @@
+/**
+ * Generated by scripts/build-tokens.mjs — do not edit manually.
+ * Source: hirobius.tokens.json (W3C DTCG 2025.10)
+ * Regenerate: node scripts/build-tokens.mjs
+ *
+ * Raw primitive values as typed constants.
+ * Import in doc pages instead of hardcoding hex strings, font names, or OKLCH values.
+ *
+ * Usage:
+ *   import { tokenValues } from './generated-token-values';
+ *   tokenValues.primitive.color.blue['500']        // '#1e2fff'
+ *   tokenValues.primitive.typography.family.primary[0]   // 'Clash Grotesk'
+ *   tokenValues.primitive.color.blue['500']        // 'oklch(0.49 0.2903 266.54)'
+ */
+export declare const tokenValues: {
+    readonly primitive: {
+        readonly color: {
+            readonly neutral: {
+                readonly "50": "#fafafa";
+                readonly "100": "#f5f5f5";
+                readonly "200": "#e5e5e5";
+                readonly "300": "#d4d4d4";
+                readonly "400": "#a3a3a3";
+                readonly "500": "#737373";
+                readonly "600": "#525252";
+                readonly "700": "#404040";
+                readonly "800": "#262626";
+                readonly "850": "#1a1a1a";
+                readonly "900": "#111111";
+                readonly "950": "#0a0a0a";
+                readonly white: "#ffffff";
+                readonly black: "#000000";
+            };
+            readonly blue: {
+                readonly "50": "oklch(0.96 0.03 266.54)";
+                readonly "100": "oklch(0.92 0.04 266.54)";
+                readonly "200": "oklch(0.88 0.07 266.54)";
+                readonly "300": "oklch(0.70 0.2903 266.54)";
+                readonly "400": "oklch(0.65 0.2903 266.54)";
+                readonly "450": "oklch(0.56 0.29 266.60)";
+                readonly "500": "#1E2EFD";
+                readonly "600": "oklch(0.45 0.2903 266.54)";
+                readonly "700": "oklch(0.44 0.2903 266.54)";
+                readonly "800": "oklch(0.30 0.07 266.54)";
+                readonly "900": "oklch(0.22 0.05 266.54)";
+            };
+            readonly red: {
+                readonly "50": "#fef2f2";
+                readonly "400": "#f87171";
+                readonly "700": "#b91c1c";
+                readonly "950": "#450a0a";
+            };
+            readonly green: {
+                readonly "50": "#ecfdf5";
+                readonly "400": "#34d399";
+                readonly "700": "#047857";
+                readonly "950": "#022c22";
+            };
+            readonly amber: {
+                readonly "50": "#fffbeb";
+                readonly "400": "#fbbf24";
+                readonly "800": "#92400e";
+                readonly "950": "#451a03";
+            };
+            readonly stone: {
+                readonly "100": "#F5EFE7";
+                readonly "400": "#D0B492";
+                readonly "450": "#BC9D7E";
+                readonly "500": "#A8896A";
+                readonly "600": "#8B6F47";
+                readonly "700": "#75593A";
+                readonly "800": "#5C432A";
+                readonly "950": "#3A2E1F";
+            };
+            readonly projectBrand: {
+                readonly microsoftGameDev: {
+                    readonly "100": "#E5E5FC";
+                    readonly "500": "#6d31fb";
+                    readonly "900": "oklch(0.22 0.16 304)";
+                };
+            };
+        };
+        readonly space: {
+            readonly "0": "0px";
+            readonly "1": "4px";
+            readonly "2": "8px";
+            readonly "3": "12px";
+            readonly "4": "16px";
+            readonly "5": "20px";
+            readonly "6": "24px";
+            readonly "7": "28px";
+            readonly "8": "32px";
+            readonly "10": "40px";
+            readonly "12": "48px";
+            readonly "16": "64px";
+            readonly "20": "80px";
+            readonly "24": "96px";
+            readonly "32": "128px";
+            readonly px1: "1px";
+            readonly px2: "2px";
+            readonly px6: "6px";
+            readonly px10: "10px";
+        };
+        readonly blur: {
+            readonly "8": "8px";
+            readonly "16": "16px";
+        };
+        readonly radius: {
+            readonly "0": "0px";
+            readonly "2": "2px";
+            readonly "4": "4px";
+            readonly "8": "8px";
+            readonly "12": "12px";
+            readonly full: "9999px";
+        };
+        readonly typography: {
+            readonly family: {
+                readonly primary: readonly ["Satoshi", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"];
+                readonly display: readonly ["Clash Display", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"];
+                readonly mono: readonly ["Geist Mono", "Courier New", "monospace"];
+            };
+            readonly size: {
+                readonly "2xs": "10px";
+                readonly xs: "13px";
+                readonly sm: "15px";
+                readonly base: "17px";
+                readonly lg: "20px";
+                readonly xl: "24px";
+                readonly "2xl": "30px";
+                readonly "3xl": "36px";
+                readonly "4xl": "48px";
+                readonly "5xl": "80px";
+                readonly "7xl": "72px";
+            };
+            readonly weight: {
+                readonly light: "300";
+                readonly regular: "400";
+                readonly medium: "500";
+                readonly semibold: "600";
+                readonly bold: "700";
+            };
+            readonly lineHeight: {
+                readonly compact: "0.95";
+                readonly none: "1";
+                readonly tight: "1.25";
+                readonly snug: "1.375";
+                readonly normal: "1.5";
+                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";
+            };
+        };
+        readonly duration: {
+            readonly instant: "100ms";
+            readonly short: "150ms";
+            readonly medium: "250ms";
+            readonly long: "400ms";
+        };
+        readonly easing: {
+            readonly emphasized: "cubic-bezier(0.4, 0, 0.2, 1)";
+            readonly decelerate: "cubic-bezier(0, 0, 0.2, 1)";
+            readonly accelerate: "cubic-bezier(0.4, 0, 1, 1)";
+            readonly elastic: "spring(300, 20, 1)";
+        };
+        readonly shadow: {
+            readonly color: "220 13% 18%";
+        };
+        readonly breakpoint: {
+            readonly xs: "375px";
+            readonly sm: "640px";
+            readonly md: "768px";
+            readonly lg: "1024px";
+            readonly xl: "1280px";
+        };
+        readonly size: {
+            readonly "8": "8px";
+            readonly "10": "10px";
+            readonly "12": "12px";
+            readonly "16": "16px";
+            readonly "20": "20px";
+            readonly "24": "24px";
+            readonly "32": "32px";
+            readonly "40": "40px";
+            readonly "48": "48px";
+            readonly "64": "64px";
+            readonly "80": "80px";
+            readonly "96": "96px";
+            readonly interactive: {
+                readonly min: "44px";
+            };
+            readonly width: {
+                readonly "96": "96px";
+                readonly "760": "760px";
+                readonly "1200": "1200px";
+                readonly "50ch": "50ch";
+            };
+        };
+        readonly grid: {
+            readonly columns: {
+                readonly "1": "1";
+                readonly "2": "2";
+                readonly "3": "3";
+            };
+        };
+        readonly zIndex: {
+            readonly "0": "0";
+            readonly "10": "10";
+            readonly "100": "100";
+            readonly "1000": "1000";
+        };
+        readonly borderWidth: {
+            readonly xs: "1px";
+            readonly sm: "2px";
+            readonly md: "4px";
+        };
+    };
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Hirobius Design System - runtime theme resolver.
+ *
+ * ct(isDark) returns a computed colour object built entirely from hds tokens.
+ * Import this wherever you need resolved colours for a given dark/light mode.
+ *
+ * Usage:
+ *   import { ct } from '../design-system/theme';
+ *   const t = ct(isDark);
+ *   // t.bg, t.content, t.accent, etc.
+ */
+export declare function ct(isDark: boolean): {
+    bg: string;
+    panelBg: string;
+    fill: string;
+    hover: string;
+    brandTint: string;
+    content: {
+        primary: string;
+        secondary: string;
+        subtle: string;
+        faint: string;
+    };
+    border: string;
+    rule: string;
+    accent: string;
+    blueBar: string;
+    success: "#34d399" | "#047857";
+    danger: "#f87171" | "#b91c1c";
+    warning: "#fbbf24" | "#92400e";
+    info: "oklch(0.70 0.2903 266.54)" | "#1E2EFD";
+};

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

@@ -0,0 +1,333 @@
+/**
+ * Hirobius Design System — token bridge.
+ *
+ * All values here reference W3C CSS custom properties from tokens.css.
+ * Source of truth: hirobius.tokens.json → node scripts/build-tokens.mjs
+ *
+ * For colours that require runtime theme-mode computation see theme.ts / ct(isDark).
+ * Once full semantic colour tokens are added those too will become static CSS var references.
+ */
+import React from 'react';
+declare const hds: {
+    color: {
+        brand: string;
+        content: {
+            primary: string;
+            secondary: string;
+            disabled: string;
+            inverse: string;
+            accent: string;
+            onAccent: string;
+        };
+        brandPressed: string;
+        brandRGB: string;
+        white: string;
+        surface: {
+            page: {
+                dark: string;
+                light: string;
+            };
+            raised: {
+                dark: string;
+                light: string;
+            };
+        };
+        blue: {
+            '50': string;
+            '100': string;
+            '200': string;
+            '300': string;
+            '400': string;
+            '450': string;
+            '500': string;
+            '600': string;
+            '700': string;
+            '800': string;
+            '900': string;
+        };
+        feedback: {
+            success: {
+                dark: "#34d399";
+                light: "#047857";
+            };
+            warning: {
+                dark: "#fbbf24";
+                light: "#92400e";
+            };
+            error: {
+                dark: "#f87171";
+                light: "#b91c1c";
+            };
+            info: {
+                dark: "oklch(0.70 0.2903 266.54)";
+                light: "#1E2EFD";
+            };
+        };
+    };
+    fontFamily: string;
+    monoFamily: string;
+    fontSize: {
+        '2xs': string;
+        xs: string;
+        sm: string;
+        base: string;
+        lg: string;
+        xl: string;
+        '2xl': string;
+        '3xl': string;
+        '4xl': string;
+        '5xl': string;
+    };
+    fontWeight: {
+        regular: string;
+        medium: string;
+        semibold: string;
+        bold: string;
+    };
+    lineHeight: {
+        compact: string;
+        none: string;
+        tight: string;
+        snug: string;
+        normal: string;
+        relaxed: string;
+    };
+    letterSpacing: {
+        tighter: string;
+        tight: string;
+        normal: string;
+        wide: string;
+        wider: string;
+    };
+    semantic: {
+        color: {
+            accent: {
+                rest: "var(--semantic-accent-rest)";
+                hover: "var(--semantic-accent-hover)";
+                pressed: "var(--semantic-accent-pressed)";
+                subtle: "var(--semantic-accent-subtle)";
+                disabled: "var(--semantic-accent-disabled)";
+            };
+        };
+        space: {
+            subgrid: {
+                gap: string;
+                hairline: string;
+                xs: string;
+            };
+            component: {
+                padding: string;
+                gap: string;
+            };
+            stack: {
+                gap: string;
+            };
+            layout: {
+                gutter: string;
+                gap: string;
+                section: string;
+            };
+            section: {
+                stack: string;
+                inset: string;
+            };
+            sidebar: {
+                indent: string;
+                gap: string;
+                sectionGap: string;
+                railPadding: string;
+            };
+        };
+        typography: {
+            label: React.CSSProperties;
+            labelDescriptive: React.CSSProperties;
+            labelTechnical: React.CSSProperties;
+        };
+    };
+    typeStyles: {
+        display: React.CSSProperties;
+        h1: React.CSSProperties;
+        h2: React.CSSProperties;
+        h3: React.CSSProperties;
+        body: React.CSSProperties;
+        ui: React.CSSProperties;
+        eyebrow: React.CSSProperties;
+        mono: React.CSSProperties;
+        small: React.CSSProperties;
+        caption: React.CSSProperties;
+        heading1: React.CSSProperties;
+        heading2: React.CSSProperties;
+        heading3: React.CSSProperties;
+        technical: React.CSSProperties;
+        badge: React.CSSProperties;
+        micro: React.CSSProperties;
+        displayXl: React.CSSProperties;
+        display1: React.CSSProperties;
+        display2: React.CSSProperties;
+        headingHero: React.CSSProperties;
+        headingSection: React.CSSProperties;
+        title: React.CSSProperties;
+        body2: React.CSSProperties;
+        bodyLarge: React.CSSProperties;
+        bodySmall: React.CSSProperties;
+        monoXs: React.CSSProperties;
+        monoSm: React.CSSProperties;
+        label: React.CSSProperties;
+        labelDescriptive: React.CSSProperties;
+        labelTechnical: React.CSSProperties;
+    };
+    iconSize: {
+        small: string;
+        medium: string;
+        large: string;
+    };
+    density: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        xl2: string;
+        xl3: string;
+        xl4: string;
+    };
+    space: {
+        px1: string;
+        px2: string;
+        px4: string;
+        px6: string;
+        px8: string;
+        px10: string;
+        px12: string;
+        px16: string;
+        px20: string;
+        px24: string;
+        px28: string;
+        px32: string;
+        px40: string;
+        px48: string;
+        px64: string;
+        px80: string;
+        px96: string;
+        px128: string;
+    };
+    borderWidth: {
+        xs: string;
+        sm: string;
+        md: string;
+        default: string;
+        emphasis: string;
+    };
+    borderRadius: {
+        0: string;
+        2: string;
+        4: string;
+        8: string;
+        full: string;
+        circle: string;
+        /** Named aliases for common radii — prefer these over numeric keys in new code. */
+        sm: string;
+        md: string;
+        /** Global action radius — toggle one token to round all buttons, inputs, selects. */
+        action: string;
+    };
+    duration: {
+        /** 100ms — binary toggles, instant dismissals */
+        instant: string;
+        /** 150ms — micro-interactions, hover/focus/press (productive default) */
+        fast: string;
+        /** 250ms — entrances, teaching moments (expressive) */
+        normal: string;
+        /** 400ms — spatial movement, page travel (slow / spatial) */
+        slow: string;
+    };
+    effect: {
+        blur: {
+            subtle: string;
+            lightboxBackdrop: string;
+        };
+    };
+    zIndex: {
+        base: string;
+        focus: string;
+        overlay: string;
+        modal: string;
+    };
+    breakpoints: {
+        readonly xs: 375;
+        readonly sm: 640;
+        readonly md: 768;
+        readonly lg: 1024;
+        readonly xl: 1280;
+        readonly css: {
+            readonly xs: "var(--primitive-breakpoint-xs)";
+            readonly sm: "var(--primitive-breakpoint-sm)";
+            readonly md: "var(--primitive-breakpoint-md)";
+            readonly lg: "var(--primitive-breakpoint-lg)";
+            readonly xl: "var(--primitive-breakpoint-xl)";
+        };
+    };
+    layout: {
+        pageGutterH: string;
+        mobileGutterH: string;
+        sectionPad: string;
+        sectionPadSm: string;
+        panelGap: string;
+        panelGapMob: string;
+        containerMaxWidth: "var(--semantic-layout-container-maxWidth)";
+        contentMaxWidth: "var(--semantic-layout-content-maxWidth)";
+        proseMaxWidth: "var(--semantic-layout-prose-maxWidth)";
+        sectionPaddingY: "var(--semantic-layout-section-paddingY)";
+        gridColumnGap: "var(--semantic-layout-grid-gap)";
+    };
+    size: {
+        8: string;
+        10: string;
+        12: string;
+        16: string;
+        20: string;
+        24: string;
+        32: string;
+        40: string;
+        48: string;
+        64: string;
+        80: string;
+        96: string;
+        interactive: {
+            min: string;
+        };
+        width: {
+            '96': string;
+            '760': string;
+            '1200': string;
+            '50ch': string;
+        };
+    };
+    motion: {
+        readonly productive: {
+            readonly duration: number;
+            readonly easing: [number, number, number, number];
+        };
+        readonly expressive: {
+            readonly duration: number;
+            readonly easing: {
+                readonly type: "spring";
+                readonly stiffness: 300;
+                readonly damping: 20;
+                readonly mass: 1;
+            };
+        };
+        readonly spatial: {
+            readonly duration: number;
+            readonly easing: [number, number, number, number];
+        };
+        readonly exit: {
+            readonly duration: number;
+            readonly easing: [number, number, number, number];
+        };
+    };
+};
+/** @public */
+export default hds;
+export { ct } from './theme';
+export { tokenValues } from './generated-token-values';

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

@@ -0,0 +1,9 @@
+export interface FocusVisibleState {
+    /** True when the current focus should render a visible focus ring. */
+    isFocusVisible: boolean;
+    /** Call from `onFocus`, passing the focused element. */
+    onFocus: (target: Element) => void;
+    /** Call from `onBlur` / `onPointerDown` to drop the focus ring. */
+    clearFocusVisible: () => void;
+}
+export declare function useFocusVisible(): FocusVisibleState;

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

@@ -0,0 +1,27 @@
+export type InteractionVisualState = 'rest' | 'hover' | 'focused' | 'pressed' | 'disabled';
+/** Event-less setters; consumers compose their own forwarded handlers around these. */
+export interface InteractionHandlers {
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    onPointerDown: () => void;
+    onPointerUp: () => void;
+    onPointerCancel: () => void;
+    onFocus: () => void;
+    onBlur: () => void;
+}
+export interface InteractionState {
+    /** Resolved visual state — the frozen demo state wins when present. */
+    visualState: InteractionVisualState;
+    isHover: boolean;
+    isFocused: boolean;
+    isPressed: boolean;
+    isDisabled: boolean;
+    handlers: InteractionHandlers;
+}
+export interface UseInteractionStateOptions {
+    /** The genuine `disabled` prop — forces `disabled` regardless of pointer/focus. */
+    disabled?: boolean;
+    /** Frozen demo state from `useFrozenState()`; when set it overrides live state. */
+    frozenState?: InteractionVisualState | null;
+}
+export declare function useInteractionState({ disabled, frozenState, }: UseInteractionStateOptions): InteractionState;

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

@@ -0,0 +1,21 @@
+/**
+ * CaseStudyLayout — macro-layout skeleton for portfolio case study pages.
+ * @category Layout
+ *
+ * Invisible structure only. No Surface, no decorative chrome.
+ * Slot anatomy:
+ *   heroSlot    → full-width (maxWidth="max")  — hero image + headline
+ *   introSlot   → prose-width (maxWidth="content") — narrative, Brief/Problem/Solution
+ *   metricsSlot → full-width (maxWidth="max")  — KPI or summary cards (optional)
+ *   contentSlot → full-width (maxWidth="max")  — chapters, galleries, learnings
+ */
+import type { ReactNode } from 'react';
+interface CaseStudyLayoutProps {
+    heroSlot: ReactNode;
+    introSlot: ReactNode;
+    metricsSlot?: ReactNode;
+    contentSlot: ReactNode;
+}
+/** @public */
+export declare function CaseStudyLayout({ heroSlot, introSlot, metricsSlot, contentSlot }: CaseStudyLayoutProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,16 @@
+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)";
+};
+type DocLayoutMaxWidth = keyof typeof DOC_LAYOUT_CONTENT_WIDTHS;
+export type DocLayoutContentMaxWidth = DocLayoutMaxWidth;
+interface DocLayoutProps {
+    contentSlot: ReactNode;
+    bottomSlot?: ReactNode;
+    contentMaxWidth?: DocLayoutContentMaxWidth;
+}
+export declare function DocLayout({ contentSlot, bottomSlot, contentMaxWidth, }: DocLayoutProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,6 @@
+import { type ReactNode } from 'react';
+export declare function EmbeddedDocLayoutProvider({ bottomSlot, children, }: {
+    bottomSlot: ReactNode | null;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useEmbeddedDocLayoutBottomSlot(): ReactNode;

package/dist/types/src/app/lib/nav-active.d.ts

@@ -0,0 +1,16 @@
+/**
+ * nav-active — the single active-state rule for navigation items.
+ *
+ * Previously this 3-line predicate was copy-pasted in three places (NavGroup,
+ * and HDSLayout's NestedNavGroup + SideNavItem). Centralized here so "is this
+ * nav item active?" has exactly one definition (ADR-017, Phase 4).
+ */
+/**
+ * Whether a nav item is active for the current path.
+ *
+ * - `exact`: the route must match precisely (e.g. `/` or a landing page that
+ *   shares a prefix with its children).
+ * - otherwise: active when the current path equals the item path OR is a
+ *   descendant route (`/components` is active on `/components/actions`).
+ */
+export declare function isNavItemActive(currentPath: string, itemPath: string, exact?: boolean): boolean;