baldart 3.10.0 → 3.13.0

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

@@ -0,0 +1,232 @@
+---
+name: design-system-init
+description: >
+  Bootstrap a component registry / design system on a project that doesn't have
+  one yet. Scaffolds ${paths.design_system}/INDEX.md (component index +
+  Canonical Authority Matrix), tokens-reference.md (extracted from
+  ${paths.global_styles} / Tailwind config), and a components/<Name>.md spec
+  per primitive already present under ${paths.components_primitives}. Then
+  flips features.has_design_system: true in baldart.config.yml. Use when the
+  user says /design-system-init, "crea design system", "bootstrap design
+  system", "inizializza registro componenti", or when configure detected no
+  design-system path and the user wants one. Idempotent — refuses to overwrite
+  an existing registry, supports incremental re-runs to add specs for new
+  components.
+---
+
+# Design-System Init
+
+Scaffold the component registry that the registry-first protocol
+(`framework/agents/design-system-protocol.md`) treats as BLOCKING for every
+UI task. Without a registry, the BLOCKING reads in `ui-design`,
+`frontend-design`, `ui-expert`, and `/design-review` are inert — they have
+nothing to read. This skill creates the missing pieces from the codebase's
+current state so the discipline can kick in immediately.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.design_system`,
+`paths.components_primitives`, `paths.components_root`, `paths.global_styles`,
+`paths.ui_guidelines`, `identity.brand_name`, `identity.design_philosophy`,
+`stack.design_system_signals`.
+
+**Gated by features:** none — this skill is the bootstrap mechanism for
+`features.has_design_system`. It refuses to run when a registry is already
+present (`has_design_system: true` AND `paths.design_system/INDEX.md` exists).
+
+**Overlay:** loads `.baldart/overlays/design-system-init.md` if present —
+project-specific opinions (e.g. mandated section order in `components/<Name>.md`,
+brand-voice rules to inject into the scaffolded INDEX, custom token extraction
+recipe for non-Tailwind stacks).
+
+**On missing keys:** ask the user; do not assume defaults. See
+`framework/agents/project-context.md` § 3.
+
+## What This Skill Does
+
+1. **Refusal check.** Reads `baldart.config.yml`.
+   - If `features.has_design_system: true` AND `${paths.design_system}/INDEX.md`
+     exists: stop with "Registry already present at `${paths.design_system}`.
+     To extend it, edit it directly or invoke `ui-design` / `frontend-design`
+     which know how to propose registry additions."
+   - If `has_design_system: true` but the path is missing: warn about the
+     drift, offer to re-scaffold at the configured path.
+2. **Resolve target path.** Default `docs/design-system/`. Ask the user to
+   confirm or override. Use `${paths.design_system}` if already set in config.
+3. **Inventory existing primitives.** Launch the `codebase-architect` agent
+   on `${paths.components_primitives}` (and `${paths.components_root}/shared`
+   when present) to extract: file path, exported component name, props
+   signature, variants (if discoverable), accessibility hooks used, tokens
+   referenced.
+4. **Extract token contract.** Read `${paths.global_styles}` for CSS custom
+   properties; read `tailwind.config.{ts,js,mjs,cjs}` for theme extensions;
+   read any `tokens.{json,ts,js}` or Style Dictionary output. Group by
+   category (color, spacing, shadow, radius, typography, motion).
+5. **Scaffold the files** under the target path:
+   - `INDEX.md` — component index, Canonical Authority Matrix (empty
+     visual/behavioral/composition columns to be filled by the team),
+     pointer to `tokens-reference.md` and `components/`.
+   - `tokens-reference.md` — extracted tokens, grouped, with a note that
+     `tokens-reference.md` is the SSOT and hardcoded literals are forbidden.
+   - `components/<Name>.md` — one file per discovered primitive, generated
+     from `scripts/component-spec.template.md`. Fill the fields the inventory
+     could resolve; leave clearly-marked TODO sections for the rest.
+   - `patterns/.gitkeep` — empty dir for future pattern docs.
+6. **Update config.** Set `features.has_design_system: true` and
+   `paths.design_system: <target>` in `baldart.config.yml`. Use the same
+   YAML write path as `configure` (preserve user values, never clobber
+   unrelated keys).
+7. **Print next-steps.** Authority Matrix to fill, specs to review, suggested
+   first follow-up (`/design-review` on a key route to validate the registry).
+
+## Workflow
+
+1. **Refusal check** — see § What This Skill Does step 1.
+
+2. **Target path prompt:**
+   ```
+   Scaffold the registry at: docs/design-system/  [Y/n/custom]
+   ```
+
+3. **Inventory** — launch `codebase-architect` with this prompt skeleton:
+   > Enumerate the UI primitives under `${paths.components_primitives}`. For
+   > each: file path, exported name, props type (best-effort from TS/JSDoc),
+   > variants (e.g. `variant="primary|ghost"`), accessibility attributes
+   > (aria-*, role, focus management), design tokens referenced (CSS vars,
+   > Tailwind classes that map to tokens). Report as a JSON-friendly list.
+
+4. **Token extraction** — for each detected source:
+   - CSS custom properties: parse `--*: ...;` declarations and group by prefix.
+   - Tailwind theme: parse `theme.extend.{colors,spacing,boxShadow,borderRadius,fontFamily,transitionDuration,transitionTimingFunction}`.
+   - Style Dictionary / tokens file: parse the JSON tree.
+   - If nothing is found, leave a TODO section in `tokens-reference.md`
+     pointing the team to populate it before relying on the SSOT contract.
+
+5. **Generate files** using the template in
+   `scripts/component-spec.template.md` for each component, and the inline
+   templates below for INDEX and tokens-reference.
+
+6. **Persist config:**
+   ```yaml
+   paths:
+     design_system: docs/design-system   # or user-chosen
+   features:
+     has_design_system: true
+   ```
+
+7. **Output** — short status block (see Output Contract).
+
+## Output Contract
+
+```
+Design-system bootstrap:
+  ✓ Created docs/design-system/INDEX.md
+  ✓ Created docs/design-system/tokens-reference.md (32 tokens extracted)
+  ✓ Generated 17 component specs under docs/design-system/components/
+  ⚠ 4 components had no resolvable props — TODO sections marked
+Config updated: baldart.config.yml has_design_system=true, paths.design_system=docs/design-system
+Next: review INDEX.md Authority Matrix, fill TODO sections, run /design-review on a key route.
+```
+
+## INDEX.md template
+
+The generated `INDEX.md` has this skeleton (concrete values substituted from
+the inventory):
+
+```markdown
+# ${identity.brand_name} Design System
+
+Single source of truth for visual, behavioral, and compositional decisions on
+this product. Read this BEFORE producing or reviewing any UI. The registry-first
+protocol is defined in `framework/agents/design-system-protocol.md`.
+
+## Token Contract
+
+Tokens live in [`tokens-reference.md`](tokens-reference.md). Hardcoded color /
+shadow / radius / spacing / motion values are FORBIDDEN when these tokens
+cover the use case.
+
+## Component Index
+
+| Component | File | Purpose | Spec |
+|-----------|------|---------|------|
+| Button    | ${paths.components_primitives}/Button.tsx | … | [components/Button.md](components/Button.md) |
+| …         | …    | …       | …    |
+
+## Canonical Authority Matrix
+
+| Dimension          | Authority                       | Override path |
+|--------------------|---------------------------------|---------------|
+| Color / shadow / radius / spacing | `tokens-reference.md` | Propose a new token + ADR |
+| Props / variants / a11y           | per-component `components/<Name>.md` | Update the spec in the same change |
+| Composition (patterns)            | `patterns/<topic>.md`            | New pattern doc + INDEX entry |
+
+## Quick MUST Rules
+
+- Reuse from the Component Index before inventing a new primitive.
+- Consume tokens via the project's mechanism (CSS vars / Tailwind theme /
+  theme provider) — never hardcode literals.
+- Any new primitive ships with its `components/<Name>.md` spec in the same
+  change.
+- Authority Matrix violations require a registry update, not a local override.
+
+## How to Extend
+
+- New primitive → create `components/<Name>.md` (the template lives at
+  `.framework/framework/.claude/skills/design-system-init/scripts/component-spec.template.md`
+  after `npx baldart add` — copy it, fill it in, drop under
+  `${paths.design_system}/components/`),
+  implement under `${paths.components_primitives}`, add the row above.
+- New pattern → create `patterns/<topic>.md`, link from this INDEX.
+- New token → add to `tokens-reference.md`, propagate to the project's
+  token mechanism.
+```
+
+## tokens-reference.md template
+
+```markdown
+# Token Reference
+
+Single source of truth for design tokens. Values below are extracted from
+${paths.global_styles} and tailwind config (when present). DO NOT hardcode
+literals that duplicate these tokens in components.
+
+## Color
+- `--color-primary: <value>` — …
+- …
+
+## Spacing
+- `--space-1: <value>` — …
+- …
+
+## Shadow
+- …
+
+## Radius
+- …
+
+## Typography
+- …
+
+## Motion
+- duration: …
+- easing: …
+```
+
+## Notes
+
+- The skill never modifies source components — its only side effects are
+  creating files under `${paths.design_system}` and updating
+  `baldart.config.yml`.
+- Generated specs are starting points, not final docs. The expected next move
+  is human review + filling TODO sections + a `/design-review` pass.
+- Idempotent: re-running detects existing specs and only generates files for
+  new primitives (and updates the Component Index table).
+
+## See Also
+
+- `framework/agents/design-system-protocol.md` — the protocol this skill bootstraps.
+- `framework/agents/project-context.md` — config + overlay contract.
+- `framework/.claude/skills/ui-design/SKILL.md` — primary consumer (reads
+  the registry BLOCKING).
+- `scripts/component-spec.template.md` — per-component spec template.

package/framework/.claude/skills/design-system-init/scripts/component-spec.template.md

@@ -0,0 +1,79 @@
+# {{ComponentName}}
+
+> Per-component spec. Authoritative for props, variants, accessibility, and
+> anti-patterns. Visual authority (color/shadow/radius/spacing) belongs to
+> [`../tokens-reference.md`](../tokens-reference.md).
+
+## Source
+
+- File: `{{file_path}}`
+- Exported as: `{{exported_name}}`
+- Used by: <!-- TODO: list 2-3 key consumers, e.g. pages or compound components -->
+
+## Purpose
+
+<!-- One-sentence statement of what this primitive is for and when to reach
+for it instead of an alternative. -->
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+{{props_table}}
+
+<!-- TODO: if props were not auto-resolvable, fill the table from the source
+file. Keep types accurate — drift here is the most common bug. -->
+
+## Variants
+
+{{variants_section}}
+
+<!-- TODO: enumerate every variant the component exposes. For each, describe
+when to use it. Example:
+- `variant="primary"` — primary CTA, one per surface
+- `variant="ghost"` — secondary actions in dense layouts
+- `size="sm" | "md" | "lg"` — bind to spacing tokens
+-->
+
+## Tokens consumed
+
+{{tokens_section}}
+
+<!-- TODO: list the tokens this component reads from tokens-reference.md.
+Color, spacing, shadow, radius, motion. If you find hardcoded literals in
+the source, that's a registry violation — fix at the source. -->
+
+## Accessibility
+
+- Keyboard: <!-- focus order, shortcuts, escape behavior -->
+- ARIA: <!-- roles, labels, descriptions, live regions -->
+- Touch target: ≥ 44×44px when interactive
+- Color contrast: text ≥ 4.5:1, UI ≥ 3:1 (WCAG 2.1 AA)
+- Reduced motion: respects `prefers-reduced-motion`
+
+## Composition
+
+<!-- How this primitive composes with others. Patterns it appears in.
+Cross-link to patterns/ docs when applicable. -->
+
+## Anti-patterns
+
+<!-- Common misuses that should be rejected in code review. Examples:
+- Wrapping in a div with absolute positioning to fake a variant — add a
+  variant to the registry instead.
+- Hardcoding a custom color via inline style — add a token and consume it.
+-->
+
+## MUST rules
+
+<!-- HIGH-severity rules the code-reviewer agent enforces. Examples:
+- MUST consume `--color-primary` for background; never hardcode.
+- MUST set `aria-label` when icon-only.
+-->
+
+## Changelog
+
+<!-- Track breaking changes to the spec. Bump version when removing a variant
+or changing a default. -->
+
+- {{today}} — Spec scaffolded by `/design-system-init`.

package/framework/.claude/skills/frontend-design/SKILL.md

@@ -50,6 +50,11 @@ Remember: Claude is capable of extraordinary creative work. Don't hold back, sho
 
 ## MANDATORY Pre-Work Read (project design-system override)
 
+The registry-first cascade below is the consumer view of the SSOT in
+[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md).
+When the cascade rules diverge between this file and the protocol module,
+the protocol module wins.
+
 When operating inside a repo that ships a design-system SSOT, the generic
 creative guidance above is BLOCKED by the project design-system until the
 reads below are complete. MANDATORY pre-work reads (skipping any of them is
@@ -72,6 +77,125 @@ Within those bounds, creative choices (typography nuance, composition, motion in
 
 ---
 
+## Performance Gates (Core Web Vitals 2026)
+
+Production-grade frontend is not just "looks good" — it ships within the CWV
+thresholds. Every page / component / route MUST be designed against these
+budgets, not retrofitted after Lighthouse complains.
+
+### Thresholds (p75, CrUX dataset)
+
+| Metric | Good | Poor | What it measures |
+|---|---|---|---|
+| **LCP** | ≤ 2.5s | > 4.0s | Largest Contentful Paint — usually the hero image or H1 |
+| **INP** | ≤ 200ms | > 500ms | Interaction to Next Paint — replaced FID in Mar 2024 |
+| **CLS** | ≤ 0.1 | > 0.25 | Cumulative Layout Shift |
+| TTFB | ≤ 0.8s | > 1.8s | Subset of LCP (~40% of budget) |
+| FCP | ≤ 1.8s | > 3.0s | Diagnostic only |
+
+A page passes CWV when all three (LCP/INP/CLS) are *good* at p75. INP is the
+hardest of the three on JS-heavy apps and the most commonly failed (~43% of
+sites globally).
+
+### LCP image: the only correct pattern
+
+```html
+<!-- in <head> — preload + fetchpriority for the hero -->
+<link rel="preload" as="image"
+      href="/hero.avif"
+      imagesrcset="/hero-800.avif 800w, /hero-1600.avif 1600w"
+      imagesizes="100vw"
+      fetchpriority="high">
+
+<!-- in body — picture with AVIF/WebP/fallback + explicit dimensions -->
+<picture>
+  <source srcset="/hero.avif" type="image/avif">
+  <source srcset="/hero.webp" type="image/webp">
+  <img src="/hero.jpg" alt="..."
+       fetchpriority="high"
+       width="1600" height="900">
+</picture>
+```
+
+**Never** apply `loading="lazy"` to the LCP image. **Never** render the LCP
+image via client-side JS after hydration — server-render it or preload it.
+
+### INP fixes
+
+- Break any task > 50ms into `await scheduler.yield()` chunks (Chrome 129+;
+  fallback `await new Promise(r => setTimeout(r, 0))`).
+- Debounce input handlers to one frame (~16ms) when they trigger expensive
+  recomputes. Throttle scroll/resize to `requestAnimationFrame`.
+- Move CPU-bound work (parsing, transforming, encoding) off the main thread
+  with Web Workers when latency matters.
+- Avoid `setInterval` polling for data — use SWR / React Query / TanStack
+  Query with stale-while-revalidate.
+
+### CLS budget — zero unexpected shift
+
+- Every `<img>`, `<iframe>`, `<video>` declares `width` + `height` or
+  `aspect-ratio` CSS.
+- Web fonts: `font-display: optional` (no FOIT/FOUT shift, accept fallback
+  on first load) OR `size-adjust` + matching `ascent-override` /
+  `descent-override` / `line-gap-override` to produce a metric-compatible
+  fallback font.
+- Skeleton screens mirror the real layout dimensions exactly — a skeleton
+  that's the wrong height *causes* CLS instead of preventing it.
+- Inserted UI (banners, cookie notices, ads) must reserve space upfront via
+  `min-height` — never push existing content down post-paint.
+
+## Modern CSS (2025–2026)
+
+Default to platform features instead of JS shims:
+
+- **Container queries** (`@container` + `container-type: inline-size`) —
+  default for any component that lives in variable-width contexts (sidebar,
+  grid cell, modal). Component decides its own breakpoint, independent of
+  viewport. Use viewport-based `@media` only for app-shell-level layout.
+- **`:has()`** — collapse `useState` that exists *only for styling*
+  (e.g. label color reacting to input invalid state). Never put business
+  logic into `:has()` — only visual reactions to DOM state.
+- **View Transitions API** — `document.startViewTransition()` for SPA
+  navigation and `view-transition-name` for shared-element morphs. See
+  `motion-design/reference/accessibility-and-modern-apis.md` for the full
+  pattern.
+- **Subgrid** — children align to the parent grid without re-declaring
+  tracks. Fixes the long-standing "card content alignment across rows"
+  problem.
+- **Logical properties** — `margin-inline-start` / `padding-block` instead
+  of `margin-left` / `padding-top` whenever the project might add RTL or
+  vertical-writing-mode locales. Free i18n with zero overhead.
+- **`color-mix()`** — derive hover / focus / disabled states from semantic
+  tokens without inventing new tokens
+  (`color-mix(in oklch, var(--color-action-primary) 90%, black)`).
+- **`@scope`** — scope CSS to a subtree without selector specificity wars or
+  CSS-in-JS. Useful when migrating off CSS Modules / styled-components.
+
+## Form quality (always-on requirements)
+
+These apply to every form, every project — they are not "nice to have":
+
+- `<label>` associated to input via `htmlFor` / `id` (never wrap-only — fails
+  some screen readers).
+- `autocomplete=` filled for every personal-data field
+  (`email | tel | given-name | family-name | street-address | postal-code |
+  cc-number | one-time-code` …). Required by WCAG 2.1 SC 1.3.5.
+- Validation **on blur**, not on every keystroke. Re-validate on submit.
+- Error messages are **actionable** ("Email manca @ — esempio:
+  nome@dominio.it"), never generic ("Invalid input").
+- `aria-invalid` + `aria-describedby` linking the input to its error
+  element. Error element has `role="alert"` only when it appears
+  dynamically.
+- `inputMode=` set when it differs from `type` (e.g. `type="text"
+  inputMode="numeric"` for SMS codes — keeps the field text-shaped but
+  triggers the numeric keypad).
+- Paste handling normalizes whitespace and format BEFORE validating
+  (cc-number without spaces, tel without separators).
+- Submit button disabled only **after** a failed attempt — never blocked
+  pre-emptively; users should be allowed to try and receive feedback.
+
+---
+
 ## Prototipi Standalone e Demo
 
 Quando il task richiede un prototipo HTML interattivo, demo animata, slide deck, mockup iOS/app, o design exploration **NON legato alla codebase Next.js** (nessun contesto `src/app/`), invocare la skill `huashu-design` in aggiunta o al posto di questa skill. Essa fornisce:

package/framework/.claude/skills/motion-design/reference/accessibility-and-modern-apis.md

@@ -0,0 +1,114 @@
+# Accessibility & Modern Motion APIs
+
+## `prefers-reduced-motion` — collapse, don't disable
+
+```css
+:root {
+  --motion-duration-fast: 150ms;
+  --motion-duration-base: 250ms;
+  --motion-duration-slow: 400ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --motion-duration-fast: 0.01ms;
+    --motion-duration-base: 0.01ms;
+    --motion-duration-slow: 0.01ms;
+  }
+}
+```
+
+**Why 0.01ms, not 0?** Some Safari/WebKit versions skip the `transitionend`
+event entirely when duration is exactly `0` — state machines that wait on
+that event hang. `0.01ms` is functionally instant but keeps the event
+pipeline intact.
+
+**What stays vs. what goes** when reduced-motion is requested:
+
+- KEEP: opacity fades < 200ms (no vestibular impact), color cross-fades,
+  scale changes < 5%, subtle elevation changes.
+- COLLAPSE: translate / parallax / scale > 5% / rotate / skew / 3D
+  perspective / spring overshoot — anything with apparent motion across the
+  viewport.
+
+**Don't** apply a global `* { animation: none !important }` reset — that
+breaks loading spinners, focus indicators, and any animation that
+*communicates state*. Token-level collapse is the right primitive.
+
+## View Transitions API
+
+For same-document navigation (SPA route change, list ↔ detail, tab switch):
+
+```js
+function navigate(to) {
+  if (!document.startViewTransition) {
+    applyDom(to); // graceful fallback — no transition
+    return;
+  }
+  document.startViewTransition(() => applyDom(to));
+}
+```
+
+For shared-element morph (hero image survives the route change):
+
+```css
+.hero-image {
+  view-transition-name: hero-image; /* unique per shared element */
+}
+
+::view-transition-old(hero-image),
+::view-transition-new(hero-image) {
+  animation-duration: var(--motion-duration-base);
+  animation-timing-function: cubic-bezier(0.2, 0, 0, 1); /* emphasized */
+}
+```
+
+For cross-document transitions (MPA, Chrome 126+, behind opt-in CSS):
+
+```css
+@view-transition { navigation: auto; }
+```
+
+**Accessibility**: View Transitions automatically respect
+`prefers-reduced-motion` when the page exposes the reduced-motion media
+query — no extra wiring needed beyond the token collapse above.
+
+**Use it for**: navigation, list ↔ detail morphs, sort / filter reorders,
+modal hero reveal. **Don't use it for**: per-frame interactive feedback
+(hover, focus, drag) — those need direct CSS / spring animations.
+
+## Spring vs. timing function — when to pick which
+
+| Use case | Pick |
+|---|---|
+| Direct manipulation (drag release, swipe, pull-to-refresh) | Spring |
+| Page / view transition | Cubic-bezier (deterministic, easy to choreograph) |
+| Acknowledgment / tap feedback | Cubic-bezier (short, predictable) |
+| Interruptible animation that should "settle naturally" | Spring |
+| Stagger choreography | Cubic-bezier (timeline easier to reason about) |
+
+**Spring rule of thumb**: stiffness 250–350 + damping 18–24 = "standard
+feel". Higher stiffness = snappier; lower damping = more oscillation. Cap
+total settle time at 600ms — beyond that the user perceives "lag", not
+physicality.
+
+## Choreography budget
+
+- Single-element transition: 100–500ms (see `timing-easing-tables.md`).
+- Stagger of multiple children: each child delay 30–50ms, **total budget
+  ≤ 600ms** (faster on dense lists — cap at 400ms for >10 items).
+- Page-load sequence: hero ≤ 250ms, secondary content stagger ≤ 400ms
+  total. Beyond that the user is staring at incomplete UI.
+
+## Animation that communicates state — never collapse these
+
+Reduced-motion does NOT mean *no feedback*. Always preserve:
+
+- Focus ring appearance (instant is fine — but visible).
+- Loading indicators (a static spinner or skeleton is still feedback).
+- Validation error appearance (color + icon — duration can be 0).
+- Toast / notification appearance (fade-in opacity ≤ 200ms is acceptable
+  under reduced-motion).
+
+Stripping these leaves users without feedback that an action registered —
+worse than the animation they tried to avoid.

package/framework/.claude/skills/ui-design/SKILL.md

@@ -32,6 +32,11 @@ Evaluation is always performed by a separate agent with fresh context.
 
 ## Prerequisites — BLOCKING reads before ANY design work
 
+The registry-first cascade below is the consumer view of the SSOT in
+[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md).
+When the cascade rules diverge between this file and the protocol module,
+the protocol module wins.
+
 These reads are BLOCKING. Resolve paths from `baldart.config.yml` before opening files. If `features.has_design_system: true`, item 1 is the mandatory entry point and skipping it is a protocol violation.
 
 1. **MANDATORY / BLOCKING when `features.has_design_system: true`** — read `${paths.design_system}/INDEX.md` (the design-system entry point: component index, authority matrix, token contract, any project-specific theming pairing rules and overlay decision tree).
@@ -141,6 +146,43 @@ Read [references/inventory.md](references/inventory.md).
 3. Update state file with chosen option, design decisions, component lists.
 4. Clean up `/tmp/prd-design-<slug>/`.
 
+### Step H — Registry Coherence Reconciliation (BLOCKING completion gate)
+
+When `features.has_design_system: true`, the design is not complete until the
+component registry reflects every primitive the chosen design depends on. Run
+the **Post-Intervention Coherence Check** defined in
+[`framework/agents/design-system-protocol.md`](../../../agents/design-system-protocol.md)
+§ "Post-Intervention Coherence Check".
+
+Concretely, walk the UI Element Inventory from Step G and for each item:
+
+1. **Registry-hit confirmed**: the primitive exists in `${paths.design_system}/INDEX.md`
+   AND its `components/<Name>.md` spec matches the way the design uses it
+   (props, variants, accessibility). If the design uses a variant not yet
+   documented, update the spec inline.
+2. **Source-tree-hit silent primitive**: the primitive exists under
+   `${paths.components_primitives}` but not in `INDEX.md`. Add the INDEX entry
+   inline (full spec or stub `status: needs-review`, see decision matrix in the
+   protocol).
+3. **New primitive proposed by the design**: it has no source implementation
+   AND no spec. Either:
+   - scaffold the spec + INDEX entry now as part of the inventory deliverable, OR
+   - open a follow-up card and **flag the gap explicitly** in the inventory so
+     downstream implementation work cannot proceed without resolution.
+4. **Token additions**: the design introduces a color / spacing / shadow / motion
+   value not present in `${paths.design_system}/tokens-reference.md`. Update the
+   reference inline OR open a follow-up token-addition card before approval.
+
+Surface every finding in the design handoff with the standard codes
+(`DS_INDEX_DRIFT` / `DS_COMPONENT_STALE` / `DS_TOKENS_DRIFT`). Silent
+reconciliation is forbidden — the user must see the drift that was found and
+how it was resolved (inline vs. follow-up card).
+
+This step exists because the design phase is where drift is **cheapest to
+prevent**: catching a duplicate primitive at the mockup stage costs minutes,
+catching it after implementation costs a refactor. The weekly `ds-drift`
+routine is a safety net, not a substitute for this check.
+
 ---
 
 ## Design Principles (quick reference)
@@ -153,6 +195,7 @@ These are enforced — read `${paths.ui_guidelines}` for full spec.
 - **Multi-tenant theming pairing**: when `features.multi_tenant_theming: true`, themed text-token paired with themed bg-token per the project's theming pattern doc
 - **View State Trinity**: loading (skeletons), error (localized message + retry), empty (CTA). The error language follows `identity.language`.
 - **Separation of concerns**: UI / business logic / data layers stay separate
+- **Registry coherence (BLOCKING)**: when `has_design_system: true`, every primitive in the chosen design is reconciled with `INDEX.md` + `components/<Name>.md` + `tokens-reference.md` before sign-off (Step H). New primitive ⇒ new spec same change. Modified primitive ⇒ updated spec same change. Silent reuse of undocumented primitive ⇒ INDEX entry added now
 
 ---