baldart 4.64.0 → 4.65.0

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

@@ -0,0 +1,145 @@
+# Component Manifest Schema
+
+## Purpose
+
+Define the **machine-readable HEAD** every per-component spec
+(`${paths.design_system}/components/<Name>.md`) carries so agents discover and
+reuse primitives by reading a small, structured frontmatter **on demand** — not
+by parsing a monolithic `INDEX.md` or the component source. This module is the
+**single source of truth** for *which fields a component spec needs* and *in what
+state*; every writer and every consumer cites it.
+
+It is the design-system analogue of `agents/card-schema.md`: a schema that ≥6
+surfaces produce or consume (`design-system-init`, `doc-reviewer`, `ui-expert`,
+`code-reviewer`, `codebase-architect`, `context-primer`, `ds-drift`) and must
+therefore live in one place that none of them re-describe.
+
+## Scope
+
+**In**: the frontmatter field table, the deterministic-vs-agentic split, the
+regeneration contract, the on-demand read contract, the thin-INDEX router shape,
+and the transition-leniency rule.
+
+**Out**: the *enforcement* (when a missing/stale spec blocks) and the drift codes
+(`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT`) — those stay in
+`agents/design-system-protocol.md` (§ Post-Intervention Coherence Check). This
+module defines the *fields those codes are checked against*; it **never copies**
+the codes or the gate (that would re-introduce the drift the SSOT split prevents).
+Token *values* and the DTCG source live in the token layer
+(`${paths.design_tokens}` → `.tokens.json`); this module references token **IDs**,
+never values.
+
+## Gating
+
+Same as the design-system protocol: meaningful only when
+`features.has_design_system: true`. There is **no separate feature flag** — the
+manifest rides on the design-system layer. When the flag is `false`, component
+specs (and this schema) do not apply.
+
+## The frontmatter HEAD
+
+Additive: a YAML frontmatter block is prepended to the EXISTING prose spec. The
+prose body (Purpose, Props table, Accessibility, Anti-patterns, …) is preserved
+verbatim — the HEAD makes the *mechanical* half machine-addressable; the prose
+stays the human-readable long form.
+
+```yaml
+---
+# === DETERMINISTIC — extracted from source (TS types) + git; regenerable, never hand-curated ===
+name: Button                              # exported component name
+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
+  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
+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."
+token_bindings: [color.action.primary, radius.md, space.2, motion.fast]  # DTCG token IDs (not values)
+a11y: "Icon-only requires aria-label; ≥44px target; respects prefers-reduced-motion."
+related: [IconButton, Link]               # sibling primitives (not composition)
+must_rules: ["MUST consume color.action.primary", "MUST set aria-label when icon-only"]
+last_verified: 2026-06-23                 # set by doc-reviewer / ds-drift on semantic re-verify
+owner: doc-reviewer                       # curation owner (constant; documents the SSOT)
+---
+```
+
+### Field origin
+
+| 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**. |
+| **Agentic** (doc-reviewer) | `purpose`, `token_bindings`, `a11y`, `related`, `must_rules`, `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. |
+
+## Read contract (the context win)
+
+1. An agent doing reuse-discovery reads the thin `INDEX.md` (router) → then **only
+   the frontmatter** of the N specs in scope (front-load the first `---…---`
+   block), NOT the prose body and NOT the source.
+2. The prose body is read only when the agent is about to **modify** that
+   component.
+3. `token_bindings` are IDs into `.tokens.json`, so one already-read tokens file
+   answers every component's bindings — no per-component token re-read, and the
+   binding stays stable when a token *value* changes.
+
+This is the whole point: replace "read a 33KB monolith + fall to source" with
+"read a small router + N small frontmatters".
+
+## Thin INDEX router
+
+`${paths.design_system}/INDEX.md` is **generated** and holds only routing data —
+one row per primitive: `name | source | one-line purpose | spec link`. It carries
+NO human-curated judgment (the Authority Matrix moved to
+`design-system-protocol.md`; per-component detail lives in each spec). Because it
+is generated, it is always safe to regenerate from the specs — never hand-edit it.
+
+## Regeneration contract
+
+- **Anchor**: `source_sha`. A regeneration run skips a component whose source is
+  unchanged AND whose spec already has a HEAD (no-op); regenerates only
+  stale/missing ones.
+- **Deterministic fields**: overwritten from current source every run.
+- **Agentic fields**: preserved unless empty; an empty field is a candidate for
+  enrichment, never a reason to clobber a filled one.
+- **Idempotent + resumable**: a kill mid-run leaves a mix of HEAD-bearing and
+  prose-only specs — all valid (see leniency below). No half-written state.
+
+## Transition leniency (do not raise the floor)
+
+The HEAD is an **upgrade target, not a new floor**. During and after adoption:
+
+- A **prose-only spec** (no HEAD) is still a valid spec — it does NOT trip
+  `DS_COMPONENT_STALE` merely for lacking a HEAD.
+- **Empty deterministic fields** (e.g. a JS/Vue/Svelte consumer with no TS types,
+  or an unresolved prop) are **advisory** — "not yet enriched", never a blocking
+  finding.
+- A **missing** spec for a new primitive remains exactly the `DS_INDEX_DRIFT` it
+  is today — the manifest adds no new failure mode, it only makes the existing
+  spec richer where the data is available.
+
+This keeps consumers that have not yet upgraded (and non-TS stacks) from becoming
+*more* broken than before the manifest existed.
+
+## Producers & consumers
+
+- **Bootstrap / upgrade**: `/design-system-init` (deterministic extract + agentic
+  enrich; greenfield and upgrade modes).
+- **Per-task write**: `ui-expert` / `ui-design` / `frontend-design` in the
+  Post-Intervention Coherence Check — a new/modified primitive regenerates its
+  HEAD in the same change.
+- **Curation owner**: `doc-reviewer` (agentic fields).
+- **Per-merge gate**: `code-reviewer` (reads HEAD-first; enforces the drift codes
+  per the protocol).
+- **Read-first discovery**: `codebase-architect`, `context-primer`.
+- **Weekly net**: `ds-drift` (compares `source_sha`/HEAD against source).
+
+## See also
+
+- `agents/design-system-protocol.md` — the enforcement gate + drift codes + read
+  cascade this schema feeds.
+- `agents/card-schema.md` — the sibling schema module this one mirrors.
+- `agents/project-context.md` — `baldart.config.yml` + overlay resolution.

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

@@ -47,13 +47,21 @@ To bootstrap a registry on a project that does not yet have one, invoke the
 
 ## Canonical sources (resolve via `baldart.config.yml`)
 
-- `${paths.design_system}/INDEX.md` — component index + Canonical Authority
-  Matrix + quick MUST rules. Entry point for every UI task.
-- `${paths.design_system}/tokens-reference.md` — human-readable token contract
-  (colors, spacing, shadows, radii, motion). Single source of truth for any
-  value that would otherwise be hardcoded.
-- `${paths.design_system}/components/<Name>.md` — per-component spec (props,
-  variants, accessibility, anti-patterns). One file per primitive.
+- `${paths.design_system}/INDEX.md` — **generated** thin router: one row per
+  primitive (`name | source | one-line purpose | spec link`). Entry point for
+  every UI task. Human-curated judgement does NOT live here (it moved to the
+  Authority Matrix below + each spec's frontmatter) — never hand-edit the INDEX.
+- `${paths.design_tokens}` → `.tokens.json` — **the token SSOT**, W3C DTCG
+  format (`$type`/`$value`). The stack-native artifact (`tokens.ts` / CSS custom
+  properties) is **generated** from it via `baldart tokens build`; editing that
+  generated output by hand is drift (see Token Contract).
+- `${paths.design_system}/tokens-reference.md` — **generated/narrative** human
+  view of the tokens. NOT a third source of values: either generated from
+  `.tokens.json` or pure narrative ("how to use tokens"), never hand-authored
+  values that duplicate the DTCG source.
+- `${paths.design_system}/components/<Name>.md` — per-component spec. Carries a
+  machine-readable frontmatter HEAD (see `agents/component-manifest-schema.md`)
+  + prose body (props, variants, accessibility, anti-patterns). One per primitive.
 - `${paths.design_system}/patterns/*.md` — opt-in pattern docs (theming,
   overlays, motion choreography, multi-tenant pairing rules).
 - `${paths.ui_guidelines}` — brand voice, typography, philosophy. Always read.
@@ -64,9 +72,12 @@ To bootstrap a registry on a project that does not yet have one, invoke the
 
 Before producing any new UI code, mockup, or design review:
 
-1. **BLOCKING** — read `${paths.design_system}/INDEX.md`. Extract: the
-   component index, the Authority Matrix for the surface you are about to
-   touch, any pattern docs the index points to.
+1. **BLOCKING** — read `${paths.design_system}/INDEX.md` (the thin router) to
+   locate the primitives in scope, then read **only the frontmatter HEAD** of
+   each in-scope `components/<Name>.md` (per `agents/component-manifest-schema.md`)
+   — not the prose body, not the source. Read the prose body only when you are
+   about to modify that primitive. Also read the Authority Matrix (below) + any
+   pattern docs the router points to.
 2. **BLOCKING** — read `${paths.ui_guidelines}` for visual language, typography,
    accessibility, and brand voice. The `identity.design_philosophy` (when set)
    is the lens through which these guidelines apply.
@@ -120,10 +131,26 @@ any code or mockup produced under this protocol:
   the `motion-design` skill).
 
 The exact token consumption mechanism (CSS custom properties, Tailwind theme
-extend, theme provider) is project-specific — defer to
-`${paths.design_system}/tokens-reference.md` and the project's chosen
+extend, theme provider) is project-specific — defer to the project's chosen
 mechanism.
 
+**Token SSOT inversion (when `paths.design_tokens` is set).** The canonical
+token source is the DTCG `.tokens.json` at `${paths.design_tokens}`. The
+stack-native artifact agents/components consume (`tokens.ts`, a CSS custom-property
+sheet, …) is **generated** from it by `baldart tokens build` and carries a
+`// baldart-generated from .tokens.json — do not edit` marker. Consequences:
+
+- To add/change a token, edit `.tokens.json` and regenerate — never hand-edit the
+  generated output.
+- `DS_TOKENS_DRIFT` is now mechanically checkable: the generated output must equal
+  `baldart tokens build` from the current `.tokens.json`. A hand-edit to the
+  generated file (output ≠ rebuild) is the violation — port it to `.tokens.json`.
+- A `token_bindings` ID in a component HEAD must resolve to a real node in
+  `.tokens.json`; a dangling ID is `DS_TOKENS_DRIFT`.
+
+When `paths.design_tokens` is unset, the project has not adopted the DTCG SSOT —
+fall back to the project's existing token file as the source (no inversion).
+
 ## Reference Tables (embed)
 
 These tables are the SSOT for the *numeric ranges* every agent/skill should
@@ -306,13 +333,16 @@ visually uneven steps because HSL lightness is not perceptual.
 
 ## Authority Matrix
 
-`${paths.design_system}/INDEX.md` declares, for each primitive, who is
-authoritative over which dimension:
+This matrix is **canonical here** (protocol-level), not in `INDEX.md` — the INDEX
+is a generated router and cannot hold curated judgement. For each primitive, it
+declares who is authoritative over which dimension:
 
-- **Visual authority** — colors, spacing, shadows, radii: the registry +
-  tokens-reference. Agents/skills may not deviate.
+- **Visual authority** — colors, spacing, shadows, radii, motion: the DTCG token
+  SSOT (`${paths.design_tokens}` → `.tokens.json`, surfaced via the generated
+  token reference). Agents/skills may not deviate.
 - **Behavioral authority** — props, variants, accessibility hooks: the
-  per-component spec.
+  per-component spec (its frontmatter HEAD for the machine-readable contract, its
+  prose body for rationale).
 - **Composition authority** — how primitives are combined into patterns: the
   pattern docs.
 
@@ -441,12 +471,19 @@ For each item in the diff that touched a visual surface, run these 4 checks:
    in the same change. Missing spec = `DS_INDEX_DRIFT` finding, task blocked.
 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. Stale spec =
-   `DS_COMPONENT_STALE` finding, task blocked.
-3. **New / changed token ⇒ updated reference**: did the change introduce or
-   modify a token (color, spacing, shadow, radius, motion)? If yes,
-   `${paths.design_system}/tokens-reference.md` MUST reflect it. Stale
-   reference = `DS_TOKENS_DRIFT` finding, task blocked.
+   `components/<Name>.md` MUST be updated to match — including its **frontmatter
+   HEAD** (deterministic fields `props`/`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`
+   § Transition leniency.)
+3. **New / changed token ⇒ updated SSOT**: did the change introduce or modify a
+   token (color, spacing, shadow, radius, motion)? If `paths.design_tokens` is
+   set, the change MUST be made in `.tokens.json` and the stack-native output
+   regenerated via `baldart tokens build` (a hand-edit to the generated output is
+   the drift). Otherwise update the project's token source + reference. Either
+   way, a dangling `token_bindings` ID is drift. Stale = `DS_TOKENS_DRIFT`,
+   task blocked.
 4. **Surfaced silent primitive ⇒ added to INDEX**: during the work, did you
    reuse a primitive that exists in the source tree but is **not** in
    `INDEX.md`? If yes, add it to the INDEX in the same change (or open a
@@ -529,6 +566,9 @@ When changing the BLOCKING cascade, change it here — not in the consumers.
 
 ## See also
 
+- `framework/agents/component-manifest-schema.md` — the machine-readable
+  frontmatter HEAD on each `components/<Name>.md`, the on-demand read contract,
+  and the regeneration + transition-leniency rules this gate is checked against.
 - `framework/agents/project-context.md` — always-ask / never-assume contract
   and the `baldart.config.yml` resolution flow.
 - `framework/agents/design-review.md` — design-review workflow and report

package/framework/agents/index.md

@@ -20,6 +20,7 @@ Route agents to the right module with minimal reading.
 - If touching database schema or fields -> read `agents/data-model.md` and `${paths.references_dir}/data-model.md`.
 - If touching UI pages/routes or flows -> read `${paths.references_dir}/ui/index.md` (then specific UI module for your domain).
 - If touching ANY visual surface (component, page, mockup, design review) and `features.has_design_system: true` -> read `agents/design-system-protocol.md` and treat the BLOCKING cascade (`${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md`) as mandatory pre-work. When the flag is `false`, recommend `/design-system-init` to scaffold a registry.
+- If CREATING, UPDATING, or READING a per-component spec (`${paths.design_system}/components/<Name>.md`) -> read `agents/component-manifest-schema.md` for the machine-readable frontmatter HEAD (deterministic-from-TS + agentic fields) and the on-demand read contract (INDEX router → frontmatter-first, prose only when modifying). The drift codes + gate stay in `design-system-protocol.md`.
 - If touching design-review workflows or UI guidelines -> read `agents/design-review.md` and project-specific UI guidelines.
 - If touching architecture, auth, or tech stack -> read `agents/architecture.md`.
 - If touching workflow/process/commits/backlog -> read `agents/workflows.md`.
@@ -72,6 +73,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/i18n-protocol.md` — Internationalization discipline: no hardcoded user-facing strings, context registry (`paths.i18n_registry`) + ICU + context-aware translation; BLOCKING anti-hardcoded lint gate (since v4.52.0, gated on `features.has_i18n`)
 - `agents/design-system-protocol.md` — Registry-first discipline for UI work: BLOCKING cascade on `INDEX.md` + `tokens-reference.md` + `components/<Name>.md` (since v3.11.0, gated on `features.has_design_system`)
 - `agents/card-schema.md` — Atomic Card Baseline Schema: the universal, profile-aware (epic/child/standalone) field contract every backlog card satisfies, plus the consumer HALT/BACK-FILL/WARN contract (since v4.35.0)
+- `agents/component-manifest-schema.md` — Component Manifest Schema: the machine-readable frontmatter HEAD on each `components/<Name>.md` (deterministic-from-TS + agentic fields), on-demand read contract, regeneration + transition-leniency rules (since v4.65.0, gated on `features.has_design_system`)
 - `agents/return-contract-protocol.md` — Subagent return-message economy: COMPACT (bounded headline + `path:line` findings + disk pointer) vs FULL, persist-then-summarize — the input-side twin of `effort-protocol.md` (since v4.59.0)
 
 ## Where to Document (Decision Tree)

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.65.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