baldart 4.76.0 → 4.77.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.77.0] - 2026-06-29
+
+**TS-aware design-system extractor + the `variant_prop` HEAD field.** The component-manifest extractor was pure-regex (zero-dep) and could not resolve TypeScript: a `type Variant = 'a'|'b'; variant: Variant` captured the alias *name* `"Variant"`, not its members, so on a TS-strict consumer (mayo) every HEAD came out with `variants: []` and ~25 with `props: {}`. Since the HEAD is the SSOT every UI agent reads for discovery, `variants: []` on a 6-variant Button induces wrong code. Separately, the variant axis was **hardcoded** to the prop name `variant` in three places — wrong for a `Chip`/`Pill` whose axis is `tone`. This release makes the extractor **optionally TS-aware** (it borrows the consumer's own `typescript`, resolved from the repo root) and adds a deterministic **`variant_prop`** field naming the real axis.
+
+**MINOR** — adds capability + a new deterministic HEAD field. **No new `baldart.config.yml` key** (rides on `features.has_design_system`), so the schema-change propagation rule does NOT apply. **Zero regression**: when typescript is absent (Codex / greenfield / non-TS stack) or a file fails to parse, the extractor falls back to the existing zero-dep regex path per file; legacy HEADs (pre-v4.77.0, no `variant_prop`) default the render axis to `'variant'` so existing registries render identically until a one-time re-extract backfills the field.
+
+### Added
+
+- **`extract-ts.mjs`** (`framework/.claude/skills/design-system-init/scripts/extract-ts.mjs`) — optional TS-aware resolver. Probes `typescript` via `require.resolve('typescript', { paths: [process.cwd()] })` (the **consumer's** dependency, not BALDART's), parses syntactically with `ts.createSourceFile` (no tsconfig / Program / TypeChecker — fast, in-file, deterministic), and resolves type **aliases**, **unions**, **intersections**, **`Omit`/`Pick`**, interface `extends`, and `forwardRef`/`memo`/`React.FC` wrappers. Opaque / imported types (`ComponentPropsWithoutRef<'button'>`, `HTMLAttributes`) stay **empty** — never a DOM-attribute dump. Per-file try/catch → regex fallback. The typescript-free `computeVariantProp` / `pureStringLiteralUnion` / `literalMembers` are **shared** with the regex path so the axis ranking is byte-identical on both.
+- **`variant_prop` deterministic HEAD field** — which prop IS the variant axis, ranked `variant > tone > intent > kind > appearance > state > status > color > severity` (else the sole literal-union prop, else `''`). `variants` is the literal members of `variant_prop`'s type. Emitted by `serialize-spec.mjs`, consumed as the axis key by `render-manifest.mjs` (`entriesFor`) and `compile-ds-cards.mjs` (row label) instead of the hardcoded `'variant'`. Documented in `component-manifest-schema.md` (SSOT), the canonical `component-spec.template.md`, the `/design-system-init` `/ds-new` `/ds-edit` skills, `COMPONENT-MANIFEST-LAYER.md`, and `design-system-protocol.md`.
+
+### Fixed
+
+- **`render-manifest.mjs parseHead` now reads block-style `variants`** — the serializer emits non-empty `variants` as a YAML **block list** (`variants:\n  - a`), but `parseHead` only matched flow `variants: [a, b]`, so on any real serialized spec the variant matrix read `[]` (every component collapsed to a single `--default` entry). It now accepts both block and flow forms; with `variant_prop` this makes the render/publish axis work end-to-end (a `Chip` mounts `{ tone }` per variant).
+
+### Changed
+
+- **`extract-manifest.mjs extractFile`** — TS-path-first with per-file regex fallback; emits `variant_prop`; `extractVariants(props)` generalized to `extractVariantsFor(props, variantProp)` (the axis is no longer hardcoded to `variant`).
+- **`/design-system-init` UPGRADE mode** (`SKILL.md`) — a one-line **pre-v4.77.0 backfill** note: re-extract all components ignoring `source_sha` once to populate `variant_prop` + resolve aliases, agentic fields preserved by the existing non-clobber rule.
+
+## [4.76.1] - 2026-06-26
+
+**`/design-system-init` offers a render surface (opt-in Storybook scaffold).** The render harness (Stage C) needs a Storybook, and a registry-only project has none — so the harness was a silent no-op with nowhere to go. Now `/design-system-init`, after scaffolding the registry, OFFERS (default-NO, JS/TS stacks only) to run the **official `npx storybook init`** so the harness has a surface. It **never hand-writes a per-stack render surface and never auto-wires the project's providers** — that "auto-provider-shim" is the refuted false-fidelity trap; instead it leaves a `.storybook/preview` decorator TODO so **the user owns the context-shimming** (theme/i18n/router), which is how Storybook does it correctly. `/ds-render`'s no-op message now points here. Declined / Codex / non-JS → skipped (publish still works via static-spec cards).
+
+**PATCH** — opt-in, no behaviour change for projects that decline or already have Storybook; no new config key.
+
+### Changed
+- **`/design-system-init` step 7b** (`framework/.claude/skills/design-system-init/SKILL.md`) — opt-in `npx storybook init` offer + the user-owned-decorator TODO; cross-ref `/ds-render`.
+- **`/ds-render` no-Storybook message** (`framework/.claude/skills/ds-render/SKILL.md`) — points to the init offer instead of a dead no-op.
+
 ## [4.76.0] - 2026-06-26
 
 **Closed-loop design system: BALDART ⇄ Claude Design.** BALDART owns the design system; Claude Design is where designers draw mockups. The two **diverge** over time — v4.75 made every new mockup born on the project's tokens, but that alignment decays as the in-repo registry evolves and the satellite stays frozen. This release adds the machinery to keep them in sync with **ONE authority** (the in-repo registry — `.tokens.json` + `components/<Name>.md` HEAD + INDEX/Selection-Policy + `ds-gate`); Claude Design is a **satellite mirror**, never a 2nd SSOT. Planned via a multi-agent workflow (map → per-axis design → adversarial refutation → completeness/SSOT critic → synthesis) which **refuted** the obvious-but-wrong pieces before any code.

package/VERSION

@@ -1 +1 @@
-4.76.0
+4.77.0

package/framework/.claude/skills/design-system-init/SKILL.md

@@ -104,10 +104,19 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    extractor (`scripts/extract-manifest.mjs` via Bash) over
    `${paths.components_primitives}` (+ `${paths.components_root}/shared`) to read
    from TS types: exported name, `source`, `source_sha`, `props`
-   ({type,required,default}), `variants` (literal union), `composes` (in-registry
-   imports), `category` (import-fan-in heuristic). **This half runs with NO
-   subagent** — it is the Codex-portable path. Empty results on a non-TS stack are
-   acceptable (advisory), never a failure.
+   ({type,required,default}), `variant_prop` (which prop is the variant axis,
+   ranked), `variants` (literal members of the axis), `composes` (in-registry
+   imports), `category` (import-fan-in heuristic). When `typescript` is resolvable
+   from the consumer root the extractor is **TS-aware** (resolves aliases / unions /
+   intersections / `Omit` / `Pick`); else it falls back to regex per file. **This
+   half runs with NO subagent** — it is the Codex-portable path. Empty results on a
+   non-TS stack are acceptable (advisory), never a failure.
+   - **Pre-v4.77.0 backfill (UPGRADE):** a registry whose HEADs were generated
+     before v4.77.0 lacks `variant_prop` and may have unresolved aliases. Re-extract
+     ALL components **ignoring `source_sha`** once (it is cheap + deterministic),
+     then re-serialize — non-empty agentic fields are preserved by the existing
+     non-clobber rule. The render harness defaults the axis to `'variant'` until
+     then, so an un-backfilled registry still renders correctly.
 4. **Enrich — AGENTIC, AS DATA (never hand-write YAML).** Launch `doc-reviewer`
    to produce the agentic fields (`purpose`, `a11y`, `token_bindings`, `related`,
    `must_rules`, **plus the selection-policy fields `canonical_for` / `use_when` /
@@ -234,9 +243,28 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    `paths.design_system: <target>`, and (when tokens bootstrapped)
    `paths.design_tokens` + `design_tokens.outputs`. Use the same YAML write path
    as `configure` (preserve user values, never clobber unrelated keys).
+7b. **Offer a render surface — OPT-IN, never forced (closed-loop Stage C enabler).**
+   A registry documents components but cannot RENDER them in isolation — the render
+   harness (`baldart render` / `/ds-render`) needs a Storybook. If **no `.storybook/`
+   exists** AND the stack is JS/TS (`stack.framework` is react/vue/svelte/etc.),
+   ASK the user (one consolidated question, default-NO): *"Vuoi che inizializzi
+   Storybook così il render harness può montare i primitivi in isolamento? (serve
+   per la verifica di qualità isolata e per il render dei componenti)"*. On YES:
+   - **Delegate to the official scaffolder** — run `npx storybook init` (stack-aware;
+     installs the right `@storybook/<framework>` devDeps + writes `.storybook/main`
+     + `preview`). NEVER hand-write a per-stack render surface and NEVER auto-wire
+     the project's providers — that "auto-provider-shim" is the REFUTED false-fidelity
+     trap. Instead leave a **TODO in `.storybook/preview`**: *"add your ThemeProvider
+     / i18n provider / router here as a decorator so isolated primitives render with
+     real context"* — **the user owns the decorators** (that is how Storybook does the
+     context-shimming correctly).
+   - On Codex / non-JS stack / user declines → skip silently; the harness simply
+     stays a no-op (publish still works via static-spec cards). This is an offer, not
+     a requirement.
 8. **Print next-steps.** Specs needing agentic review (empty fields), the
    round-trip token diff if non-empty, suggested follow-up (`/design-review` on a
-   key route).
+   key route); if Storybook was initialized, the `.storybook/preview` decorator TODO
+   + `/ds-render` to render the primitives.
 
 ## Workflow
 
@@ -249,8 +277,9 @@ precedence caveats: `framework/agents/effort-protocol.md`.
    node .framework/framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs \
      --roots <primitives>,<shared> --json
    ```
-   It emits, per component: `name`, `source`, `source_sha`, `props`, `variants`,
-   `composes`, `category`. Empty fields on a non-TS stack are advisory, not errors.
+   It emits, per component: `name`, `source`, `source_sha`, `props`, `variant_prop`,
+   `variants`, `composes`, `category` (TS-aware when typescript is resolvable; regex
+   fallback otherwise). Empty fields on a non-TS stack are advisory, not errors.
 
 3. **Agentic enrichment (`doc-reviewer`).** Fill `purpose`, `a11y`,
    `token_bindings`, `related`, `must_rules`, and the selection-policy fields

package/framework/.claude/skills/design-system-init/scripts/compile-ds-cards.mjs

@@ -64,7 +64,8 @@ function loadTokens(file) {
 function isColor(v) { return /^#([0-9a-f]{3,8})$|^(rgb|hsl|oklch|color)\(/i.test(String(v).trim()); }
 
 function card({ spec, group, tokens }) {
-  const variantRows = (spec.variants.length ? spec.variants : ['—']).map((v) => `<tr><td>variant</td><td><code>${esc(v)}</code></td></tr>`).join('');
+  const axisLabel = spec.variant_prop || 'variant';
+  const variantRows = (spec.variants.length ? spec.variants : ['—']).map((v) => `<tr><td>${esc(axisLabel)}</td><td><code>${esc(v)}</code></td></tr>`).join('');
   const propRows = Object.entries(spec.props || {}).map(([p, d]) => `<tr><td><code>${esc(p)}</code></td><td><code>${esc(d.type)}</code></td><td>${esc(d.default)}</td></tr>`).join('');
   // Token swatches the component declares (token_bindings would be richer; v1 shows the project palette subset by colour).
   const swatches = Object.entries(tokens).filter(([, v]) => isColor(v)).slice(0, 24)

package/framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs

@@ -19,6 +19,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { TS_AVAILABLE, extractPropsTs, computeVariantProp } from './extract-ts.mjs';
 
 function arg(name, def = '') {
   const i = process.argv.indexOf(name);
@@ -97,9 +98,9 @@ function extractProps(src, name) {
   return props;
 }
 
-/** Variants = literal union of the `variant` prop. */
-function extractVariants(props) {
-  const v = props.variant && props.variant.type;
+/** Variants = literal union of the variant-axis prop (`variant_prop`). */
+function extractVariantsFor(props, variantProp) {
+  const v = variantProp && props[variantProp] && props[variantProp].type;
   if (!v) return [];
   const lits = [...v.matchAll(/'([^']+)'|"([^"]+)"/g)].map((m) => m[1] || m[2]);
   return lits;
@@ -129,7 +130,17 @@ export function extractFile(file) {
   try { src = fs.readFileSync(file, 'utf8'); } catch (_) { return null; }
   const name = exportedName(src, file);
   if (!name) return null;
-  const props = extractProps(src, name);
+  // TS-aware path first (resolves aliases/unions/intersections/Omit/Pick); on any
+  // miss it returns null and we fall back to the zero-dep regex path for THIS file.
+  let props, variantProp, variants;
+  const tsOut = TS_AVAILABLE ? extractPropsTs(src, name, file) : null;
+  if (tsOut) {
+    ({ props, variantProp, variants } = tsOut);
+  } else {
+    props = extractProps(src, name);
+    variantProp = computeVariantProp(props);          // shared rule — identical on both paths
+    variants = extractVariantsFor(props, variantProp);
+  }
   return {
     name,
     source: path.relative(process.cwd(), file),
@@ -137,7 +148,8 @@ export function extractFile(file) {
     status: 'stable',
     category: 'primitive',
     props,
-    variants: extractVariants(props),
+    variant_prop: variantProp,
+    variants,
     composes: extractComposes(src).filter((c) => c !== name),
   };
 }

package/framework/.claude/skills/design-system-init/scripts/extract-ts.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+// TS-aware component-manifest extraction (since v4.77.0).
+//
+// OPTIONAL companion to the zero-dep regex extractor (extract-manifest.mjs). It
+// resolves TypeScript type aliases / unions / intersections / Omit / Pick in a
+// component's prop type — the cases the pure-regex path cannot see
+// (`type Variant = 'a'|'b'; variant: Variant` captures the alias NAME, not its
+// members). The fix is SYNTACTIC: it parses the file with `ts.createSourceFile`
+// (no Program / TypeChecker / tsconfig — fast, in-file, deterministic) and walks
+// the AST. Opaque / imported types (`ComponentPropsWithoutRef<'button'>`,
+// `HTMLAttributes`) stay EMPTY — we never dump DOM attributes.
+//
+// Reliability contract (the whole reason this is a separate, probed module):
+//   - `typescript` is the CONSUMER's dependency, not BALDART's. It is resolved
+//     from `process.cwd()` (the repo root the extractor runs against), NOT from
+//     this script's location inside `.framework/` where it is absent.
+//   - When typescript is unavailable (Codex / greenfield / non-TS stack) OR the
+//     file fails to parse/traverse, `extractPropsTs` returns `null` and the
+//     caller falls back to the regex path for THAT file — zero regression.
+//   - `computeVariantProp` / `pureStringLiteralUnion` / `literalMembers` carry NO
+//     typescript dependency and are SHARED with the regex path, so the
+//     variant-axis ranking rule is byte-identical on both paths (determinism).
+//
+// This module imports NOTHING from extract-manifest.mjs (one-way, no cycle).
+// Schema: framework/agents/component-manifest-schema.md.
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// --- typescript probe: resolve from the CONSUMER root (process.cwd()), not from
+// this script's location inside .framework/ (where typescript is not installed). ---
+let ts = null;
+try {
+  ts = require(require.resolve('typescript', { paths: [process.cwd()] }));
+} catch (_) {
+  ts = null;
+}
+
+/** True when the consumer has `typescript` resolvable; else the TS path no-ops. */
+export const TS_AVAILABLE = !!ts;
+
+// === Shared, typescript-FREE helpers (used by BOTH the TS and regex paths) ===
+
+/** Variant-axis ranking: which prop name wins when several are literal unions. */
+const RANK = ['variant', 'tone', 'intent', 'kind', 'appearance', 'state', 'status', 'color', 'severity'];
+
+/** A type text that is a pure union (or single) of string literals: `'a' | 'b'`. */
+export function pureStringLiteralUnion(typeText) {
+  if (!typeText) return false;
+  const parts = String(typeText).split('|').map((s) => s.trim()).filter(Boolean);
+  if (!parts.length) return false;
+  return parts.every((p) => /^'[^']*'$/.test(p) || /^"[^"]*"$/.test(p));
+}
+
+/** The string-literal members of a union type text, in source order. */
+export function literalMembers(typeText) {
+  if (!typeText) return [];
+  return [...String(typeText).matchAll(/'([^']*)'|"([^"]*)"/g)].map((m) => (m[1] !== undefined ? m[1] : m[2]));
+}
+
+/**
+ * The variant-axis prop name for a props map. A candidate is any prop whose
+ * resolved type is a pure string-literal union; the winner is the first by RANK,
+ * else the sole candidate, else '' (no resolvable axis). This is the single rule
+ * shared by the TS and regex paths — never fork it.
+ */
+export function computeVariantProp(props) {
+  if (!props || typeof props !== 'object') return '';
+  const candidates = Object.keys(props).filter((k) => pureStringLiteralUnion(props[k] && props[k].type));
+  if (!candidates.length) return '';
+  for (const r of RANK) if (candidates.includes(r)) return r;
+  return candidates.length === 1 ? candidates[0] : '';
+}
+
+// === TS path (no-ops entirely when typescript is unavailable) ===
+
+const MAX_DEPTH = 8; // alias-recursion cap (with `seen`, prevents pathological/cyclic blowups)
+
+/** Map of top-level type aliases + interfaces declared IN this file (by name). */
+function buildDeclMap(sf) {
+  const map = new Map();
+  for (const st of sf.statements) {
+    if ((ts.isTypeAliasDeclaration(st) || ts.isInterfaceDeclaration(st)) && st.name) {
+      map.set(st.name.text, st);
+    }
+  }
+  return map;
+}
+
+function paramTypeOfFunction(fn) {
+  return (fn.parameters && fn.parameters[0] && fn.parameters[0].type) || null;
+}
+
+/** React.FC<P> / FC<P> / FunctionComponent<P> → the first type argument (P). */
+function propsFromComponentTypeAnnotation(typeNode) {
+  if (!ts.isTypeReferenceNode(typeNode) || !typeNode.typeArguments || !typeNode.typeArguments.length) return null;
+  const tn = typeNode.typeName;
+  const simple = ts.isQualifiedName(tn) ? tn.right.text : tn.text;
+  if (simple === 'FC' || simple === 'FunctionComponent') return typeNode.typeArguments[0];
+  return null;
+}
+
+/** Locate the exported component `name` and return the TypeNode of its props. */
+function findComponentParamType(sf, name) {
+  let fallback = null;
+  for (const st of sf.statements) {
+    // function Name(props: T) / export [default] function Name(props: T)
+    if (ts.isFunctionDeclaration(st)) {
+      const isDefault = st.modifiers && st.modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+      if ((st.name && st.name.text === name) || (!st.name && isDefault)) {
+        const t = paramTypeOfFunction(st);
+        if (t) return t;
+      }
+      continue;
+    }
+    // export default Name; (anonymous arrow assigned to const handled below)
+    if (ts.isVariableStatement(st)) {
+      for (const decl of st.declarationList.declarations) {
+        if (!decl.name || !ts.isIdentifier(decl.name) || decl.name.text !== name) continue;
+        // const Name: React.FC<P> = ...
+        if (decl.type) {
+          const t = propsFromComponentTypeAnnotation(decl.type);
+          if (t) return t;
+        }
+        const init = decl.initializer;
+        if (!init) continue;
+        // forwardRef<Ref, Props>(...) / memo<Props>(...)
+        if (ts.isCallExpression(init)) {
+          const callee = init.expression;
+          const calleeName = ts.isPropertyAccessExpression(callee)
+            ? callee.name.text
+            : (ts.isIdentifier(callee) ? callee.text : '');
+          if (init.typeArguments && init.typeArguments.length) {
+            if (calleeName === 'forwardRef' && init.typeArguments[1]) return init.typeArguments[1];
+            if (calleeName === 'memo' && init.typeArguments[0]) return init.typeArguments[0];
+          }
+          // unwrap the first function argument (forwardRef/memo wrapping a component fn)
+          const fn = init.arguments && init.arguments[0];
+          if (fn && (ts.isArrowFunction(fn) || ts.isFunctionExpression(fn))) {
+            const t = paramTypeOfFunction(fn);
+            if (t) return t;
+          }
+        }
+        if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+          const t = paramTypeOfFunction(init);
+          if (t) return t;
+        }
+      }
+    }
+  }
+  return fallback;
+}
+
+/**
+ * If a prop's type is (via single-file type aliases) a PURE string-literal union,
+ * return its expanded text (`'a' | 'b'`); else null. This is what makes
+ * `variant: Variant` (where `type Variant = 'a'|'b'`) resolve to the members — the
+ * core alias-resolution the regex path cannot do. Interfaces can't be a literal
+ * union, so only type-alias references are followed.
+ */
+function unionLiteralText(node, ctx, seen) {
+  const { declMap } = ctx;
+  if (!node) return null;
+  if (ts.isParenthesizedTypeNode(node)) return unionLiteralText(node.type, ctx, seen);
+  if (ts.isLiteralTypeNode(node) && node.literal && ts.isStringLiteral(node.literal)) return `'${node.literal.text}'`;
+  if (ts.isUnionTypeNode(node)) {
+    const parts = node.types.map((t) => unionLiteralText(t, ctx, seen));
+    return parts.every((p) => p !== null) ? parts.join(' | ') : null;
+  }
+  if (ts.isTypeReferenceNode(node)) {
+    const tn = node.typeName;
+    const simple = ts.isQualifiedName(tn) ? tn.right.text : tn.text;
+    if (declMap.has(simple) && !seen.has(simple)) {
+      const decl = declMap.get(simple);
+      if (ts.isTypeAliasDeclaration(decl)) {
+        const next = new Set(seen); next.add(simple);
+        return unionLiteralText(decl.type, ctx, next);
+      }
+    }
+  }
+  return null;
+}
+
+/** PropertySignature members of a TypeLiteral / InterfaceDeclaration body. */
+function membersOf(node, ctx) {
+  const { sf } = ctx;
+  const out = {};
+  const members = node.members || [];
+  for (const m of members) {
+    if (!ts.isPropertySignature(m) || !m.name) continue;
+    const pname = (ts.isIdentifier(m.name) || ts.isStringLiteral(m.name)) ? m.name.text : m.name.getText(sf);
+    // Resolve aliased literal unions to their members; else keep the raw type text.
+    const resolved = m.type ? unionLiteralText(m.type, ctx, new Set()) : null;
+    const type = resolved || (m.type ? m.type.getText(sf).replace(/\s+/g, ' ').trim() : 'any');
+    out[pname] = { type, required: !m.questionToken };
+  }
+  return out;
+}
+
+/** String-literal keys named by an Omit/Pick second argument (`'a'` or `'a'|'b'`). */
+function extractKeyLiterals(node) {
+  if (!node) return [];
+  if (ts.isLiteralTypeNode(node) && node.literal && ts.isStringLiteral(node.literal)) return [node.literal.text];
+  if (ts.isUnionTypeNode(node)) return node.types.flatMap((t) => extractKeyLiterals(t));
+  return [];
+}
+
+/** Resolve a TypeNode to `{ [prop]: { type, required } }` — syntactic, in-file only. */
+function resolveType(node, ctx, depth, seen) {
+  const { declMap } = ctx;
+  if (!node || depth > MAX_DEPTH) return {};
+  if (ts.isParenthesizedTypeNode(node)) return resolveType(node.type, ctx, depth + 1, seen);
+
+  if (ts.isInterfaceDeclaration(node)) {
+    const out = {};
+    // `extends` heritage first (own members override below).
+    for (const hc of node.heritageClauses || []) {
+      for (const et of hc.types || []) {
+        const exprName = et.expression && et.expression.text;
+        if (exprName && declMap.has(exprName) && !seen.has(exprName)) {
+          const next = new Set(seen); next.add(exprName);
+          Object.assign(out, resolveType(declMap.get(exprName), ctx, depth + 1, next));
+        }
+      }
+    }
+    Object.assign(out, membersOf(node, ctx));
+    return out;
+  }
+
+  if (ts.isTypeLiteralNode(node)) return membersOf(node, ctx);
+
+  if (ts.isIntersectionTypeNode(node)) {
+    const out = {};
+    for (const t of node.types) {
+      const m = resolveType(t, ctx, depth + 1, seen);
+      for (const k of Object.keys(m)) {
+        out[k] = out[k] ? { type: out[k].type, required: out[k].required || m[k].required } : m[k];
+      }
+    }
+    return out;
+  }
+
+  if (ts.isUnionTypeNode(node)) {
+    const arms = node.types.map((t) => resolveType(t, ctx, depth + 1, seen)).filter((m) => Object.keys(m).length);
+    if (!arms.length) return {};
+    const out = {};
+    for (const k of new Set(arms.flatMap((m) => Object.keys(m)))) {
+      const present = arms.filter((m) => m[k]);
+      const inAll = present.length === arms.length;
+      const requiredInAll = inAll && present.every((m) => m[k].required);
+      out[k] = { type: present[0][k].type, required: requiredInAll };
+    }
+    return out;
+  }
+
+  if (ts.isTypeReferenceNode(node)) {
+    const tn = node.typeName;
+    const simple = ts.isQualifiedName(tn) ? tn.right.text : tn.text;
+    if ((simple === 'Omit' || simple === 'Pick') && node.typeArguments && node.typeArguments.length >= 2) {
+      const base = resolveType(node.typeArguments[0], ctx, depth + 1, seen);
+      const keys = new Set(extractKeyLiterals(node.typeArguments[1]));
+      const out = {};
+      for (const k of Object.keys(base)) {
+        const inSet = keys.has(k);
+        if (simple === 'Omit' ? !inSet : inSet) out[k] = base[k];
+      }
+      return out;
+    }
+    if (declMap.has(simple) && !seen.has(simple)) {
+      const next = new Set(seen); next.add(simple);
+      const decl = declMap.get(simple);
+      const target = ts.isInterfaceDeclaration(decl) ? decl : decl.type;
+      return resolveType(target, ctx, depth + 1, next);
+    }
+    return {}; // opaque / imported — never enumerate (no DOM-attr dump)
+  }
+
+  return {};
+}
+
+/**
+ * TS-aware extraction for ONE component. Returns `{ props, variantProp, variants }`
+ * on success, or `null` to signal the caller to use the regex path for this file
+ * (typescript unavailable, no resolvable param type, or any parse/traversal error).
+ */
+export function extractPropsTs(src, name, fileName) {
+  if (!ts) return null;
+  try {
+    const kind = /\.tsx$/.test(fileName || '') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    const sf = ts.createSourceFile(fileName || 'component.tsx', src, ts.ScriptTarget.Latest, true, kind);
+    const typeNode = findComponentParamType(sf, name);
+    if (!typeNode) return null; // untyped param → let regex try the `${name}Props` convention
+    const props = resolveType(typeNode, { sf, declMap: buildDeclMap(sf) }, 0, new Set());
+    if (!props || typeof props !== 'object') return null;
+    const variantProp = computeVariantProp(props);
+    const variants = variantProp ? literalMembers(props[variantProp].type) : [];
+    return { props, variantProp, variants };
+  } catch (_) {
+    return null;
+  }
+}

package/framework/.claude/skills/design-system-init/scripts/render-manifest.mjs

@@ -45,13 +45,27 @@ function parseHead(md) {
   if (!name) return null;
   const source = scalar('source');
 
-  // variants: [a, b, c]  (the enumerated literal union of the `variant` prop)
+  // variants — the enumerated literal union of the variant-axis prop. The
+  // serializer emits a BLOCK list for non-empty arrays (`variants:\n  - a`) and
+  // flow `[]` when empty, so accept BOTH block and flow `[a, b]` here.
   let variants = [];
-  const vr = head.match(/^variants:\s*\[(.*?)\]/m);
-  if (vr && vr[1].trim()) {
-    variants = vr[1].split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  const vFlow = head.match(/^variants:\s*\[(.*?)\]/m);
+  if (vFlow && vFlow[1].trim()) {
+    variants = vFlow[1].split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  } else {
+    const vBlock = head.match(/^variants:\s*\n((?:[ \t]+-[ \t]*.+\n?)+)/m);
+    if (vBlock) {
+      variants = vBlock[1].split('\n')
+        .map((l) => { const m2 = l.match(/^\s*-\s*(.+?)\s*$/); return m2 ? m2[1].replace(/^["']|["']$/g, '') : null; })
+        .filter(Boolean);
+    }
   }
 
+  // variant_prop: which prop is the variant axis (since v4.77.0). Legacy HEADs
+  // (pre-v4.77.0) lack it → default to 'variant' when variants are present, so
+  // existing registries keep the same axis/rendering.
+  const variant_prop = scalar('variant_prop') || (variants.length ? 'variant' : '');
+
   // props block: each line `  <name>: { type: "...", required: ..., default: ... }`
   const props = {};
   const pm = head.match(/^props:\s*\n([\s\S]*?)(?=^\S|\n# ===|\Z)/m);
@@ -68,7 +82,7 @@ function parseHead(md) {
       props[pname] = { type: strip(typeM && typeM[1]) || '', default: strip(defM && defM[1]) };
     }
   }
-  return { name, source, variants, props };
+  return { name, source, variant_prop, variants, props };
 }
 
 // Enumerable iff the prop type is a literal union of string/number/boolean
@@ -89,7 +103,10 @@ function enumMembers(type) {
 
 function entriesFor(spec, full) {
   const { name, variants, props } = spec;
-  const others = Object.keys(props).filter((p) => p !== 'variant');
+  // The variant axis is the prop named by `variant_prop` (default 'variant' for
+  // legacy HEADs) — NOT hardcoded, so a Chip whose axis is `tone` mounts `tone`.
+  const axis = spec.variant_prop || (variants.length ? 'variant' : '');
+  const others = Object.keys(props).filter((p) => p !== axis);
   const baseFixture = {};
   for (const p of others) if (props[p].default !== undefined && props[p].default !== null) baseFixture[p] = props[p].default;
 
@@ -97,8 +114,8 @@ function entriesFor(spec, full) {
   const variantValues = variants.length ? variants : ['default'];
   let entries = variantValues.map((v) => ({
     id: `${name}--${v}`,
-    props: { ...(variants.length ? { variant: v } : {}), ...baseFixture },
-    axis: 'variant',
+    props: { ...(variants.length && axis ? { [axis]: v } : {}), ...baseFixture },
+    axis: axis || 'variant',
   }));
 
   if (full) {
@@ -150,7 +167,7 @@ function main() {
       spec = parseHead(fs.readFileSync(path.join(dir, file), 'utf8'));
     } catch (_) { spec = null; }
     if (!spec) { skipped.push(file); continue; }
-    components.push({ name: spec.name, source: spec.source || null, variants: spec.variants, entries: entriesFor(spec, full) });
+    components.push({ name: spec.name, source: spec.source || null, variant_prop: spec.variant_prop || null, variants: spec.variants, entries: entriesFor(spec, full) });
   }
 
   emit({

package/framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs

@@ -16,8 +16,9 @@
 // Usage:
 //   node serialize-spec.mjs --bundle bundle.json --out-dir <dir> [--index <path>] [--brand <name>]
 //   bundle.json = { brand?, components: [ { name, source, source_sha, status,
-//     category, props:{}, variants:[], composes:[], purpose, token_bindings:[],
-//     a11y, related:[], must_rules:[], last_verified, owner, prose } ] }
+//     category, props:{}, variant_prop, variants:[], composes:[], purpose,
+//     token_bindings:[], a11y, related:[], must_rules:[], last_verified, owner,
+//     prose } ] }
 // Exits non-zero if any emitted HEAD fails to re-parse (when js-yaml is present).
 
 import fs from 'node:fs';
@@ -72,6 +73,7 @@ export function emitHead(c) {
   L.push(`status: ${scalar(c.status || 'stable')}`);
   L.push(`category: ${scalar(c.category || 'primitive')}`);
   L.push(propsBlock(c.props));
+  L.push(`variant_prop: ${scalar(c.variant_prop ?? '')}`);
   L.push(list('variants', c.variants));
   L.push(list('composes', c.composes));
   L.push('# AGENTIC (curated by doc-reviewer — preserved across regeneration):');

package/framework/.claude/skills/ds-edit/SKILL.md

@@ -110,7 +110,8 @@ Each step is a delegation. Read the cited SSOT; do not paraphrase it.
    describe the required source change as a TODO and require the user to apply it.
 3. **Re-extract the deterministic HEAD.**
    `node .framework/framework/.claude/skills/design-system-init/scripts/extract-one.mjs --source <path.tsx> --json`
-   → the updated `props` / `variants` / `composes` / `source_sha` from the new source.
+   → the updated `props` / `variant_prop` / `variants` / `composes` / `source_sha`
+   from the new source (TS-aware: resolves type aliases / unions / `Omit` / `Pick`).
 4. **Re-verify the agentic fields.** DELEGATE `doc-reviewer` to update ONLY what the
    change affects (`must_rules` / `a11y` / `token_bindings` / `purpose`) and keep the
    rest. Existing values are preserved by the serializer; never blank a field you

package/framework/.claude/skills/ds-new/SKILL.md

@@ -102,8 +102,8 @@ Each step is a delegation. Read the cited SSOT; do not paraphrase it.
    path. The skill itself NEVER writes component source.
 3. **Extract the deterministic HEAD.**
    `node .framework/framework/.claude/skills/design-system-init/scripts/extract-one.mjs --source <path.tsx> --json`
-   → `name`/`source`/`source_sha`/`props`/`variants`/`composes` (zero-dep,
-   Codex-portable, no subagent).
+   → `name`/`source`/`source_sha`/`props`/`variant_prop`/`variants`/`composes`
+   (TS-aware when typescript resolves, else zero-dep regex; Codex-portable, no subagent).
 4. **Enrich the agentic fields AS DATA.** DELEGATE `doc-reviewer` (Task tool) to
    produce `purpose` / `token_bindings` (picked from the REAL ids in
    `${paths.design_tokens}`) / `a11y` / `related` / `must_rules` as JSON values —

package/framework/.claude/skills/ds-render/SKILL.md

@@ -43,7 +43,11 @@ Baseline `medium`. Honor an inline `effort=<level>` override.
 
 1. **Build the surface.** `baldart render build [--full]` → emits
    `render-manifest.json` (from the component HEADs) + generates the adapter render
-   surface (ephemeral `.baldart.stories.tsx`). No Storybook → STOP (clean no-op).
+   surface (ephemeral `.baldart.stories.tsx`). **No Storybook → STOP (clean no-op)**
+   and tell the user the harness needs a render surface: offer to run
+   `/design-system-init` (which proposes `npx storybook init`, opt-in — § step 7b)
+   or to `npx storybook init` directly, then re-run `/ds-render`. Never auto-install
+   Storybook from this skill.
 2. **Run the screenshot loop** (this skill owns the browser via `playwright-skill`):
    `npx storybook build -o .harness/storybook-static`, then for each story
    `iframe.html?id=<storyId>&viewMode=story` capture a PNG into `.harness/shots/`.

package/framework/agents/component-manifest-schema.md

@@ -51,11 +51,12 @@ source: components/ui/Button.tsx          # path relative to repo root
 source_sha: a1b2c3d                        # git blob sha of source at last generation (drift anchor)
 status: stable                            # stable | experimental | deprecated  (default stable; `deprecated` is a hand override)
 category: primitive                       # primitive | composite | feature      (heuristic on import fan-in; hand-overridable)
-props:                                    # from the TS prop type / interface
+props:                                    # from the TS prop type / interface (TS-aware: resolves aliases / unions / intersections / Omit / Pick)
   variant: { type: "'primary'|'ghost'|'destructive'", required: false, default: "'primary'" }
   size:    { type: "'sm'|'md'|'lg'", required: false, default: "'md'" }
   disabled: { type: boolean, required: false, default: false }
-variants: [primary, ghost, destructive]   # enumerated literal union of the `variant` prop
+variant_prop: variant                     # which prop IS the variant axis (ranked; '' if none). NOT hardcoded to `variant` — a Chip whose axis is `tone` reports `tone`.
+variants: [primary, ghost, destructive]   # enumerated literal union of the `variant_prop` type
 composes: [Slot, Spinner]                 # in-registry primitives imported by this component
 # === AGENTIC — curated by doc-reviewer; survives regeneration, never clobbered when non-empty ===
 purpose: "Primary action trigger; one primary per surface."
@@ -76,7 +77,27 @@ owner: doc-reviewer                       # curation owner (constant; documents
 
 | Origin | Fields | Rule |
 |---|---|---|
-| **Deterministic** (TS/git) | `name`, `source`, `source_sha`, `status` (default), `category` (heuristic), `props`, `variants`, `composes` | Always safe to **overwrite** on regeneration — they are derived. Extracted by a pure Node script (no agent), so the path is **portable to Codex**. |
+| **Deterministic** (TS/git) | `name`, `source`, `source_sha`, `status` (default), `category` (heuristic), `props`, `variant_prop`, `variants`, `composes` | Always safe to **overwrite** on regeneration — they are derived. Extracted by a pure Node script (no agent), so the path is **portable to Codex**. |
+
+**TS-aware extraction (since v4.77.0).** When `typescript` is resolvable from the
+consumer root, the extractor parses the source syntactically (`ts.createSourceFile`
+— no tsconfig/TypeChecker) and resolves type **aliases**, **unions**,
+**intersections**, and **`Omit`/`Pick`** in the props type (`type V='a'|'b'; variant: V`
+→ `['a','b']`). Opaque / imported types (`ComponentPropsWithoutRef<'button'>`,
+`HTMLAttributes`) stay **empty** — never a DOM-attribute dump. When typescript is
+absent (Codex / greenfield / non-TS stack) or a file fails to parse, it falls back
+to the zero-dep **regex** path for that file (today's behaviour, no regression).
+
+**`variant_prop` (the variant axis).** A prop is a variant-axis *candidate* iff its
+resolved type is a pure string-literal union; the winner is the first by the rank
+`variant > tone > intent > kind > appearance > state > status > color > severity`,
+else the sole candidate, else `''`. `variants` is the literal members of
+`variant_prop`'s type. Consumers (render harness, `@dsCard` compiler) use
+`variant_prop` as the axis key — so a `Chip` whose axis is `tone` mounts `tone`,
+not a phantom `variant`. **Legacy HEADs** (pre-v4.77.0, no `variant_prop`) **default
+the axis to `'variant'`** when `variants` is non-empty, so existing registries keep
+rendering identically; a one-time re-extract backfills the field (see
+`/design-system-init` UPGRADE mode).
 | **Agentic** (doc-reviewer) | `purpose`, `token_bindings`, `a11y`, `related`, `must_rules`, `canonical_for`, `use_when`, `selection_closed`, `last_verified`; plus `status: deprecated` as a judgment | **Never clobbered** when non-empty. Empty agentic fields = "not yet enriched", filled later by `doc-reviewer` / `ds-drift`, never auto-invented. |
 
 ### Selection-policy fields (the closed-set layer)

package/framework/agents/design-system-protocol.md

@@ -600,7 +600,7 @@ and the advisory check 6 (mirror, non-blocking):
 2. **Modified primitive ⇒ updated spec**: did the change alter a primitive's
    props / variants / accessibility behavior? If yes, the corresponding
    `components/<Name>.md` MUST be updated to match — including its **frontmatter
-   HEAD** (deterministic fields `props`/`variants`/`composes`/`source_sha`
+   HEAD** (deterministic fields `props`/`variant_prop`/`variants`/`composes`/`source_sha`
    regenerated from source; agentic fields re-verified). Stale spec =
    `DS_COMPONENT_STALE` finding, task blocked. (A prose-only spec lacking a HEAD
    is NOT stale merely for that — see `agents/component-manifest-schema.md`

package/framework/docs/COMPONENT-MANIFEST-LAYER.md

@@ -40,7 +40,7 @@ BALDART wraps the **standard** (DTCG) and owns only a thin generator — the sam
 |---|---|---|
 | HEAD schema | `framework/agents/component-manifest-schema.md` | SSOT for the frontmatter fields + read/regeneration/leniency contract |
 | Gate + cascade | `framework/agents/design-system-protocol.md` | BLOCKING reads, drift codes, token SSOT inversion, Authority Matrix |
-| Deterministic extractor | `framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs` (`extractFile`) + `extract-one.mjs` (single-component wrapper) | zero-dep Node; name/source/source_sha/props/variants/composes (Codex-portable) |
+| Deterministic extractor | `framework/.claude/skills/design-system-init/scripts/extract-manifest.mjs` (`extractFile`) + `extract-one.mjs` (single-component wrapper) + `extract-ts.mjs` (optional TS-aware resolver) | Node; name/source/source_sha/props/variant_prop/variants/composes. **TS-aware** when `typescript` resolves from the consumer root (aliases/unions/intersections/Omit/Pick); **zero-dep regex fallback** otherwise (Codex-portable) |
 | Spec template | `framework/templates/component-spec.template.md` | CANONICAL prose-body template (SSOT); serializer fills it on creation via `--prose-template` (default) |
 | Bootstrap/upgrade | `framework/.claude/skills/design-system-init/SKILL.md` | greenfield + upgrade modes |
 | Token emitters | `src/utils/token-emitters/{index,ts,css}.js` | DTCG → stack-native output (REGISTRY pattern) |
@@ -72,8 +72,11 @@ has_design_system: true (no separate flag — the manifest rides on it)
 ## 5. Invariants (do not break)
 
 - **Codex portability**: the READ path and the deterministic half (extractor,
-  `baldart tokens build`) run with **no subagent**. Only agentic enrichment needs
-  Claude; under Codex it degrades to empty/TODO fields — never a hard failure.
+  `baldart tokens build`) run with **no subagent**. The TS-aware resolver
+  (`extract-ts.mjs`) is **optional** — it uses the consumer's own `typescript` when
+  resolvable and falls back to the **zero-dep regex** path per file otherwise, so
+  Codex / non-TS stacks are unaffected. Only agentic enrichment needs Claude; under
+  Codex it degrades to empty/TODO fields — never a hard failure.
 - **No twin**: ONE artifact per component (the spec, evolved) and ONE token SSOT
   (`.tokens.json`); `tokens-reference.md` and `tokens.ts`/CSS are **generated
   views/outputs**, never hand-authored sources. The INDEX is a generated router.

package/framework/templates/component-spec.template.md

@@ -24,8 +24,9 @@ source: {{file_path}}
 source_sha: {{source_sha}}
 status: {{status}}           # stable | experimental | deprecated  (default stable)
 category: {{category}}       # primitive | composite | feature
-props: {{props_yaml}}        # name → { type, required, default }  ({} if unresolved)
-variants: {{variants_yaml}}  # [] if none / unresolved
+props: {{props_yaml}}        # name → { type, required, default }  ({} if unresolved; TS-aware: resolves aliases/unions/intersections/Omit/Pick)
+variant_prop: {{variant_prop}}  # which prop is the variant axis (ranked; '' if none / unresolved; legacy HEADs default to 'variant')
+variants: {{variants_yaml}}  # [] if none / unresolved (literal members of variant_prop's type)
 composes: {{composes_yaml}}  # in-registry primitives this imports
 # AGENTIC fields (curated by doc-reviewer — preserved across regeneration):
 purpose: "{{purpose}}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.76.0",
+  "version": "4.77.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"