baldart 4.64.0 → 4.66.0

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

@@ -0,0 +1,100 @@
+# Component Manifest + DTCG Token Layer
+
+Authoritative design, lifecycle, and invariants for the machine-readable
+component-manifest layer and the DTCG token SSOT (since v4.65.0). Companion to
+the textual SSOTs: `framework/agents/component-manifest-schema.md` (the HEAD
+schema) and `framework/agents/design-system-protocol.md` (the gate + cascade).
+
+## 1. Why this exists
+
+On a real consumer, UI component discovery was slow: the registry's `INDEX.md`
+had grown to a **33KB monolith** read in full on every UI task, there was no
+`tokens-reference.md` (tokens parsed from a large hand-authored token file), and
+**0 of ~135 components** had a per-component spec — so every "what does this
+primitive do / can I reuse it" lookup degraded to reading component **source**.
+Graphify is
+the wrong lever here: component lookup is a single-symbol query, which the
+code-graph protocol routes to LSP/Grep, not the graph.
+
+The fix is not a new layer — the framework already prescribes per-component specs
+(`components/<Name>.md`, owned by `doc-reviewer`, gated by `code-reviewer`,
+audited by `ds-drift`). It is **(a)** making those specs machine-readable and
+read **on demand**, and **(b)** giving tokens a real, interoperable SSOT.
+
+## 2. What BALDART adds vs what the stack already ships
+
+| Concern | Stack / status quo | What BALDART adds |
+|---|---|---|
+| Component contract | prose `components/<Name>.md` (often absent) | a YAML **frontmatter HEAD** — deterministic (from TS) + agentic (curated) — read on demand |
+| Discovery entry | monolithic INDEX read in full | **thin generated INDEX router** → frontmatter-first reads of only the N specs in scope |
+| Token source | ad-hoc `tokens.ts` / CSS / Tailwind | **W3C DTCG `.tokens.json`** as SSOT |
+| Token output | hand-authored | **generated** via `baldart tokens build` (own thin emitter registry — no Style Dictionary) |
+| Generation | hand-written specs that don't scale | **hybrid**: deterministic Node extractor + agentic enrichment |
+
+BALDART wraps the **standard** (DTCG) and owns only a thin generator — the same
+"wrap best-in-class, own the adapter" ethos as the i18n and graph layers.
+
+## 3. The moving parts
+
+| Piece | Path | Role |
+|---|---|---|
+| 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` | zero-dep Node; name/source/source_sha/props/variants/composes (Codex-portable) |
+| Spec template | `…/design-system-init/scripts/component-spec.template.md` | HEAD + prose scaffold |
+| 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) |
+| Token generator | `src/utils/tokens-generator.js` | parse `.tokens.json`, resolve `{aliases}`, build/isStale |
+| CLI verb | `src/commands/tokens.js` (`baldart tokens build`) | the operation skills/doctor CALL |
+| Config | `paths.design_tokens` + `design_tokens.outputs` | propagated template→configure→update→doctor |
+
+## 4. Install / adoption lifecycle
+
+```
+has_design_system: true (no separate flag — the manifest rides on it)
+        │
+        ├─ configure: autodetect .tokens.json → paths.design_tokens; propose ts/css outputs; baldart tokens build
+        │
+        ├─ /design-system-init (greenfield OR upgrade):
+        │     deterministic extract (no subagent) → agentic enrich (doc-reviewer)
+        │     → .tokens.json bootstrap + round-trip verify → thin INDEX router
+        │
+        ├─ per task: ui-expert/ui-design write the HEAD in the Post-Intervention Check
+        │            coder/architect/context-primer READ frontmatter-first
+        │
+        ├─ per merge: code-reviewer Rule 8 gates (HEAD-first; transition-lenient)
+        │
+        ├─ weekly: ds-drift (source_sha + token-output-vs-DTCG)
+        │
+        └─ doctor backfill: tokens-build (stale output) + ds-manifest-nudge (specs missing/prose-only)
+```
+
+## 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.
+- **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.
+- **Token SSOT inversion**: when `paths.design_tokens` is set, edit `.tokens.json`
+  and regenerate; a hand-edit to a generated output (output ≠ `baldart tokens
+  build`) is `DS_TOKENS_DRIFT`. Generated files carry a `baldart-generated` banner.
+- **Transition leniency (no new floor)**: a prose-only spec lacking a HEAD is
+  valid (not `DS_COMPONENT_STALE`); empty deterministic fields (non-TS stack) are
+  advisory; a missing spec for a new primitive is the same `DS_INDEX_DRIFT` as
+  before. The manifest is an upgrade target, not a stricter gate.
+- **Ownership**: `doc-reviewer` owns the agentic HEAD fields (never clobbered on
+  regeneration); the deterministic fields are regenerated from source; never
+  hand-curate them.
+- **Authority Matrix** lives in `design-system-protocol.md`, not the (generated)
+  INDEX.
+
+## 6. Adding capability later (deferred, documented)
+
+- Extra emitters (`scss`, `tailwind`, `json`) — drop a file in `token-emitters/`.
+- A git pre-commit hook to regenerate tokens on `.tokens.json` change (opt-in).
+- In-place replacement of a hand-authored `tokens.ts` (after the round-trip is
+  trusted on real consumers).
+- `framework-edit-gate` hard-deny on editing a generated token output (after one
+  release of the advisory banner).

package/framework/routines/ds-drift.routine.yml

@@ -14,24 +14,31 @@ prompt: |
   Run the weekly design-system drift check (only if `${paths.design_system}/`
   exists in the project — exit cleanly if absent):
 
-  1. **INDEX coverage**: compare `${paths.design_system}/INDEX.md` component
-     index against the actual shared-component inventory. Flag
-     `DS_INDEX_DRIFT` for any mismatch.
-  2. **Per-component accuracy**: for each `${paths.design_system}/components/<Name>.md`,
-     verify it lines up with the source file (variants, props, exported
-     constants). Flag `DS_COMPONENT_STALE` for docs not re-verified in >7
-     days where the source has changed in git.
+  1. **INDEX coverage**: the `${paths.design_system}/INDEX.md` router must list
+     every primitive that has a spec. Flag `DS_INDEX_DRIFT` for any mismatch
+     (fix by regenerating the router, never hand-editing it).
+  2. **Per-component HEAD accuracy**: for each
+     `${paths.design_system}/components/<Name>.md`, compare its frontmatter HEAD
+     against the source — `source_sha` vs the current git blob, `props`/`variants`
+     vs the TS types (schema: `framework/agents/component-manifest-schema.md`).
+     Flag `DS_COMPONENT_STALE` when `source_sha` is stale (or >7 days unverified
+     with a source change). A prose-only spec with no HEAD is an upgrade candidate
+     (recommend `/design-system-init`), NOT itself stale.
   3. **Animations reconciliation**: `${paths.design_system}/patterns/animations.md`
      must match keyframes in the project's global styles. Flag
      `DS_ANIMATIONS_DRIFT`.
-  4. **Tokens reconciliation**: when tokens source files changed, verify
-     `${paths.design_system}/tokens-reference.md` is in sync and the relevant
-     CSS custom properties still exist. Flag `DS_TOKENS_DRIFT`.
+  4. **Tokens reconciliation**: when `paths.design_tokens` is set (DTCG SSOT),
+     verify the generated outputs (`design_tokens.outputs`) + `tokens-reference.md`
+     equal `baldart tokens build` — a hand-edited generated file or a dangling
+     `token_bindings` ID is `DS_TOKENS_DRIFT`. When unset, fall back to verifying
+     the project token source vs `tokens-reference.md`.
   5. Emit a consolidated report under
      `docs/reports/{{YYYYMMDD}}-ds-drift.md`.
 
-  Apply trivial fixes inline (e.g. update an INDEX row to match the current
-  source). Anything that requires design judgement is left as a finding.
+  Apply trivial fixes inline (regenerate the INDEX router; `baldart tokens build`
+  for token-output drift; refresh a stale deterministic HEAD via the extractor).
+  Anything that requires design judgement (agentic HEAD fields, new variant
+  semantics) is left as a finding.
 
 output:
   path: docs/reports/{{YYYYMMDD}}-ds-drift.md

package/framework/templates/baldart.config.template.yml

@@ -35,6 +35,13 @@ paths:
   components_root: ""         # e.g. src/components
   global_styles: ""           # e.g. src/app/globals.css
 
+  # Design-token SSOT (since v4.65.0). The W3C DTCG `.tokens.json` file that is
+  # the SINGLE source of truth for design tokens; the stack-native artifact
+  # (tokens.ts / CSS vars) is GENERATED from it via `baldart tokens build` (see
+  # the design_tokens: block below). Only meaningful when has_design_system: true.
+  # Leave empty if the project has not adopted the DTCG SSOT (no inversion).
+  design_tokens: ""           # e.g. src/ui/tokens.tokens.json
+
   # Workflow infrastructure (set the matching `features.*` flag).
   backlog_dir: ""             # e.g. backlog
   adrs_dir: ""                # e.g. docs/decisions
@@ -312,6 +319,21 @@ graph:
   # without it, so this is an enhancement, not a requirement.
   register_mcp: false
 
+# ─── DESIGN TOKENS (DTCG) ──────────────────────────────────────────────────
+# Generation targets for the DTCG token SSOT (since v4.65.0). The source is
+# `paths.design_tokens` (a W3C DTCG `.tokens.json`). `baldart tokens build`
+# reads it, resolves `{aliases}`, and regenerates each output below. The
+# generated files carry a `baldart-generated` banner — edit `.tokens.json`, never
+# the output. Only meaningful when has_design_system: true AND
+# paths.design_tokens is set; otherwise `tokens build` is a no-op.
+design_tokens:
+  # Each output is { format, path }. format ∈ token-emitters registry
+  # (src/utils/token-emitters/: ts | css — extend by dropping a new emitter).
+  outputs: []
+  # Example:
+  #   - { format: ts,  path: src/ui/tokens.ts }
+  #   - { format: css, path: src/ui/tokens.css }
+
 # ─── TOOLCHAIN ─────────────────────────────────────────────────────────────
 # State of the curated dev toolchain. Populated by `baldart configure` / the
 # `/toolchain-bootstrap` skill. Only meaningful when `features.has_toolchain:

package/package.json

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

package/src/commands/configure.js

@@ -308,6 +308,23 @@ function detect(cwd = process.cwd()) {
     )
   );
 
+  // ---- Design-token SSOT (DTCG `.tokens.json`, since v4.65.0) -------------
+  // Detection-only: a `.tokens.json` / `.tokens` file at a conventional spot
+  // means the project already speaks DTCG. If absent we leave design_tokens
+  // empty (no inversion) — adoption is an explicit /design-system-init step,
+  // never auto-forced (the project's existing tokens.ts stays the source).
+  const designTokensPath = findFirst(
+    ...expandCandidates(
+      'tokens.tokens.json', 'design/tokens.tokens.json',
+      'src/ui/tokens.tokens.json', 'src/design-system/tokens.tokens.json',
+      'tokens.json', 'design-tokens.json'
+    ),
+    ...(designSystemPath ? [
+      path.join(designSystemPath, 'tokens.tokens.json'),
+      path.join(designSystemPath, 'tokens.json'),
+    ] : [])
+  ) || '';
+
   // ---- API docs (widened — OpenAPI, GraphQL, populated dir) --------------
   const apiIndex = findFirst('docs/references/api/index.md', 'docs/api/index.md');
   const apiSchemas = findFirst('docs/references/api/schemas.md', 'docs/api/schemas.md');
@@ -425,6 +442,7 @@ function detect(cwd = process.cwd()) {
       components_primitives: componentsPrimitives,
       components_root: componentsRoot,
       global_styles: globalStyles,
+      design_tokens: designTokensPath,
       backlog_dir: exists('backlog') ? 'backlog' : '',
       adrs_dir: countMatches('docs/decisions', /^ADR-.*\.md$/) > 0 ? 'docs/decisions' : '',
       prd_dir: exists('docs/prd') ? 'docs/prd' : '',
@@ -732,6 +750,7 @@ async function interactivePrompts(merged, detected) {
     ['components_primitives', 'UI primitives directory (e.g. src/components/ui)', () => true],
     ['components_root', 'Components root directory', () => true],
     ['global_styles', 'Global stylesheet path', () => true],
+    ['design_tokens', 'DTCG token SSOT (.tokens.json) — leave empty if not adopted', () => merged.features.has_design_system],
     ['backlog_dir', 'Backlog directory', () => merged.features.has_backlog],
     ['adrs_dir', 'ADR directory', () => merged.features.has_adrs],
     ['prd_dir', 'PRD directory', () => merged.features.has_prd_workflow],
@@ -750,6 +769,41 @@ async function interactivePrompts(merged, detected) {
     merged.paths[key] = await promptForKey(`${label}`, proposed);
   }
 
+  // ---- Design tokens (DTCG SSOT, since v4.65.0) -------------------------
+  // Only when the project adopted the DTCG source (paths.design_tokens set).
+  // The block holds the GENERATION targets; `baldart tokens build` (+ doctor
+  // backfill) regenerate them. We never invert an existing hand-authored
+  // tokens.ts here — that migration is an explicit /design-system-init step.
+  merged.design_tokens = merged.design_tokens || { outputs: [] };
+  if (merged.features.has_design_system === true && merged.paths.design_tokens) {
+    UI.section('Design tokens (DTCG SSOT → generated artifacts)');
+    const TokensGenerator = require('../utils/tokens-generator');
+    const gen = new TokensGenerator(process.cwd());
+    if (!gen.detect(merged.paths.design_tokens)) {
+      UI.info(`DTCG source \`${merged.paths.design_tokens}\` not found yet — run /design-system-init to scaffold it. Leaving design_tokens.outputs empty.`);
+    } else if (!(merged.design_tokens.outputs || []).length) {
+      // Propose the conventional outputs next to the existing token consumers.
+      const proposed = [];
+      const tsGuess = merged.paths.global_styles ? '' : 'src/ui/tokens.ts';
+      if (await UI.confirm('Generate a TypeScript token object (tokens.ts) from the DTCG source?', true)) {
+        const p = await promptForKey('  tokens.ts output path', tsGuess || 'src/ui/tokens.ts');
+        if (p) proposed.push({ format: 'ts', path: p });
+      }
+      if (await UI.confirm('Also generate a CSS custom-property sheet?', false)) {
+        const p = await promptForKey('  tokens.css output path', 'src/ui/tokens.css');
+        if (p) proposed.push({ format: 'css', path: p });
+      }
+      merged.design_tokens.outputs = proposed;
+      if (proposed.length) {
+        const res = gen.build({ source: merged.paths.design_tokens, outputs: proposed });
+        if (res.ok) UI.success(`Tokens built (${res.tokenCount}) → ${res.written.join(', ')}`);
+        else UI.warning(`Token build failed: ${res.error} (fix the .tokens.json then run \`baldart tokens build\`).`);
+      }
+    }
+  } else {
+    merged.design_tokens.outputs = merged.design_tokens.outputs || [];
+  }
+
   // ---- E2E review tuning (since v3.18.0) --------------------------------
   // Only runs when the user opted in above. Populates the e2e_review.*
   // sub-section with the severity floor, self-heal cap, pixel pre-filter

package/src/commands/doctor.js

@@ -479,6 +479,54 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on i18n probe */ }
 
+    // ---- Design-system manifest + DTCG tokens (since v4.65.0) ----------
+    // Two backfills, both gated on has_design_system (no separate flag — the
+    // manifest rides on the design-system layer). (1) "default-on + nudge":
+    // when the registry exists but specs are missing or still prose-only (no
+    // machine-readable HEAD), nudge /design-system-init. (2) token SSOT: when
+    // paths.design_tokens is set, flag generated outputs that drifted from the
+    // DTCG source (or a hand-edited generated file).
+    state.dsManifestNudge = false;
+    state.dsManifestReason = '';
+    state.tokensStale = false;
+    state.tokensStalePaths = [];
+    try {
+      if (config && !config.__malformed && config.features && config.features.has_design_system === true) {
+        const dsRoot = (config.paths && config.paths.design_system) || '';
+        if (dsRoot) {
+          const compDir = path.join(cwd, dsRoot, 'components');
+          let specs = [];
+          try { specs = fs.readdirSync(compDir).filter((f) => f.endsWith('.md')); } catch (_) { specs = []; }
+          if (specs.length === 0) {
+            state.dsManifestNudge = true;
+            state.dsManifestReason = 'no per-component specs found';
+          } else {
+            // Cheap sample: does ANY spec carry a frontmatter HEAD (starts with `---`)?
+            const structured = specs.slice(0, 8).some((f) => {
+              try { return fs.readFileSync(path.join(compDir, f), 'utf8').startsWith('---'); }
+              catch (_) { return false; }
+            });
+            if (!structured) {
+              state.dsManifestNudge = true;
+              state.dsManifestReason = 'specs are prose-only (no machine-readable HEAD)';
+            }
+          }
+        }
+        // DTCG token SSOT staleness.
+        const src = (config.paths && config.paths.design_tokens) || '';
+        const outs = (config.design_tokens && config.design_tokens.outputs) || [];
+        if (src && outs.length) {
+          const TokensGenerator = require('../utils/tokens-generator');
+          const st = new TokensGenerator(cwd).isStale({ source: src, outputs: outs });
+          if (st.stale) {
+            state.tokensStale = true;
+            state.tokensStalePaths = (st.reasons || []).map((r) => r.path);
+            state.tokensStaleError = st.error || null;
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on design-system probe */ }
+
     // ---- Auto-deploy allowlist presence (since v4.59.0) ----------------
     // Purely informational: git.auto_deploy bounds what `/new -auto-ship`
     // may execute as an OUTWARD action. An empty allowlist is the SAFE
@@ -1013,6 +1061,43 @@ function planActions(state) {
     });
   }
 
+  // ---- Design-system manifest + DTCG tokens (since v4.65.0) ----------
+  // (1) Rebuild stale generated token artifacts from the DTCG SSOT — offline,
+  // deterministic, idempotent → autoOk. (2) Nudge the manifest bootstrap when
+  // the registry is present but specs are missing/prose-only (the "default-on
+  // + nudge" behavior; informational, never auto-mutates source).
+  if (state.tokensStale) {
+    actions.push({
+      key: 'tokens-build',
+      label: state.tokensStaleError
+        ? 'Design tokens: DTCG source has an error — fix then rebuild'
+        : `Rebuild generated token artifacts from the DTCG source (${state.tokensStalePaths.join(', ')})`,
+      why: state.tokensStaleError
+        ? `paths.design_tokens is set but the DTCG source could not be parsed: ${state.tokensStaleError}. Fix the .tokens.json, then \`baldart tokens build\`.`
+        : 'The generated token output(s) drifted from the DTCG SSOT (a hand-edit to a generated file, or the source changed without a rebuild). `baldart tokens build` regenerates them (offline, no API cost). Edit `.tokens.json`, never the generated output.',
+      autoOk: !state.tokensStaleError, // a parse error needs a human; a plain rebuild is safe
+      run: async () => {
+        if (state.tokensStaleError) {
+          UI.warning(`DTCG source error: ${state.tokensStaleError}. Fix it, then run \`baldart tokens build\`.`);
+          return;
+        }
+        const tokens = require('./tokens');
+        await tokens.build({ cwd: state.cwd });
+      },
+    });
+  }
+  if (state.dsManifestNudge) {
+    actions.push({
+      key: 'ds-manifest-nudge',
+      label: `Design-system specs need a machine-readable upgrade — run /design-system-init (${state.dsManifestReason})`,
+      why: `features.has_design_system is true but ${state.dsManifestReason}. Agents fall back to reading the monolithic INDEX + component source (slow). Running /design-system-init (upgrade mode) generates the per-component frontmatter HEAD + a thin INDEX router so discovery reads small structured specs on demand. See framework/agents/component-manifest-schema.md.`,
+      autoOk: false, // a skill that reads source + enriches — never run unattended from doctor
+      run: async () => {
+        UI.info('Run `/design-system-init` in your editor to upgrade the per-component specs to the machine-readable HEAD and regenerate the thin INDEX router. See framework/docs/COMPONENT-MANIFEST-LAYER.md.');
+      },
+    });
+  }
+
   // Auto-deploy allowlist (since v4.59.0). Advisory print-only — surfaced ONLY
   // when the allowlist is non-empty (the safe default of empty/unset opens
   // nothing, so it warrants no nag). Reminds the user that `/new -auto-ship`

package/src/commands/tokens.js

@@ -0,0 +1,80 @@
+/**
+ * `baldart tokens build` — regenerate the stack-native token artifacts from the
+ * DTCG SSOT (since v4.65.0).
+ *
+ * The design-token source of truth is the DTCG `.tokens.json` at
+ * `paths.design_tokens`; the artifacts agents/components consume (tokens.ts, a
+ * CSS custom-property sheet) are GENERATED from it and carry a
+ * `baldart-generated` banner. This verb is what the `/design-system-init` skill,
+ * `baldart doctor`, and (later) a git hook CALL — none of them reimplement the
+ * generation (the SSOT for that is `src/utils/tokens-generator.js`).
+ *
+ * Config consumed (baldart.config.yml):
+ *   paths.design_tokens      → the DTCG source (.tokens.json)
+ *   design_tokens.outputs[]  → [{ format: ts|css, path: <file> }]
+ *
+ * Always safe: no source / no outputs → a clear no-op message, exit 0. A bad
+ * DTCG file or a write failure → exit 1 with the reason (it IS a build step).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const UI = require('../utils/ui');
+const TokensGenerator = require('../utils/tokens-generator');
+
+const CONFIG_FILE = 'baldart.config.yml';
+
+function loadConfig(cwd) {
+  const full = path.join(cwd, CONFIG_FILE);
+  try { return yaml.load(fs.readFileSync(full, 'utf8')) || {}; }
+  catch (_) { return null; }
+}
+
+async function tokensBuild(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const json = !!opts.json;
+  const config = loadConfig(cwd);
+
+  const emit = (obj, exit = 0) => {
+    if (json) process.stdout.write(JSON.stringify(obj) + '\n');
+    return exit;
+  };
+
+  if (!config) {
+    if (!json) UI.warning(`No (or malformed) ${CONFIG_FILE} — run \`npx baldart configure\` first.`);
+    return emit({ schema: 'baldart.tokens-build/1', ok: false, reason: 'no-config' }, 1);
+  }
+
+  const source = config.paths && config.paths.design_tokens;
+  const outputs = (config.design_tokens && config.design_tokens.outputs) || [];
+
+  if (!source) {
+    if (!json) UI.info('No `paths.design_tokens` set — DTCG token SSOT not adopted on this project. Nothing to build.');
+    return emit({ schema: 'baldart.tokens-build/1', ok: true, skipped: 'no-source' });
+  }
+
+  const gen = new TokensGenerator(cwd);
+  if (!gen.detect(source)) {
+    if (!json) UI.warning(`design tokens source not found at \`${source}\`. Create it (e.g. via /design-system-init) then re-run.`);
+    return emit({ schema: 'baldart.tokens-build/1', ok: false, reason: 'source-missing', source }, 1);
+  }
+  if (!outputs.length) {
+    if (!json) UI.warning('`design_tokens.outputs` is empty — nothing to generate. Add at least one { format, path }.');
+    return emit({ schema: 'baldart.tokens-build/1', ok: true, skipped: 'no-outputs', source });
+  }
+
+  const res = gen.build({ source, outputs });
+  if (!res.ok) {
+    if (!json) UI.error(`Token build failed: ${res.error}`);
+    return emit({ schema: 'baldart.tokens-build/1', ok: false, reason: res.error, source }, 1);
+  }
+
+  if (!json) {
+    UI.success(`Tokens built from ${source} (${res.tokenCount} tokens):`);
+    for (const p of res.written) UI.info(`  ✓ ${p}`);
+  }
+  return emit({ schema: 'baldart.tokens-build/1', ok: true, source, written: res.written, tokenCount: res.tokenCount });
+}
+
+module.exports = { build: tokensBuild };

package/src/commands/update.js

@@ -1320,6 +1320,12 @@ async function update(options = {}, unknownArgs = []) {
             const missingI18n = Object.keys(tpl.i18n || {})
               .filter((k) => !(k in (cur2.i18n || {})))
               .map((k) => `i18n.${k}`);
+            // `design_tokens:` (since v4.65.0) — same nested-block contract.
+            // Its only key `outputs` is an ARRAY, so (per the v4.46.0 array
+            // lesson) we diff presence of the key, not deep value equality.
+            const missingDesignTokens = Object.keys(tpl.design_tokens || {})
+              .filter((k) => !(k in (cur2.design_tokens || {})))
+              .map((k) => `design_tokens.${k}`);
             const allMissing = [
               ...missingPaths,
               ...missingFeatures,
@@ -1329,6 +1335,7 @@ async function update(options = {}, unknownArgs = []) {
               ...missingToolchain,
               ...missingToolchainCmds,
               ...missingI18n,
+              ...missingDesignTokens,
             ];
             if (allMissing.length) {
               UI.newline();

package/src/utils/token-emitters/README.md

@@ -0,0 +1,36 @@
+# token-emitters
+
+Per-format emitters for the DTCG token generator (`../tokens-generator.js`).
+The DTCG `.tokens.json` (`paths.design_tokens` in `baldart.config.yml`) is the
+design-token SSOT; each emitter turns the resolved token set into ONE
+stack-native artifact. Same REGISTRY pattern as `lsp-adapters/`,
+`routine-adapters/`, `tool-adapters/`, `toolchain-adapters/`.
+
+## Adding a format
+
+1. Create `<format>.js` exporting `module.exports = function emit({ resolved, nested, marker }) { return '<file contents>'; }`.
+   - `resolved`: `Map<dotId, { type, value }>` — fully ref-resolved leaf tokens, source order.
+   - `nested`: nested plain object of resolved **values** (DTCG tree minus `$type`/`$value`).
+   - `marker`: the generated-file banner line for your format (already comment-wrapped).
+2. Register it in `index.js`'s `EMITTERS` map.
+3. If the comment syntax differs from `//` and `/* */`, extend `markerFor()` in `index.js`.
+
+That's it — `tokens-generator.js`, `baldart tokens build`, and `doctor` iterate
+the registry; nothing else changes.
+
+## Invariants
+
+- **Deterministic, diff-stable output**: emit in source order, no timestamps, no
+  randomness — so `isStale()` (on-disk vs fresh render byte-compare) is reliable.
+- **Always emit the `marker`** as the first line — it is how humans and the
+  `framework-edit-gate` know the file is generated and must not be hand-edited.
+- **Pure**: emitters never touch the filesystem; the generator writes.
+- **Zero dependency**: no Style Dictionary, no npm — keep it portable (the build
+  path must run identically under Codex).
+
+## Shipped formats
+
+| format | output |
+|--------|--------|
+| `ts`   | `export const tokens = {…} as const;` + `export type Tokens` |
+| `css`  | `:root { --<dot-id-as-dashes>: <value>; }` |

package/src/utils/token-emitters/css.js

@@ -0,0 +1,18 @@
+// CSS emitter: DTCG → `:root { --<dot-id-as-dashes>: <value>; }`.
+//
+// Token id `color.action.primary` → `--color-action-primary`. Emits resolved
+// values (refs collapsed) in source order so the output is diff-stable.
+
+function cssVarName(dotId) {
+  return `--${dotId.replace(/\./g, '-')}`;
+}
+
+module.exports = function emitCss({ resolved, marker }) {
+  const lines = [];
+  for (const [id, tok] of resolved) {
+    lines.push(`  ${cssVarName(id)}: ${tok.value};`);
+  }
+  return `${marker}\n:root {\n${lines.join('\n')}\n}\n`;
+};
+
+module.exports.cssVarName = cssVarName;

package/src/utils/token-emitters/index.js

@@ -0,0 +1,47 @@
+// Token emitter registry (since v4.65.0).
+//
+// DTCG (`.tokens.json`) is the design-token SSOT; each emitter turns the
+// resolved token set into ONE stack-native artifact (a TS object, a CSS
+// custom-property sheet, …). This is the same REGISTRY pattern as
+// `lsp-adapters/`, `routine-adapters/`, `tool-adapters/`, `toolchain-adapters/`:
+// every other layer iterates this map, so adding a format = drop a file +
+// register it here. Zero npm dependency (no Style Dictionary) — see
+// `framework/docs/COMPONENT-MANIFEST-LAYER.md`.
+//
+// An emitter exports a single function:
+//   emit({ resolved, nested, marker }) -> string   (the file contents)
+// where:
+//   resolved : Map<dotId, { type, value }>  fully ref-resolved leaf tokens
+//   nested   : nested plain object of resolved VALUES (DTCG tree minus $type/$value)
+//   marker   : the "baldart-generated" banner line for this format
+
+const ts = require('./ts');
+const css = require('./css');
+
+const EMITTERS = { ts, css };
+
+/** Stable, format-appropriate generated-file banner. */
+function markerFor(format) {
+  const text = 'baldart-generated from .tokens.json — do not edit (run `baldart tokens build`)';
+  if (format === 'css') return `/* ${text} */`;
+  return `// ${text}`; // ts / js / any C-style
+}
+
+/**
+ * Emit one output. Returns { ok, format, content } or { ok:false, error }.
+ * Pure — does not touch the filesystem (the caller writes).
+ */
+function emit(format, { resolved, nested }) {
+  const fn = EMITTERS[format];
+  if (typeof fn !== 'function') {
+    return { ok: false, error: `unknown token output format: "${format}" (known: ${Object.keys(EMITTERS).join(', ')})` };
+  }
+  const marker = markerFor(format);
+  try {
+    return { ok: true, format, content: fn({ resolved, nested, marker }) };
+  } catch (e) {
+    return { ok: false, error: `emitter "${format}" failed: ${e.message}` };
+  }
+}
+
+module.exports = { emit, markerFor, knownFormats: () => Object.keys(EMITTERS) };

package/src/utils/token-emitters/ts.js

@@ -0,0 +1,32 @@
+// TS emitter: DTCG → a typed `export const tokens = {...} as const;` object.
+//
+// Emits the nested tree of RESOLVED values (refs already collapsed), mirroring
+// the DTCG group structure minus the $type/$value wrappers. Deterministic key
+// order (insertion order of the source) so the output is diff-stable.
+
+function literal(value) {
+  // Tokens resolve to strings (colors, dimensions, durations) or numbers.
+  if (typeof value === 'number') return String(value);
+  return JSON.stringify(String(value));
+}
+
+function render(node, indent) {
+  const pad = '  '.repeat(indent);
+  const padInner = '  '.repeat(indent + 1);
+  const keys = Object.keys(node);
+  const lines = keys.map((k) => {
+    const v = node[k];
+    // A safe JS identifier key can be bare; otherwise quote it (e.g. "2").
+    const key = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+    if (v && typeof v === 'object') {
+      return `${padInner}${key}: ${render(v, indent + 1)},`;
+    }
+    return `${padInner}${key}: ${literal(v)},`;
+  });
+  return `{\n${lines.join('\n')}\n${pad}}`;
+}
+
+module.exports = function emitTs({ nested, marker }) {
+  const body = render(nested, 0);
+  return `${marker}\nexport const tokens = ${body} as const;\n\nexport type Tokens = typeof tokens;\n`;
+};