@hirobius/design-system 0.9.0 → 0.11.0

package/dist/tokens.js

@@ -285,6 +285,13 @@ const a = {
         lineHeight: "var(--semantic-typography-ui-line-height)",
         maxWidth: "var(--semantic-typography-ui-max-width)"
       },
+      caption: {
+        fontFamily: "var(--semantic-typography-caption-font-family)",
+        fontSize: "var(--semantic-typography-caption-font-size)",
+        fontWeight: "var(--semantic-typography-caption-font-weight)",
+        letterSpacing: "var(--semantic-typography-caption-letter-spacing)",
+        lineHeight: "var(--semantic-typography-caption-line-height)"
+      },
       eyebrow: {
         fontFamily: "var(--semantic-typography-eyebrow-font-family)",
         fontSize: "var(--semantic-typography-eyebrow-font-size)",
@@ -499,11 +506,12 @@ const o = "var(--primitive-typography-family-primary)", n = "var(--primitive-typ
     eyebrow: i.semantic.typography.eyebrow,
     mono: i.semantic.typography.mono,
     // ── Migration aliases → canonical composites ──────────────────────────────
-    // Pre-2026-05-04 names map to the new roles. small → ui; caption → ui
-    // (sentence-case secondary text); the eyebrow-pattern callsites migrate
-    // explicitly to typeStyles.eyebrow as part of the ops-dashboard sweep.
+    // Pre-2026-05-04 names map to the new roles. small → ui; the eyebrow-pattern
+    // callsites migrate explicitly to typeStyles.eyebrow as part of the
+    // ops-dashboard sweep. caption now resolves to its own 12/16 composite
+    // (semantic.typography.caption, matching Figma) rather than aliasing ui.
     small: i.semantic.typography.ui,
-    caption: i.semantic.typography.ui,
+    caption: i.semantic.typography.caption,
     heading1: i.semantic.typography.h1,
     heading2: i.semantic.typography.h2,
     heading3: i.semantic.typography.h3,

package/dist/types/src/app/components/hds-tooltip.d.ts

@@ -0,0 +1,45 @@
+/**
+ * HdsTooltip — accessible hover/focus tooltip on Radix (Overlays).
+ * @category Overlays
+ * @tier primitive
+ * @doc-exempt: no Overlays doc page yet — add demo when the overlays page is created
+ *
+ * Radix Tooltip (@radix-ui/react-tooltip) themed with role tokens. Provides
+ * Floating-UI collision-aware positioning, ARIA wiring, keyboard focus support,
+ * open/close delay, and portal mounting out of the box. Unlike the legacy
+ * `Tooltip` (an @internal image-expand pill bound to AssetImg), this is the
+ * general-purpose accessible tooltip for labelling controls.
+ *
+ *   <HdsTooltip>
+ *     <HdsTooltip.Trigger asChild>
+ *       <IconButton icon={Link} aria-label="Copy link" />
+ *     </HdsTooltip.Trigger>
+ *     <HdsTooltip.Content>Copy link</HdsTooltip.Content>
+ *   </HdsTooltip>
+ *
+ * Skin: inverse surface bubble (semantic.color.surface.inverse) + inverse
+ * content text (semantic.color.content.inverse) — these are a designed pair, so
+ * the bubble reads correctly in BOTH themes (dark bubble/light text in light
+ * mode, light bubble/dark text in dark mode). Radius 4 (primitive.radius.4),
+ * shadow-overlay, and a matching arrow. Text reuses the caption type composite.
+ */
+import * as React from 'react';
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+/** @public */
+export type HdsTooltipContentProps = React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>;
+declare const HdsTooltipContent: React.ForwardRefExoticComponent<Omit<TooltipPrimitive.TooltipContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+interface HdsTooltipComponent extends React.FC<React.ComponentProps<typeof TooltipPrimitive.Root> & {
+    /** Hover-open delay in ms (Radix Provider). Default 300. */
+    delayDuration?: number;
+}> {
+    Trigger: typeof TooltipPrimitive.Trigger;
+    Content: typeof HdsTooltipContent;
+}
+/**
+ * Tooltip root. Bakes in the Radix Provider so a single `<HdsTooltip>` is
+ * self-contained — no app-level provider required. Controlled via
+ * `open`/`onOpenChange`, or uncontrolled with `defaultOpen`.
+ * @public
+ */
+declare const HdsTooltip: HdsTooltipComponent;
+export { HdsTooltip };

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

@@ -0,0 +1,38 @@
+/**
+ * Textarea — multi-line text field primitive with label, helper, and error slots.
+ * @category Inputs
+ * @tier primitive
+ *
+ * Mirrors Input's shell + token skin as a native `<textarea>`. Figma parity:
+ * the four states Default / Focus / Error / Disabled map to the focus-ring,
+ * `error`, and `disabled` treatments below.
+ */
+import * as React from 'react';
+import { type VariantProps } from 'class-variance-authority';
+declare const textareaVariants: (props?: {
+    resize?: "none" | "both" | "vertical";
+    invalid?: boolean;
+} & import("class-variance-authority/dist/types").ClassProp) => string;
+/** @public */
+export type TextareaResize = NonNullable<VariantProps<typeof textareaVariants>['resize']>;
+export interface TextareaProps extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'disabled'> {
+    /** Field label rendered above the textarea. */
+    label?: string;
+    /** Supporting helper text rendered below when not in error. */
+    helperText?: string;
+    /** Disable interaction. */
+    disabled?: boolean;
+    /** Mark the field as invalid (sets aria-invalid + destructive border). */
+    error?: boolean;
+    /** Error message rendered below the textarea when `error` is true. */
+    errorMessage?: string;
+    /** User resize affordance. Defaults to vertical-only. */
+    resize?: TextareaResize;
+    /** Class hook for the outer wrapper. */
+    className?: string;
+    /** Class hook for the textarea element itself. */
+    textareaClassName?: string;
+}
+export declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+/** @internal — CVA variant helper; compose via Textarea props instead. */
+export { textareaVariants };

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

@@ -0,0 +1,68 @@
+/**
+ * HdsThemeProvider — framework-agnostic theming contract for HDS.
+ * @category Theming
+ * @tier primitive
+ * @doc-exempt: API/contract primitive, documented in README (no doc page yet)
+ *
+ * HDS theming is driven entirely by root attributes + CSS custom properties, so
+ * it works with ZERO JavaScript (the Astro / static path just sets the same
+ * attributes on a layout element). The four override "dials":
+ *
+ *   dial     attribute / var           values                         default
+ *   ───────  ────────────────────────  ─────────────────────────────  ──────────
+ *   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
+ *
+ * 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
+ * toggle (that is the in-app ThemeContext's job). Styles do not require it; it
+ * exists so React apps can set the contract declaratively and read it back via
+ * `useHdsTheme()`.
+ *
+ *   <HdsThemeProvider theme="dark" density="compact" brand="acme">
+ *     <App />
+ *   </HdsThemeProvider>
+ *
+ * Equivalent zero-JS markup:
+ *   <div data-hds data-theme="dark" data-density="compact" data-brand="acme">…</div>
+ */
+import * as React from 'react';
+/** @public */
+export type HdsTheme = 'light' | 'dark';
+/** @public */
+export type HdsDensity = 'comfortable' | 'compact';
+/** @public */
+export interface HdsThemeValue {
+    /** Colour theme. `"dark"` activates the dark token overrides; omit for light. */
+    theme?: HdsTheme;
+    /** Spacing density. `"compact"` activates the compact overrides; omit for comfortable. */
+    density?: HdsDensity;
+    /** Brand-overlay slug (compiled `[data-brand]`/`[data-tenant]` block). Omit for the base brand. */
+    brand?: string;
+    /** Body font-family override (`--hds-font-family`). */
+    fontFamily?: string;
+    /** Monospace font-family override (`--hds-font-family-mono`). */
+    fontFamilyMono?: string;
+}
+/**
+ * Read the nearest HdsThemeProvider's active dial values. Returns an empty
+ * object when no provider is present (styles still work off the defaults).
+ * @public
+ */
+export declare function useHdsTheme(): HdsThemeValue;
+/** @public */
+export interface HdsThemeProviderProps extends HdsThemeValue {
+    children: React.ReactNode;
+    /** Wrapper element type for the `data-hds` scope. Default `"div"`. */
+    as?: React.ElementType;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Renders a `data-hds` scope wrapper that carries the four theming dials as
+ * root attributes + CSS vars, and exposes them to `useHdsTheme()`.
+ * @public
+ */
+export declare function HdsThemeProvider({ theme, density, brand, fontFamily, fontFamilyMono, as: Comp, className, style, children, }: HdsThemeProviderProps): import("react/jsx-runtime").JSX.Element;

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

@@ -384,6 +384,13 @@ export declare const tokenRefs: {
                 readonly lineHeight: "var(--semantic-typography-ui-line-height)";
                 readonly maxWidth: "var(--semantic-typography-ui-max-width)";
             };
+            readonly caption: {
+                readonly fontFamily: "var(--semantic-typography-caption-font-family)";
+                readonly fontSize: "var(--semantic-typography-caption-font-size)";
+                readonly fontWeight: "var(--semantic-typography-caption-font-weight)";
+                readonly letterSpacing: "var(--semantic-typography-caption-letter-spacing)";
+                readonly lineHeight: "var(--semantic-typography-caption-line-height)";
+            };
             readonly eyebrow: {
                 readonly fontFamily: "var(--semantic-typography-eyebrow-font-family)";
                 readonly fontSize: "var(--semantic-typography-eyebrow-font-size)";

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

@@ -16,6 +16,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 +25,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';
@@ -1557,6 +1559,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 +2330,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/variables.css

@@ -273,6 +273,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

@@ -1504,6 +1504,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}",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@hirobius/design-system",
   "description": "Hirobius Design Systems Architecture: token-governed React components, documentation surfaces, and distribution tooling.",
   "private": false,
-  "version": "0.9.0",
+  "version": "0.11.0",
   "engines": {
     "node": ">=20",
     "pnpm": ">=8"
@@ -57,16 +57,10 @@
       "import": "./dist/mui.js",
       "default": "./dist/mui.js"
     },
-    "./protocol": {
-      "import": "./protocol/envelope.mjs",
-      "default": "./protocol/envelope.mjs"
-    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "protocol/envelope.mjs",
-    "protocol/figma-snapshot.schema.json",
     "hirobius.tokens.json",
     "public/hds-manifest.json"
   ],
@@ -105,6 +99,7 @@
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-toast": "^1.2.17",
     "@radix-ui/react-toggle-group": "^1.1.13",
+    "@radix-ui/react-tooltip": "^1.1.8",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "0.487.0",
@@ -178,6 +173,7 @@
     "vite": "6.4.2",
     "vite-bundle-visualizer": "^1.2.1",
     "vitest": "^4.1.0",
+    "yaml": "^2.8.1",
     "zod": "^4.4.3",
     "zustand": "^5.0.12"
   },
@@ -216,7 +212,7 @@
     "_comment:link-integrity": "check:doc-refs and check:routes both validate internal link integrity (different surfaces: doc refs vs route links). Kept dormant/manual-only to prevent pre-commit cascade.",
     "_comment:security-baseline": "check:security validates OWASP baseline patterns. Dormant/manual-only — candidate for integration into security-focused CI lane, not pretest.",
     "_comment:token-integrity": "check:css-values, check:token-structure validate token system correctness. Dormant/manual-only due to overlapping scope with check:fast and existing token validators.",
-    "_comment:editorconfig-version": "check:mojibake pins EC_VERSION=v3.7.0. The editorconfig-checker@6.1.x npm wrapper expects binary v3.7.0 but downloads the latest Go release (v3.8.0, 2026-06-25), so a fresh install fails with a version mismatch (binary != config). Pinning the download to the wrapper's expected version keeps CI + pre-commit green. Bump both together when upgrading the npm package. All editorconfig-checker calls route through check:mojibake.",
+    "_comment:editorconfig-version": "check:mojibake routes through scripts/lib/mojibake.mjs, which pins EC_VERSION=v3.7.0. The editorconfig-checker@6.1.x npm wrapper expects binary v3.7.0 but downloads the latest Go release (v3.8.0, 2026-06-25), so a fresh install fails with a version mismatch (binary != config). Pinning the download to the wrapper's expected version keeps CI + pre-commit green. Bump both together when upgrading the npm package. The wrapper also SKIPS gracefully (like check:secrets) when the binary download is network-blocked (remote agent sessions), so hooks no longer need --no-verify (#18/#52); the gate still enforces wherever the binary is present.",
     "api:check": "node scripts/audit-component-integrity.mjs --api",
     "api:update": "node scripts/audit-component-integrity.mjs --api --update-baseline",
     "assets:convert": "node scripts/convert-incoming-assets.mjs",
@@ -226,7 +222,6 @@
     "audit:sbom": "node scripts/audit-sbom.mjs",
     "audit:sidecar": "node scripts/generate-security-posture.mjs",
     "audit:style-dictionary": "bash scripts/poc/style-dictionary-poc/run.sh",
-    "bridge": "node --env-file=.env.local scripts/hds-bridge.mjs",
     "build": "pnpm sync:health && node scripts/sync-icons.mjs && vite build --configLoader native",
     "build:ssr": "vite build --ssr src/entry-server.tsx --outDir .ssr-cache --configLoader native",
     "build:prerender": "pnpm build && pnpm build:ssr && node scripts/prerender.mjs",
@@ -276,13 +271,13 @@
     "check:lockfile": "pnpm install --frozen-lockfile --offline --prefer-offline --ignore-scripts --silent 2>/dev/null || (echo 'Lockfile drift: run pnpm install' && exit 1)",
     "check:manifest-drift": "node scripts/check-manifest-drift.mjs",
     "check:micromotion": "node scripts/check-motion.mjs",
-    "check:mojibake": "EC_VERSION=v3.7.0 pnpm exec editorconfig-checker",
+    "check:mojibake": "node scripts/lib/mojibake.mjs",
     "check:mono-roles": "node scripts/check-mono-roles.mjs",
     "check:motion": "node scripts/check-reduced-motion.mjs",
     "check:page-shell": "node scripts/check-page-shell.mjs",
     "check:refs": "node scripts/check-ref-forwarding.mjs",
     "check:registry": "node scripts/check-registry.mjs",
-    "check:release": "pnpm check:full && node scripts/check-style-discipline.mjs && pnpm build && pnpm perf:budget && pnpm test:a11y && pnpm test:visual && pnpm test:responsive && pnpm test:collision && pnpm check:size",
+    "check:release": "pnpm check:full && node scripts/check-style-discipline.mjs && pnpm build && pnpm test:a11y && pnpm test:visual && pnpm test:responsive && pnpm test:collision && pnpm check:size",
     "check:routes": "node scripts/check-link-integrity.mjs --route-links-only",
     "check:secrets": "node scripts/check-secrets.mjs",
     "check:security": "node scripts/check-security-baseline.mjs",
@@ -306,11 +301,11 @@
     "docs:changelogs": "node scripts/generate-component-changelogs.mjs",
     "docs:llms": "node scripts/generate-llms-txt.mjs",
     "figma-variables": "node scripts/build-figma-variables.mjs",
-    "figma:bridge:smoke": "node scripts/figma-bridge-smoke.mjs",
     "figma:diff": "node scripts/figma-diff.mjs",
     "figma:snapshot": "node scripts/normalize-figma-snapshot.mjs",
     "figma:stream": "node scripts/llm-stream-bridge.mjs",
     "guardrail:firing-stats": "node scripts/refresh-firing-stats.mjs",
+    "harvest:design-md": "node scripts/harvest-design-md.mjs",
     "heal": "node scripts/self-heal.mjs",
     "heal:smoke": "node scripts/self-heal.mjs --smoke",
     "health-commit": "pnpm check:semantic-report && node scripts/print-health-commit.mjs",
@@ -322,7 +317,6 @@
     "manifest:generate": "node scripts/generate-manifest.mjs && node scripts/generate-component-api.mjs && node scripts/enrich-manifest.mjs",
     "manifest:project": "node scripts/generate-manifest-projection.mjs",
     "nav:generate": "node scripts/generate-nav-model.mjs",
-    "perf:budget": "node -e \"require('fs').readdirSync('.lighthouseci').filter(f=>f.startsWith('lhr-')).forEach(f=>require('fs').unlinkSync('.lighthouseci/'+f))\" 2>/dev/null; lhci collect --config=.lighthouserc.json && lhci assert --config=.lighthouserc.json; find . -maxdepth 1 -type d -name 'C:*' -exec rm -rf {} + 2>/dev/null; true",
     "prebuild": "node scripts/validate-manifest.mjs",
     "prebuild:lib": "node scripts/generate-component-api.mjs",
     "pretest": "node scripts/validate-manifest.mjs && node scripts/check-manifest-drift.mjs && node scripts/check-manifest-schema-semver.mjs && node scripts/audit-component-integrity.mjs --completeness && node scripts/check-source-canon.mjs && node scripts/check-binding-drift.mjs && node scripts/test-figma-masters-snapshot.mjs && node scripts/test-doc-pages-snapshot.mjs && node scripts/check-registry.mjs && node scripts/check-tenant-tokens.mjs && knip --no-exit-code",
@@ -330,6 +324,7 @@
     "roadmap:data": "node scripts/build-roadmap-data.mjs && node scripts/verify-roadmap-sync.mjs",
     "roadmap:verify": "node scripts/verify-roadmap-sync.mjs",
     "roadmap:watch": "node scripts/watch-roadmap.mjs",
+    "hds:new": "node scripts/scaffold-component.mjs",
     "scaffold:component": "node scripts/scaffold-component.mjs",
     "scaffold:tenant": "node scripts/scaffold-tenant.mjs",
     "sitemap:generate": "node scripts/generate-sitemap.mjs",

package/public/hds-manifest.json

@@ -2,7 +2,7 @@
   "name": "Hirobius Design System",
   "description": "Three-tier design token system for Adrian Milsap's portfolio site. Tokens flow primitive → semantic → component. All visual decisions trace back to hirobius.tokens.json.",
   "version": "1",
-  "generated": "2026-07-01T06:53:00.024Z",
+  "generated": "2026-07-03T08:57:17.539Z",
   "source": "hirobius.tokens.json",
   "format": "W3C DTCG 2025.10",
   "docs": "https://adrianmilsap.com/hds",
@@ -63,6 +63,7 @@
     "HdsCheckbox",
     "HdsRadio",
     "HdsSlider",
+    "HdsThemeProvider",
     "HdsToggle",
     "HeadingStack",
     "Icon",
@@ -986,6 +987,10 @@
         "name": "Text",
         "filePath": "src/app/components/text.tsx"
       },
+      {
+        "name": "Textarea",
+        "filePath": "src/app/components/textarea.tsx"
+      },
       {
         "name": "TextLockup",
         "filePath": "src/app/components/text-lockup.tsx"
@@ -2216,6 +2221,7 @@
       },
       "consumers": [
         "src/app/components/componentPreviewRegistry.tsx",
+        "src/app/components/hds-tooltip.tsx",
         "src/app/components/inline-code.tsx",
         "src/app/components/page-footer.tsx",
         "src/app/components/pagination.tsx",
@@ -4652,6 +4658,7 @@
         "src/app/components/dialog.tsx",
         "src/app/components/error-pattern.tsx",
         "src/app/components/foundation-swatch.tsx",
+        "src/app/components/hds-tooltip.tsx",
         "src/app/components/heading-anchor.tsx",
         "src/app/components/info-page.tsx",
         "src/app/components/nav-item.tsx",
@@ -5267,6 +5274,7 @@
         "src/app/components/combobox.tsx",
         "src/app/components/form.tsx",
         "src/app/components/input.tsx",
+        "src/app/components/textarea.tsx",
         "src/app/pages/docs/patterns/HdsField.tsx",
         "src/form/hds-form.tsx",
         "src/stories/field.stories.tsx",
@@ -6131,7 +6139,8 @@
         "src/app/components/componentPreviewRegistry.tsx",
         "src/app/components/controls.tsx",
         "src/app/components/select.test.tsx",
-        "src/app/data/hdsEditorial.tsx"
+        "src/app/data/hdsEditorial.tsx",
+        "src/stories/select.stories.tsx"
       ],
       "tokenMapping": {
         "label": "semantic.typography.small",
@@ -6865,6 +6874,77 @@
       "requiredProps": [],
       "a11yRules": []
     },
+    "HdsThemeProvider": {
+      "category": "Theming",
+      "categorySource": "jsdoc",
+      "governedCategory": true,
+      "hidden": false,
+      "docExempt": true,
+      "filePath": "src/app/context/hds-theme.tsx",
+      "description": "Renders a `data-hds` scope wrapper that carries the four theming dials as root attributes + CSS vars, and exposes them to `useHdsTheme()`.",
+      "figmaUrl": null,
+      "figmaId": null,
+      "figmaLink": "TODO:hds-master:HdsThemeProvider",
+      "tier": "primitive",
+      "preview": {
+        "exportName": "HdsThemeProvider",
+        "sizing": "panel"
+      },
+      "consumers": [
+        "src/index.ts"
+      ],
+      "tokenMapping": {},
+      "variantAxes": [],
+      "componentProperties": [],
+      "props": {
+        "as": {
+          "type": "ElementType<any, keyof IntrinsicElements>",
+          "default": "div"
+        },
+        "brand": {
+          "type": "string",
+          "optional": true
+        },
+        "className": {
+          "type": "string",
+          "optional": true
+        },
+        "density": {
+          "type": "enum",
+          "values": [
+            "comfortable",
+            "compact"
+          ],
+          "optional": true
+        },
+        "fontFamily": {
+          "type": "string",
+          "optional": true
+        },
+        "fontFamilyMono": {
+          "type": "string",
+          "optional": true
+        },
+        "style": {
+          "type": "CSSProperties",
+          "optional": true
+        },
+        "theme": {
+          "type": "enum",
+          "values": [
+            "light",
+            "dark"
+          ],
+          "optional": true
+        }
+      },
+      "allowedChildren": [
+        "*"
+      ],
+      "propConstraints": {},
+      "requiredProps": [],
+      "a11yRules": []
+    },
     "HdsPhosphor": {
       "category": "Compiler",
       "filePath": "scripts/hds-jsx-compiler.mjs",
@@ -7958,7 +8038,9 @@
       "consumers": [
         "src/app/components/asset-img.tsx",
         "src/app/components/doc-sections.tsx",
-        "src/app/data/hdsEditorial.tsx"
+        "src/app/components/hds-tooltip.tsx",
+        "src/app/data/hdsEditorial.tsx",
+        "src/stories/hds-tooltip.stories.tsx"
       ],
       "tokenMapping": {},
       "variantAxes": [],
@@ -8024,7 +8106,9 @@
       "description": "SideNav - sidebar navigation row primitive. Two levels: root — top-level section link. Full-width row using the shared nav label type style. nested — child page link. Keeps the same full-width hit area and label type treatment, with indentation handled via inner padding only. No indicator bar (reserved for HdsTocNav). Idle text = content-secondary → primary on hover/active. Accent surface fill on active state.",
       "figmaUrl": null,
       "figmaId": null,
-      "consumers": [],
+      "consumers": [
+        "src/stories/side-nav.stories.tsx"
+      ],
       "tokenMapping": {},
       "props": {},
       "allowedChildren": [
@@ -10216,6 +10300,19 @@
           "maxWidth": "60ch"
         }
       },
+      {
+        "path": "semantic.typography.caption",
+        "cssVar": "--semantic-typography-caption",
+        "type": "typography",
+        "description": "Caption / helper text. Satoshi medium, 12px, line-height 16px. Matches the Figma typography/caption text style.",
+        "composite": {
+          "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
+          "fontSize": "12px",
+          "fontWeight": "500",
+          "letterSpacing": "0em",
+          "lineHeight": "16px"
+        }
+      },
       {
         "path": "semantic.typography.eyebrow",
         "cssVar": "--semantic-typography-eyebrow",