@hirobius/design-system 0.10.0 → 0.12.0

package/dist/types/src/app/lib/hds-search.d.ts

@@ -0,0 +1,45 @@
+/** @internal — search engine behind the CommandPalette; not part of the public API. */
+/**
+ * hds-search — the manifest search engine extracted from CommandPalette.
+ *
+ * A dependency-free subsequence + position scorer (think micro-fzf) over four
+ * corpora drawn from `virtual:hds-manifest`: component specs, utilities, role
+ * tokens, and curated foundation sections. Pure and side-effect-free — the
+ * manifest is passed in, never read from a module global — so it is unit-tested
+ * directly (see scripts/../tests/hds-search.test.ts) rather than through a
+ * component test hook.
+ *
+ * Lifted from command-palette.tsx per ADR-011's review (deep module behind a
+ * narrow interface): the UI shell now imports { buildIndex, rank } and owns no
+ * search logic.
+ */
+import type { ManifestSpec, RoleToken, SystemManifest } from '../data/manifest-types';
+export type { ManifestSpec, RoleToken, SystemManifest };
+export type ResultKind = 'component' | 'pattern' | 'template' | 'utility' | 'token' | 'section';
+export interface PaletteResult {
+    id: string;
+    label: string;
+    description: string;
+    kind: ResultKind;
+    /** Where Enter/click navigates — relative React Router path. */
+    to: string;
+    /** Source string used for fuzzy matching (lowercased). */
+    haystack: string;
+}
+export declare const KIND_LABEL: Record<ResultKind, string>;
+export declare const MAX_RESULTS = 30;
+export declare function sanitize(text: string): string;
+/** Build the searchable index from a manifest. Pure — pass the manifest in. */
+export declare function buildIndex(manifest: SystemManifest): PaletteResult[];
+/**
+ * Subsequence + position scorer:
+ *   - Every char in `query` must appear in order inside `haystack`.
+ *   - Earlier matches score higher (heavy weight on first hit).
+ *   - Adjacent-char streaks score higher (clustered matches).
+ *   - Word-start hits get a bonus.
+ *
+ * Returns -Infinity if `query` is not a subsequence of `haystack`.
+ */
+export declare function fuzzyScore(query: string, haystack: string): number;
+/** Rank items against a query. Empty query → a stable starter set. */
+export declare function rank(query: string, items: PaletteResult[]): PaletteResult[];

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

@@ -0,0 +1,9 @@
+/**
+ * @hirobius/design-system/brand — palette → HDS-semantic overlay bridge.
+ *
+ * Framework-free helpers that theme any render target (static Astro, SSR, email)
+ * from a small brand palette while inheriting the HDS semantic contract. Imports
+ * no React and no Node built-ins, so it is safe to pull into a build step or an
+ * edge runtime. See ./overlay.ts and docs on the Astro consumption path.
+ */
+export { brandOverlayVars, brandOverlayStyle, brandOverlayCss, type BrandPalette } from './overlay';

package/dist/types/src/brand/overlay.d.ts

@@ -0,0 +1,71 @@
+/**
+ * overlay.ts — pure palette → HDS-semantic overlay bridge.
+ *
+ * The seam that lets a downstream render target (a static Astro site, an email,
+ * an SSR shell) theme itself from a small brand palette while inheriting HDS's
+ * semantic contract — contrast-checked pairs, accent states, density, dark mode.
+ *
+ * A consumer resolves a brand palette (six colours + optional font/radius) and
+ * this module maps it onto the HDS semantic custom properties. Everything HDS
+ * ships downstream of those semantics (component tokens, utilities) then reads
+ * the brand automatically via the `var()` reference chain — the same strategy
+ * as the checked-in `[data-brand]` tenant overlays (`src/styles/tenants.css`),
+ * but computed at the consumer instead of at HDS build time, so HDS never has
+ * to know the client roster.
+ *
+ * Deliberately dependency-free (no React, no Node) so it runs in any render
+ * target and is unit-testable in isolation. Mirrors the zero-dependency idiom
+ * of `box-sx.ts`.
+ *
+ * Interactive accent states (hover/pressed/subtle) are derived from the primary
+ * with CSS `color-mix()` — no colour-math dependency, resolved by the browser.
+ * `color-mix()` is Baseline-supported (all evergreen engines since 2023); the
+ * factory ships new sites, so this is a safe floor.
+ *
+ * @packageDocumentation
+ */
+/** A resolved brand palette — the minimal input needed to theme a surface. */
+export interface BrandPalette {
+    /** Primary brand colour — accent rest, key surfaces, links. */
+    primary: string;
+    /** Text/icon colour that sits on top of `primary`. */
+    onPrimary: string;
+    /** Page background. */
+    bg: string;
+    /** Body/foreground text colour. */
+    fg: string;
+    /** Muted surface — raised cards, subtle fills. */
+    muted: string;
+    /** Optional secondary accent. Kept brand-level (HDS has one accent ramp). */
+    accent?: string;
+    /** Optional corner radius as a CSS length (e.g. `'8px'`). */
+    radius?: string;
+    /** Optional heading font stack. */
+    fontHeading?: string;
+    /** Optional body font stack. */
+    fontBody?: string;
+}
+/**
+ * Map a brand palette onto HDS semantic (and a few primitive) custom
+ * properties. Returns a flat `--var` → value record; the caller decides how to
+ * apply it (inline style string via {@link brandOverlayStyle} or a scoped CSS
+ * rule via {@link brandOverlayCss}).
+ *
+ * Only the accent ramp, page/content colours, and — when provided — radius and
+ * font families are overridden. All other semantics inherit HDS defaults
+ * unchanged, so a partial palette still yields a coherent theme.
+ */
+export declare function brandOverlayVars(palette: BrandPalette): Record<string, string>;
+/**
+ * Serialize a palette to an inline `style` string (`k:v;k:v`) for the `<html>`
+ * element. Inline element styles beat stylesheet rules, so this is the most
+ * direct per-surface theming path (the model the clients factory already uses).
+ */
+export declare function brandOverlayStyle(palette: BrandPalette): string;
+/**
+ * Serialize a palette to a scoped CSS rule (`<selector>{ --var: value; }`) for
+ * a static stylesheet — e.g. `[data-brand="acme"]` blocks in an Astro layout,
+ * mirroring the checked-in tenant overlays. `selector` is emitted verbatim; the
+ * caller owns its trust (typically a slug it controls).
+ */
+export declare function brandOverlayCss(selector: string, palette: BrandPalette): string;

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

@@ -2,6 +2,7 @@ export * from './app/components/alert';
 export * from './app/components/asset-img';
 export * from './app/components/avatar';
 export * from './app/components/badge';
+export * from './app/components/box';
 export * from './app/components/button';
 export * from './app/components/callout';
 export * from './app/components/field';
@@ -16,6 +17,7 @@ export * from './app/components/dialog';
 export * from './app/components/divider';
 export * from './app/components/menu';
 export * from './app/components/popover';
+export * from './app/components/hds-tooltip';
 export * from './app/components/doc-link-card';
 export * from './app/components/grid';
 export * from './app/components/heading-stack';
@@ -24,6 +26,7 @@ export * from './app/components/icon';
 export * from './app/components/inline-code';
 export * from './app/components/inline-link';
 export * from './app/components/input';
+export * from './app/components/textarea';
 export * from './app/components/checkbox';
 export * from './app/components/radio';
 export * from './app/components/slider';
@@ -39,6 +42,49 @@ export * from './app/components/table';
 export * from './app/components/tag';
 export * from './app/components/text';
 export * from './app/components/token';
+export * from './app/components/kbd';
+export * from './app/components/status-dot';
+export * from './app/components/timestamp';
+export * from './app/components/blockquote';
+export * from './app/components/visually-hidden';
+export * from './app/components/avatar-group';
+export * from './app/components/button-group';
+export * from './app/components/input-group';
+export * from './app/components/circular-progress';
+export * from './app/components/toggle-button';
+export * from './app/components/aspect-ratio';
+export * from './app/components/alert-dialog';
+export * from './app/components/hover-card';
+export * from './app/components/context-menu';
+export * from './app/components/side-nav';
+export * from './app/components/command-palette';
+export * from './app/components/image-lightbox';
+export * from './app/components/metadata-list';
+export * from './app/components/overflow-list';
+export * from './app/components/top-nav';
+export * from './app/components/app-shell';
+export * from './app/components/selectable-card';
+export * from './app/components/tokenizer';
+export * from './app/components/file-input';
+export * from './app/components/multi-selector';
+export * from './app/components/toolbar';
+export * from './app/components/tree-list';
+export * from './app/components/stepper';
+export * from './app/components/carousel';
+export * from './app/components/calendar';
+export * from './app/components/time-input';
+export * from './app/components/date-input';
+export * from './app/components/date-range-input';
+export * from './app/components/date-time-input';
+export * from './app/components/cluster';
+export * from './app/components/center';
+export * from './app/components/sidebar';
+export * from './app/components/switcher';
+export * from './app/components/cover';
+export * from './app/components/frame';
+export * from './app/components/bleed';
+export * from './app/components/reveal';
+export * from './app/components/pin';
 export * from './app/components/page';
 export * from './app/components/empty-state';
 export * from './app/components/error-boundary';
@@ -61,8 +107,7 @@ export * from './app/components/text-lockup';
 export * from './app/components/toast';
 export * from './app/layouts/CaseStudyLayout';
 export * from './app/components/error-pattern';
-export * from './app/components/info-page';
-export * from './app/pages/hds/HdsSystemDocLayout';
+export * from './app/layouts/HdsSystemDocLayout';
 export { default as hds } from './app/design-system/tokens';
 /** Raw DTCG design tokens (the contents of `hirobius.tokens.json`). */
 export declare const tokens: {
@@ -235,6 +280,53 @@ export declare const tokens: {
                 };
                 $description: string;
             };
+            lilac: {
+                "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;
+                };
+                "450": {
+                    $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;
+                };
+                $description: string;
+            };
             amber: {
                 "50": {
                     $value: string;
@@ -1557,6 +1649,19 @@ export declare const tokens: {
                 };
                 $description: string;
             };
+            caption: {
+                $value: {
+                    fontFamily: string;
+                    fontSize: {
+                        value: number;
+                        unit: string;
+                    };
+                    fontWeight: string;
+                    letterSpacing: string;
+                    lineHeight: string;
+                };
+                $description: string;
+            };
             eyebrow: {
                 $value: {
                     fontFamily: string;
@@ -2315,5 +2420,7 @@ export declare const tokens: {
     };
 };
 export { cn } from './lib/utils';
+export { HdsThemeProvider, useHdsTheme } from './app/context/hds-theme';
+export type { HdsTheme, HdsDensity, HdsThemeValue, HdsThemeProviderProps, } from './app/context/hds-theme';
 export { HdsRouterProvider, useHdsRouter } from './app/context/RouterContext';
 export type { HdsRouterAdapter, HdsRouterProviderProps, HdsLinkComponent, HdsLinkProps, HdsNavigateOptions, } from './app/context/RouterContext';

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

@@ -0,0 +1,16 @@
+/**
+ * @hirobius/design-system/scroll — opt-in scroll-motion primitives.
+ *
+ * Ships behind a dedicated subpath with `lenis` as an OPTIONAL peer dependency
+ * (install `lenis` alongside HDS to use `SmoothScroll`). Never in the main
+ * barrel — consumers who don't import this pay nothing. See ADR-021 and #116.
+ *
+ * - `SmoothScroll` — Lenis momentum-scroll provider (reduced-motion-first, SSR-safe).
+ * - `useLenis` — access the active Lenis instance / subscribe to scroll (re-exported
+ *   from `lenis/react`).
+ * - `useScrollProgress` — Motion-based 0→1 scroll progress for a target element
+ *   (no new dependency; works with or without `SmoothScroll`).
+ */
+export { SmoothScroll, type SmoothScrollProps, type SmoothScrollOptions } from './smooth-scroll';
+export { useScrollProgress, type UseScrollProgressOptions, type ScrollOffset, } from './use-scroll-progress';
+export { useLenis } from 'lenis/react';

package/dist/types/src/scroll/smooth-scroll.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SmoothScroll — opt-in Lenis smooth-scroll provider for HDS.
+ *
+ * The one scroll capability neither CSS `animation-timeline` nor Motion's
+ * `useScroll` can provide: momentum-smoothed ("inertia") scrolling. Ships behind
+ * the dedicated `@hirobius/design-system/scroll` subpath with `lenis` as an
+ * OPTIONAL peer dependency, so it is never in the main barrel and consumers who
+ * don't import it pay nothing (ADR-021).
+ *
+ * Wraps Lenis's official React integration (`lenis/react`) and adds HDS
+ * conventions:
+ *   - **Reduced-motion first.** When the user prefers reduced motion, Lenis is
+ *     not instantiated at all — children render against native scroll. Override
+ *     with `ignoreReducedMotion` only for a deliberate art-directed exception.
+ *   - **SSR-safe.** The reduced-motion probe runs client-side; server render and
+ *     first paint fall back to native scroll, then upgrade on mount.
+ *   - **Tokenized defaults.** A premium duration/easing out of the box,
+ *     overridable via `options`.
+ *
+ * Lenis drives the real scroll position, so CSS scroll-driven animations and
+ * `useScrollProgress` (Motion) keep working underneath it unchanged.
+ *
+ * @example
+ * import { SmoothScroll } from '@hirobius/design-system/scroll';
+ * // one provider at the app/site root:
+ * <SmoothScroll><App /></SmoothScroll>
+ */
+import * as React from 'react';
+import { ReactLenis } from 'lenis/react';
+/** Lenis options, derived from the official React integration (no extra import). */
+export type SmoothScrollOptions = NonNullable<React.ComponentProps<typeof ReactLenis>['options']>;
+export interface SmoothScrollProps {
+    children: React.ReactNode;
+    /** Lenis options merged over the HDS defaults (duration, easing, smoothWheel). */
+    options?: SmoothScrollOptions;
+    /**
+     * Hijack the window/document scroll (the usual root-level setup). Default `true`.
+     * Set `false` to scope smoothing to a wrapper element instead.
+     */
+    root?: boolean;
+    /**
+     * Run smoothing even when the user prefers reduced motion. Default `false`
+     * (the preference is respected — momentum scroll is a motion effect).
+     */
+    ignoreReducedMotion?: boolean;
+}
+/** @public */
+export declare function SmoothScroll({ children, options, root, ignoreReducedMotion, }: SmoothScrollProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/src/scroll/use-scroll-progress.d.ts

@@ -0,0 +1,34 @@
+/**
+ * useScrollProgress — a tokenized wrapper over Motion's `useScroll`.
+ *
+ * Returns a `0 → 1` MotionValue tracking a target element's travel through the
+ * viewport, for JS-driven scroll effects that CSS `animation-timeline` can't
+ * express (cross-element choreography, canvas/WebGL, values you need in React).
+ * Built on `motion/react` — already the HDS animation engine — so it adds no new
+ * dependency, and it works with or without {@link SmoothScroll} (Lenis drives
+ * the real scroll position, which Motion reads).
+ *
+ * For the common "reveal on enter / scale on scroll" cases, prefer CSS
+ * scroll-driven animation (`animation-timeline: view()`) — zero JS. Reach for
+ * this hook only when you genuinely need the progress value in React.
+ *
+ * @example
+ * const ref = useRef<HTMLDivElement>(null);
+ * const progress = useScrollProgress(ref);
+ * const scale = useTransform(progress, [0, 1], [0.4, 1]);
+ * return <motion.div ref={ref} style={{ scale }} />;
+ */
+import { useScroll, type MotionValue } from 'motion/react';
+import type { RefObject } from 'react';
+/** Scroll offset pair (Motion `useScroll` semantics), e.g. `['start end', 'end start']`. */
+export type ScrollOffset = NonNullable<Parameters<typeof useScroll>[0]>['offset'];
+export interface UseScrollProgressOptions {
+    /**
+     * Where progress starts (0) and ends (1), in Motion's `[targetEdge viewportEdge, …]`
+     * form. Defaults to `['start end', 'end start']` — 0 as the target's top enters
+     * the bottom of the viewport, 1 as its bottom leaves the top.
+     */
+    offset?: ScrollOffset;
+}
+/** @public */
+export declare function useScrollProgress(target: RefObject<HTMLElement | null>, options?: UseScrollProgressOptions): MotionValue<number>;

package/dist/variables.css

@@ -52,6 +52,17 @@
   --primitive-color-violet-400: #a78bfa;
   --primitive-color-violet-700: #6d28d9;
   --primitive-color-violet-950: #2e1065;
+  --primitive-color-lilac-50: #f7f4fe;
+  --primitive-color-lilac-100: #efe9fd;
+  --primitive-color-lilac-200: #ddd0fb;
+  --primitive-color-lilac-300: #c3aef6;
+  --primitive-color-lilac-400: #a585ee;
+  --primitive-color-lilac-450: #9a6fe8;
+  --primitive-color-lilac-500: #6f3fd4;
+  --primitive-color-lilac-600: #5f33c0;
+  --primitive-color-lilac-700: #4f2aa3;
+  --primitive-color-lilac-800: #3a1f78;
+  --primitive-color-lilac-900: #2a1659;
   --primitive-color-amber-50: #fffbeb;
   --primitive-color-amber-400: #fbbf24;
   --primitive-color-amber-800: #92400e;
@@ -95,7 +106,7 @@
   --primitive-radius-12: 12px;
   --primitive-radius-full: 9999px;
   --primitive-typography-family-primary: Satoshi, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-  --primitive-typography-family-display: "Clash Display", 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-size-2xs: 10px;
   --primitive-typography-size-xs: 13px;
@@ -238,25 +249,25 @@
   /* semantic.typography.display */
   --semantic-typography-display-font-family: var(--primitive-typography-family-display);
   --semantic-typography-display-font-size: var(--primitive-typography-size-7xl);
-  --semantic-typography-display-font-weight: var(--primitive-typography-weight-medium);
+  --semantic-typography-display-font-weight: var(--primitive-typography-weight-bold);
   --semantic-typography-display-letter-spacing: var(--primitive-typography-letterSpacing-tight);
   --semantic-typography-display-line-height: var(--primitive-typography-lineHeight-none);
   /* semantic.typography.h1 */
   --semantic-typography-h1-font-family: var(--primitive-typography-family-display);
   --semantic-typography-h1-font-size: var(--primitive-typography-size-4xl);
-  --semantic-typography-h1-font-weight: var(--primitive-typography-weight-medium);
+  --semantic-typography-h1-font-weight: var(--primitive-typography-weight-bold);
   --semantic-typography-h1-letter-spacing: var(--primitive-typography-letterSpacing-tight);
   --semantic-typography-h1-line-height: var(--primitive-typography-lineHeight-tight);
   /* semantic.typography.h2 */
   --semantic-typography-h2-font-family: var(--primitive-typography-family-display);
   --semantic-typography-h2-font-size: var(--primitive-typography-size-2xl);
-  --semantic-typography-h2-font-weight: var(--primitive-typography-weight-medium);
+  --semantic-typography-h2-font-weight: var(--primitive-typography-weight-bold);
   --semantic-typography-h2-letter-spacing: var(--primitive-typography-letterSpacing-tight);
   --semantic-typography-h2-line-height: 42px;
   /* semantic.typography.h3 */
   --semantic-typography-h3-font-family: var(--primitive-typography-family-display);
   --semantic-typography-h3-font-size: var(--primitive-typography-size-lg);
-  --semantic-typography-h3-font-weight: var(--primitive-typography-weight-medium);
+  --semantic-typography-h3-font-weight: var(--primitive-typography-weight-bold);
   --semantic-typography-h3-letter-spacing: var(--primitive-typography-letterSpacing-normal);
   --semantic-typography-h3-line-height: 28px;
   /* semantic.typography.body */
@@ -273,6 +284,12 @@
   --semantic-typography-ui-letter-spacing: var(--primitive-typography-letterSpacing-normal);
   --semantic-typography-ui-line-height: 24px;
   --semantic-typography-ui-max-width: 60ch;
+  /* semantic.typography.caption */
+  --semantic-typography-caption-font-family: var(--primitive-typography-family-primary);
+  --semantic-typography-caption-font-size: 12px;
+  --semantic-typography-caption-font-weight: var(--primitive-typography-weight-medium);
+  --semantic-typography-caption-letter-spacing: var(--primitive-typography-letterSpacing-normal);
+  --semantic-typography-caption-line-height: 16px;
   /* semantic.typography.eyebrow */
   --semantic-typography-eyebrow-font-family: var(--primitive-typography-family-primary);
   --semantic-typography-eyebrow-font-size: var(--primitive-typography-size-xs);

package/hirobius.tokens.json

@@ -168,6 +168,53 @@
         },
         "$description": "Discrete values within the violet range at defined lightness steps."
       },
+      "lilac": {
+        "50": {
+          "$value": "#f7f4fe",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "100": {
+          "$value": "#efe9fd",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "200": {
+          "$value": "#ddd0fb",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "300": {
+          "$value": "#c3aef6",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "400": {
+          "$value": "#a585ee",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "450": {
+          "$value": "#9a6fe8",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "500": {
+          "$value": "#6f3fd4",
+          "$description": "Lilac Bonds accent rest — AA for white text on page and card surfaces."
+        },
+        "600": {
+          "$value": "#5f33c0",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "700": {
+          "$value": "#4f2aa3",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "800": {
+          "$value": "#3a1f78",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "900": {
+          "$value": "#2a1659",
+          "$description": "Specific value within the lilac range at a defined lightness step."
+        },
+        "$description": "Discrete values within the lilac range at defined lightness steps. Mirrors the blue ramp's stop set; consumed by the lilac-bonds tenant overlay."
+      },
       "amber": {
         "50": {
           "$value": "#fffbeb",
@@ -432,14 +479,14 @@
         },
         "display": {
           "$value": [
-            "Clash Display",
+            "Satoshi",
             "system-ui",
             "-apple-system",
             "BlinkMacSystemFont",
             "Segoe UI",
             "sans-serif"
           ],
-          "$description": "Display face: Clash Display ITF, bound to display/h1/h2/h3 composites."
+          "$description": "Display face: Satoshi Bold (ITF), bound to display/h1/h2/h3 composites."
         },
         "mono": {
           "$value": ["Geist Mono", "Courier New", "monospace"],
@@ -1416,11 +1463,11 @@
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
           "fontSize": "{primitive.typography.size.7xl}",
-          "fontWeight": "{primitive.typography.weight.medium}",
+          "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.tight}",
           "lineHeight": "{primitive.typography.lineHeight.none}"
         },
-        "$description": "Display headline. 72px / Clash Display 500 / leading-none.",
+        "$description": "Display headline. 72px / Satoshi bold 700 / leading-none.",
         "$extensions": {
           "com.figma.variables": {
             "fontSize": "clamp(40px, 8vw, 72px)",
@@ -1432,11 +1479,11 @@
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
           "fontSize": "{primitive.typography.size.4xl}",
-          "fontWeight": "{primitive.typography.weight.medium}",
+          "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.tight}",
           "lineHeight": "{primitive.typography.lineHeight.tight}"
         },
-        "$description": "Primary section headings (h1). 48px / Clash Display medium 500 / leading-tight.",
+        "$description": "Primary section headings (h1). 48px / Satoshi bold 700 / leading-tight.",
         "$extensions": {
           "com.figma.variables": {
             "fontSize": "clamp(32px, 6vw, 48px)",
@@ -1448,11 +1495,11 @@
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
           "fontSize": "{primitive.typography.size.2xl}",
-          "fontWeight": "{primitive.typography.weight.medium}",
+          "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.tight}",
           "lineHeight": "42px"
         },
-        "$description": "Secondary section headings (h2). Clash Display medium, 30px, line-height 42px.",
+        "$description": "Secondary section headings (h2). Satoshi bold 700, 30px, line-height 42px.",
         "$extensions": {
           "com.figma.variables": {
             "fontSize": "clamp(24px, 3.5vw, 30px)",
@@ -1464,11 +1511,11 @@
         "$value": {
           "fontFamily": "{primitive.typography.family.display}",
           "fontSize": "{primitive.typography.size.lg}",
-          "fontWeight": "{primitive.typography.weight.medium}",
+          "fontWeight": "{primitive.typography.weight.bold}",
           "letterSpacing": "{primitive.typography.letterSpacing.normal}",
           "lineHeight": "28px"
         },
-        "$description": "Component and card headers (h3). 20px / Clash Display medium 500 / leading-snug.",
+        "$description": "Component and card headers (h3). 20px / Satoshi bold 700 500 / leading-snug.",
         "$extensions": {
           "com.figma.variables": {
             "fontSize": "clamp(18px, 2vw, 20px)",
@@ -1504,6 +1551,19 @@
         },
         "$description": "UI text for nav, labels, captions. Satoshi medium, 15px, line-height 24px."
       },
+      "caption": {
+        "$value": {
+          "fontFamily": "{primitive.typography.family.primary}",
+          "fontSize": {
+            "value": 12,
+            "unit": "px"
+          },
+          "fontWeight": "{primitive.typography.weight.medium}",
+          "letterSpacing": "{primitive.typography.letterSpacing.normal}",
+          "lineHeight": "16px"
+        },
+        "$description": "Caption / helper text. Satoshi medium, 12px, line-height 16px. Matches the Figma typography/caption text style."
+      },
       "eyebrow": {
         "$value": {
           "fontFamily": "{primitive.typography.family.primary}",