@pilotspace/add 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 `pilotspace-add` on PyPI) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
+## [1.5.0] — 2026-06-16
+
+The UDD design-loop release: defining the design *before* the code is now a
+guided, evidence-backed loop inside the method. A new `design.md` drives the UDD
+beats to a confirmed screen, a wireframe + HTML-mock recipe renders a real screen
+the human approves before build, and the engine measures that the confirmation
+was actually captured. All additive; no breaking changes (SemVer MINOR).
+
+### Added
+- **UDD design-definition loop (`design.md`)** — turns the foundation's UDD
+  concern into a runnable loop: a low-fi structural wireframe → a self-contained
+  HTML mock (resolve semantic tokens → one kit class per component → compose the
+  prototype tree → populate with mock data) → a captured screen the human
+  confirms *before* any build. Wired into `0-setup` and `1-specify`.
+- **Wireframe + HTML-mock recipe (`udd-wireframe.md`) + sample templates** — a
+  zero-dependency, any-stack floor for rendering a prototype tree into a real
+  screen, with a worked sample set (`tokens.sample.css`, `kit.sample.css`,
+  `welcome.sample.html`, `settings.sample.html` reusing the kit,
+  `wireframe.sample.txt`). One semantic-token flip re-themes every screen by
+  construction. An optional `@json-render/image` (Satori → PNG/SVG, no browser)
+  fast path is noted for JS-ecosystem projects.
+- **Capture-evidence convention + `missing_capture` WARN** — design captures live
+  at `.add/design/captures/<name>.<ext>`; `add.py check` emits a never-red
+  `missing_capture` warning for any prototype lacking a capture (silent when
+  absent, so non-UI projects stay clean). The engine *measures* capture presence;
+  it never renders.
+
 ## [1.4.0] — 2026-06-15
 
 The guided-onboarding release: starting and running an ADD project is now guided

package/docs/14-foundation.md

@@ -47,6 +47,17 @@ the method already names, made explicit as three concerns.
   test that behaviour; the foundation keeps the design intent that makes a screen
   worth building.
 
+When a milestone has screens, UDD is not only a static `DESIGN.md` — it runs a
+**design-definition loop** that turns the domain into a screen the human has *seen
+and confirmed before build*. Its four beats are `review-domain → research-components
+→ wireframe → render-capture-confirm`: read the domain into screens and regions,
+research and reuse components before inventing them, wireframe the structure low-fi,
+then render a real screen and **capture** it. That capture is the **design-confirm**
+evidence — a real image the person approves *before* implementation, so the build
+matches the layout instead of discovering it. The book keeps the *why*; the
+operational recipe (the wireframe format, the token-bound mock, the capture engines)
+lives in the `add` skill's `design.md` and `udd-wireframe.md`.
+
 These three foundation competencies, together with the **TDD ⇄ ADD** engine of
 [Part II](./02-the-flow.md), are ADD's five. The first four feed context to the
 fifth, where the AI executes on it:

package/docs/appendix-c-glossary.md

@@ -108,6 +108,14 @@
 
 **Newest-first append-only** — every append-only foundation sequence prepends the newest record at the top; the rolled-up settled line anchors at the bottom (the oldest end), so compaction collapses upward.
 
+**Wireframe** — the Stage-A low-fidelity, *structural* map of one screen: its regions and the component **slots** inside them, derived from `prototypes/<name>.json` *before* any color, type, or spacing — it answers "what goes where", not "what it looks like". Beat 3 of the UDD **design-definition loop**; the low-fi half of the two-stage fidelity that ends in a confirmed capture. See the `add` skill's `udd-wireframe.md` (Stage A).
+
+**Design mock** — the Stage-B high-fidelity, **self-contained** HTML render of a screen: the `catalog.json` components as a reusable token-bound kit, bound to `tokens.json` and populated with mock data, openable offline and screenshot-able. The human-facing *visible* evidence the human confirms (the frozen `prototypes/<name>.json` tree is its machine-checkable twin). Beat 4's hi-fi artifact; the recipe lives in the `add` skill's `udd-wireframe.md` (Stage B).
+
+**Capture** — the real rendered image (PNG/SVG) of a design mock: the **design-confirm evidence** artifact. Captures live at `.add/design/captures/<name>.<ext>` (one per prototype) and are attached or mentioned in the feature's `TASK.md`; `@json-render/image` (Satori → PNG/SVG, no browser) is the named default capture engine, otherwise the self-contained mock is screenshot headless. The engine never renders — it only MEASURES presence: `add.py check` raises a never-red `missing_capture` WARN for a prototype with no capture.
+
+**Design-confirm** — the human touchpoint closing the UDD **design-definition loop** (`review-domain → research-components → wireframe → render-capture-confirm`, beat 4 of the `add` skill's `design.md`): approving the captured screen image **before build**, show-before-ask, so the implementation matches the layout the human has already seen instead of discovering it.
+
 ---
 
 ## Optional mapping to formal phase names

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "ADD (AI-Driven Development) — a minimal, state-tracked Claude Code skill that drives every feature through Specify → Scenarios → Contract → Tests → Build → Verify → Observe. Ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/SKILL.md

@@ -106,6 +106,11 @@ template, the tier pick — read `advisor.md`; and at any decision point self-sc
 (0–1 across six dimensions, refine if any < 0.9) with `confidence.md`. Both are advisory: the
 engine never spawns, and the self-score is never a gate.
 
+When a **UI feature** reaches specify, run the **design-definition loop** in `design.md` (UDD):
+review the domain → research and reuse components → wireframe → render a real captured screen the
+human confirms **before** build — so the build matches the expected layout. Tool-agnostic; the
+engine never renders.
+
 When a milestone's tasks are all done but its **goal** (the `MILESTONE.md` exit criteria) is not
 yet met, `milestone-done` holds the milestone open — read `loop.md` for the dynamic loop that turns
 open deltas + extras into the next tasks, proposed by you and confirmed by the human, until the goal is met.

package/skill/add/design.md

@@ -0,0 +1,92 @@
+# Design — the design-definition loop (UDD)
+
+When a **UI feature** reaches specify, design it before you build it. This loop takes the
+feature from the **domain** to a screen the human has **seen and confirmed** — a real captured
+image — *before* any implementation, so the build matches the expected layout instead of
+discovering it. It is loaded on demand (like `advisor.md` / `confidence.md`); the engine never
+runs it for you.
+
+Design before code is the UDD half of the method. The token + component foundation a UI project
+draws from already exists — `tokens.json` (the compact-DTCG dialect, `udd-tokens.md`),
+`catalog.json` + `prototypes/<name>.json` (`udd-catalog.md`). This loop is how you *fill* that
+foundation for a feature and earn the human's sign-off on the look before build.
+
+## The loop — four beats
+
+```
+review-domain  →  research-components  →  wireframe  →  render-capture-confirm
+```
+
+Run the beats in order. Each feeds the next; the last ends at a human design-confirm.
+
+### 1 · review-domain
+Start from the **domain**, not from a blank canvas. Read the domain model — entities, flows, the
+ubiquitous language in `PROJECT.md` / `GLOSSARY.md` — and derive **which screens** the feature
+needs and the **regions** each screen holds. Map each domain entity to a *presentational*
+component (it shows state; it does not own a domain decision). The screen list + per-screen
+regions are this beat's output, and they are grounded in the domain you just read.
+
+### 2 · research-components (reuse before you invent)
+Check `catalog.json` **first** and **reuse** the components already there — that is what keeps
+screens consistent. Research a reference UI (a websearch over pattern galleries / component
+libraries for this kind of screen) only to fill a **genuine gap**, and propose a **new** catalog
+component for that gap with a **cited** reference. Reuse before invention; a new component is the
+exception, named and justified, not the default.
+
+### 3 · wireframe
+Draw a **low-fi**, **structural** layout for each screen — regions and component slots, no
+styling, no color. This is the cheapest possible artifact that shows the *expected layout*, so
+the human can correct the structure before a pixel is styled. Confirm the wireframe, then move on.
+
+### 4 · render-capture-confirm
+Render the screen as a **self-contained HTML mock** — the project's component library via CDN,
+bound to `tokens.json` (resolved to CSS variables), composed from the **reusable per-component
+kit** (one token-bound partial per catalog component), populated with realistic **mock** data.
+**Capture** a real image of it (a headless screenshot) and present that image to the human for
+**design-confirm** — show-before-ask, **before build**. On confirm, record the layout back to
+`prototypes/<name>.json` + `catalog.json`, save the captured image to
+`.add/design/captures/<name>.<ext>`, and **attach or mention it in the feature's `TASK.md`**
+(alongside the §6 evidence) — so the screen the human approved is traceable from the task that
+builds it. The HTML mock is the *visible evidence*; the json-render tree is the
+*machine-checkable* record of the same screen.
+
+## Tool-agnostic capture
+
+How you render and capture is **your** choice, not the engine's: a headless browser
+(Playwright / Puppeteer), an `html2image`-style renderer, a browser-automation skill, a design
+tool, or a hosted screenshot service — whatever the agent has. The recommended default is the
+self-contained HTML mock above, captured headless, because it needs no app build yet still wears
+the project's real tokens and component vocabulary. For a project that renders json-render, the
+recommended default is **`@json-render/image`** (Satori → PNG/SVG, no browser) — a deterministic
+`Spec` → image. The captured image is a **design-confirm evidence** artifact the human approves;
+it is never an engine output, and the engine never renders. This keeps the loop tool-agnostic and
+the method renderer-free.
+
+Captures live at **`.add/design/captures/<name>.<ext>`** (one per prototype) and are
+attached/mentioned in the feature's `TASK.md`. `add.py check` raises a never-red
+`missing_capture` WARN for any prototype under `.add/design/prototypes/` that still lacks a
+capture — a nudge to render + confirm it, never a blocker.
+
+The loop **binds** the existing UDD contracts **read-only**: `tokens.json`, `catalog.json`, and
+`prototypes/<name>.json` are read and composed, never reshaped — the `prototypes/<name>.json`
+data contract stays **unchanged** (a change to it is a change request, not a design step). And
+**identity** values — brand color, palette, typeface — stay **human-owned**: surface them for the
+human to decide, never auto-pick a brand value (`udd-tokens.md`).
+
+## The hard rules
+
+<constraints>
+- **Domain first.** A screen is derived from the domain (beat 1), never sketched blind.
+- **Reuse before invent.** Beat 2 checks the catalog first; a new component is a justified,
+  cited exception — never the reflex.
+- **Confirm before build.** The captured image is approved by the human *before* implementation;
+  a design-confirm placed at or after build defeats the loop.
+- **The engine never renders.** Capture is a recommended, tool-agnostic recipe run by the
+  agent's own tools; the image is evidence, not an engine artifact.
+- **Bind, don't break.** The loop reads `tokens.json` / `catalog.json` / `prototypes/<name>.json`
+  read-only; the data contract is unchanged, and identity values stay human-owned.
+</constraints>
+
+> Used at specify for a UI feature: `phases/0-setup.md` scaffolds `DESIGN.md`, and
+> `phases/1-specify.md` points here when the feature has a screen — run the four beats, then
+> carry the confirmed layout into the contract.

package/skill/add/phases/0-setup.md

@@ -74,7 +74,8 @@ gate: auto-complete NEVER skips the human baseline approval — the `lock` (§4)
 1. **Fill the living documentation** (it outlives all code): `.add/PROJECT.md` (the foundation — Domain · Spec/active
    milestone · UI/UX · Key Decisions, one screen), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`,
    `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (the design source of truth: identity ·
-   principles · screens · the named-set foundation pointers + render recipe; delete it if there's no UI).
+   principles · screens · the named-set foundation pointers + render recipe; delete it if there's no UI;
+   the design-definition loop that fills it — domain → components → wireframe → a captured screen confirmed before build — is `design.md`).
    Brownfield: from the code. Greenfield: from the interview, gaps flagged `guessed`.
 2. **Propose, then size it.** You just read the codebase (brownfield) or interviewed (greenfield) — so
    don't silently draft. First float a **kickoff suggestion** for the first milestone the human reacts to:

package/skill/add/phases/1-specify.md

@@ -18,7 +18,9 @@ understand the feature — that is information, not an obstacle. Stop and ask.
 **Identity is direction, not default (UDD).** For UI/design work, identity values — the brand
 color, the core palette, the typeface — are human-owned. Surface them for discussion during
 Diverge; never assume a brand value. The UDD token dialect checks a token's *shape*; its *value*
-is the user's call (`udd-tokens.md`).
+is the user's call (`udd-tokens.md`). For a UI feature with a screen, run the design-definition
+loop in `design.md` — domain → research and reuse components → wireframe → a real captured screen
+the human confirms before build — and carry the confirmed layout into the contract.
 
 ## Produce (in TASK.md §1)
 

package/tooling/add.py

@@ -1606,6 +1606,27 @@ def _udd_named_set_checks(root: Path) -> list[tuple[bool, str, str]]:
     return out
 
 
+_CAPTURE_EXTS = ("png", "svg", "jpg", "jpeg", "webp")
+
+
+def _missing_captures(root: Path) -> list[str]:
+    """Prototype names under `.add/design/prototypes/` lacking a design-confirm capture.
+
+    A prototype `<name>.json` is CAPTURED iff a file `.add/design/captures/<name>.<ext>`
+    exists (ext in _CAPTURE_EXTS). Returns the uncaptured names in document (sorted) order.
+    PURE · TOTAL (missing dirs -> []) · READ-ONLY (never writes, never renders): the engine
+    MEASURES capture presence; producing the image is the agent's tool-agnostic choice
+    (design.md beat 4; default `@json-render/image`). [] == every prototype captured / none exist.
+    """
+    proto_dir = root / "design" / "prototypes"
+    cap_dir = root / "design" / "captures"
+    if not proto_dir.is_dir():
+        return []
+    names = sorted(p.stem for p in proto_dir.glob("*.json") if p.is_file())
+    return [n for n in names
+            if not any((cap_dir / f"{n}.{ext}").is_file() for ext in _CAPTURE_EXTS)]
+
+
 def cmd_check(args: argparse.Namespace) -> None:
     """Read-only integrity check of the .add project. Exit 1 if anything fails."""
     as_json = getattr(args, "json", False)
@@ -1772,6 +1793,16 @@ def cmd_check(args: argparse.Namespace) -> None:
     # Silent when absent; read-only; fail-closed on malformed JSON.
     checks.extend(_udd_named_set_checks(root))
 
+    # capture-evidence: a never-red WARN naming each prototype with no design-confirm capture
+    # at .add/design/captures/<name>.<ext>. Measure-never-block — rides `warnings`, NEVER
+    # `checks` (so never feeds `failed`); silent-when-absent (no prototypes -> []). The engine
+    # MEASURES capture presence; producing the image is the agent's tool-agnostic choice.
+    for _pname in _missing_captures(root):
+        warnings.append(("missing_capture",
+                         f"prototype '{_pname}' has no design-confirm capture at "
+                         f".add/design/captures/{_pname}.<png|svg|…> — render + confirm it "
+                         "before build (design.md beat 4)"))
+
     passed = sum(1 for ok, _, _ in checks if ok)
     failed = len(checks) - passed
     if as_json:

package/tooling/templates/kit.sample.css

@@ -0,0 +1,53 @@
+/* kit.sample.css — one class per catalog.sample.json component (the reusable kit).
+   Every visual value resolves a var(--…) from tokens.sample.css — no literals here, so
+   a token flip in tokens.sample.css restyles every screen that composes from this kit.
+   Screens use these classes and style nothing inline. */
+
+/* Screen — the root viewport container */
+.screen {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  min-height: 100vh;
+  gap: var(--semantic-space-inset-md);
+  padding: var(--semantic-space-inset-md);
+  background: var(--semantic-color-surface);
+  font-family: var(--primitive-font-family-sans);
+}
+
+/* Card — a surface that groups related content */
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--semantic-space-inset-sm);
+  width: 100%;
+  max-width: 360px;
+  padding: var(--semantic-space-inset-md);
+  background: var(--semantic-color-surface);
+  border-radius: var(--semantic-space-inset-sm);
+}
+
+/* Text — a run of styled text */
+.text {
+  margin: 0;
+  line-height: 1.5;
+  color: var(--semantic-color-text);
+  font-family: var(--primitive-font-family-sans);
+}
+.text--bold { font-weight: var(--primitive-font-weight-bold); }
+.text--regular { font-weight: var(--primitive-font-weight-regular); }
+
+/* Button — a primary call-to-action */
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--semantic-space-inset-sm) var(--semantic-space-inset-md);
+  border: 0;
+  border-radius: var(--semantic-space-inset-sm);
+  background: var(--semantic-color-accent);
+  color: var(--semantic-color-surface);
+  font-family: var(--primitive-font-family-sans);
+  font-weight: var(--primitive-font-weight-bold);
+  cursor: pointer;
+}

package/tooling/templates/settings.sample.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<!-- settings.sample.html — a SECOND screen that proves REUSE. It composes from the SAME
+     kit classes (screen/card/text/button) and links the SAME tokens.sample.css +
+     kit.sample.css as welcome. It redefines nothing — no per-screen stylesheet, no inline
+     styles — so a single semantic-token flip in tokens.sample.css re-renders BOTH screens
+     identically. This is consistency by construction. -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Settings — design mock</title>
+  <link rel="stylesheet" href="tokens.sample.css">
+  <link rel="stylesheet" href="kit.sample.css">
+</head>
+<body>
+  <!-- reuses the welcome kit: Screen > Card > {Text, Text, Button} -->
+  <main class="screen">
+    <section class="card">
+      <h1 class="text text--bold">Settings</h1>
+      <p class="text text--regular">Manage your workspace preferences.</p>
+      <button class="button" type="button">Save changes</button>
+    </section>
+  </main>
+</body>
+</html>

package/tooling/templates/tokens.sample.css

@@ -0,0 +1,23 @@
+/* tokens.sample.css — tokens.sample.json resolved to CSS custom properties.
+   The SINGLE source of token values. Literals live ONLY here; the kit and the
+   screens reference var(--semantic-*). Flip one --semantic-* line below and EVERY
+   screen that links this file re-renders the same way. */
+:root {
+  /* primitive — raw values (the only literals in the whole sample) */
+  --primitive-color-blue-500: #3B82F6;
+  --primitive-color-slate-900: #0F172A;
+  --primitive-color-white: #FFFFFF;
+  --primitive-space-2: 8px;
+  --primitive-space-4: 16px;
+  --primitive-font-family-sans: "Inter", system-ui, sans-serif;
+  --primitive-font-weight-regular: 400;
+  --primitive-font-weight-bold: 700;
+
+  /* semantic — alias the primitives; THIS is the layer screens bind to.
+     Repoint one of these to re-theme every screen at once. */
+  --semantic-color-accent: var(--primitive-color-blue-500);
+  --semantic-color-text: var(--primitive-color-slate-900);
+  --semantic-color-surface: var(--primitive-color-white);
+  --semantic-space-inset-sm: var(--primitive-space-2);
+  --semantic-space-inset-md: var(--primitive-space-4);
+}

package/tooling/templates/udd-wireframe.md

@@ -0,0 +1,118 @@
+# UDD wireframe + HTML mock — make the layout visible before build
+
+`udd-tokens.md` says what a UI is *made of*; `udd-catalog.md` says what it is *built
+from*. Both are abstract JSON. This doc closes the last gap design.md names: turn a
+prototype tree into a **real, captured screen the human confirms BEFORE build** — so
+the build matches the expected layout instead of discovering it.
+
+Two stages, low-fi → hi-fi:
+
+- **Stage A — wireframe**: a fast, low-fi *structural* map. No styling.
+- **Stage B — HTML mock**: a self-contained screen the human (or a headless tool)
+  actually renders and screenshots. The image is the design-confirm evidence.
+
+The engine never renders. This is a recommendation + a worked sample, tool-agnostic
+(consistent with `udd-catalog.md`'s render recipe). A worked pair ships beside it —
+`welcome.sample.html` + `settings.sample.html` — that you can open in any browser.
+
+## Stage A — wireframe (low-fi, structural)
+
+A **wireframe** is a low-fidelity, *structural* map of one screen — regions and the
+component **slots** inside them — derived directly from the prototype tree, **before**
+any color, type scale, or spacing is decided. It answers "what goes where", not "what
+it looks like".
+
+Derive it mechanically from `prototypes/<name>.json`: each container element is a
+region, each leaf element is a slot, the tree's nesting is the layout nesting. Keep it
+in plain text or boxes — the point is speed and a shared structural picture, not paint.
+
+Worked example: `wireframe.sample.txt` is the Stage-A map of the welcome screen
+(`Screen > Card > {Text, Text, Button}`), with each slot mapped 1:1 to its prototype
+element. No colors, no pixel values — those arrive in Stage B.
+
+## Stage B — HTML mock (hi-fi, self-contained, screenshot-able)
+
+The mock is a real screen built from the design foundation in **four moves**:
+
+1. **Resolve `tokens.json`'s `semantic` layer → CSS custom properties.** Each
+   `{semantic.dotted.path}` alias becomes a `--semantic-dotted-path` variable in a
+   `:root` block. This file is the single source of token values — see
+   `tokens.sample.css`.
+2. **One kit class per `catalog.json` component.** Each component (Screen, Card, Text,
+   Button, …) gets exactly one CSS class whose every visual value is a `var(--…)` from
+   step 1 — never a literal. This is the reusable **kit** — see `kit.sample.css`.
+3. **Compose the prototype tree into HTML using the kit classes.** Walk
+   `prototypes/<name>.json`: each element becomes an HTML node carrying its
+   component's kit class; nesting follows `children`. Style nothing inline.
+4. **Populate with mock data.** Fill the `Text`/`Button` content from the prototype's
+   props (or representative stand-ins). The result is a **self-contained** screen —
+   *no network*: it links only local sibling files — that opens offline and a
+   **headless** tool can **screenshot** directly (Playwright, `html2image`,
+   an agent browser, or a SaaS renderer — pick one; the engine never renders).
+
+`welcome.sample.html` is the worked Stage-B mock of `prototype.sample.json`.
+
+## Fast path — render via json-render (for JS-ecosystem projects)
+
+Your `prototypes/<name>.json` is already a **json-render `Spec`** — the exact schema
+`udd-catalog.md` pins. If your project renders json-render (React, Vue, Svelte, Solid,
+React Native, …) you can skip the hand-authored kit and render the prototype through
+your *real* catalog, so the mock **is** the product and cannot drift from it:
+
+- **Render** — feed `prototype.json` into your `defineCatalog(…)` (see `udd-catalog.md`'s
+  "Render recipe"), or use a pre-built catalog such as `@json-render/shadcn` (36
+  shadcn/ui components) — no hand-written components for those stacks.
+- **Capture** — `@json-render/image` renders a `Spec` straight to **PNG / SVG** (Satori,
+  no browser), a deterministic captured image with no headless-screenshot step. That
+  image is the same design-confirm evidence (see "Capture is evidence").
+
+Trade-off — this is the *fast path*, not the floor. json-render needs the JS/npm
+toolchain + a renderer package, so it does NOT cover a native (SwiftUI / Flutter / …)
+project, and it has **no wireframe mode** (Stage A stays a separate, renderer-agnostic
+structural artifact). When there is no toolchain, or the stack is not JS, the
+self-contained HTML + CSS mock above is the universal default.
+
+## Reuse & consistency (by construction)
+
+Screens compose **only** from the shared kit + token vars — never hand-styled per
+screen. Because every screen links the *same* `tokens.sample.css` + `kit.sample.css`,
+a single **semantic-token flip** (one line in `tokens.sample.css`) re-renders **every**
+screen the same way. Reuse before invent: pull an existing kit class first; add a new
+one only for a genuine new `catalog.json` component.
+
+`settings.sample.html` is a SECOND screen that **reuses** the welcome kit classes
+(screen/card/text/button) without redefining them — proving the consistency: flip
+`--semantic-color-surface` once and both screens change together.
+
+## Capture is evidence
+
+The screenshot of a Stage-B mock is **design-confirm evidence** — the human-facing
+proof of beat 4 in `design.md`. Captures live at **`.add/design/captures/<name>.<ext>`**
+(one per prototype) and are **attached or mentioned in the feature's `TASK.md`**
+(alongside the §6 evidence), so the screen the human approved stays traceable from the
+task that builds it. The recommended default capture engine for a json-render project is
+**`@json-render/image`** (Satori → PNG/SVG, no browser); otherwise capture the
+self-contained HTML mock headless. The engine never produces this image — it only
+MEASURES presence (`add.py check` raises a never-red `missing_capture` WARN for a
+prototype with no capture); the capture recipe is a recommendation, not an engine feature.
+
+## Binds (read-only)
+
+This recipe **consumes** the UDD contracts and never reshapes them:
+
+- `tokens.json` — the semantic layer is the source of the CSS variables (unchanged).
+- `catalog.json` — its component set is the source of the kit classes (unchanged).
+- `prototypes/<name>.json` — the json-render tree is the structure both stages walk
+  (unchanged; the frozen data contract is read-only — a change there is a separate
+  change-request).
+
+The mock (`*.sample.html`) is the human-facing *visible* view; the frozen
+`prototypes/<name>.json` tree is the *machine-checkable* record. They are two views of
+one screen.
+
+## Ships byte-identical
+
+`udd-wireframe.md` and its five sample files ship **byte-identical** in both template
+trees (canonical `tooling/templates/` and the `_bundled` mirror) — enforced by
+`test_bundle_parity`. A file present in one tree but missing from the other is a
+`parity_break`.

package/tooling/templates/welcome.sample.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<!-- welcome.sample.html — Stage-B HTML mock of prototype.sample.json (the welcome screen).
+     Self-contained (no network): links only the local shared stylesheets. Composes ONLY
+     from the kit classes in kit.sample.css and styles nothing inline. A headless tool
+     screenshots this file directly; that image is the design-confirm evidence
+     (see udd-wireframe.md, "Capture is evidence"). -->
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Welcome — design mock</title>
+  <link rel="stylesheet" href="tokens.sample.css">
+  <link rel="stylesheet" href="kit.sample.css">
+</head>
+<body>
+  <!-- prototype tree: Screen > welcome-card(Card) > {title(Text), subtitle(Text), cta(Button)} -->
+  <main class="screen">
+    <section class="card">
+      <h1 class="text text--bold">Welcome to ADD</h1>
+      <p class="text text--regular">Spec-and-tests-first, render-ready.</p>
+      <button class="button" type="button">Get started</button>
+    </section>
+  </main>
+</body>
+</html>

package/tooling/templates/wireframe.sample.txt

@@ -0,0 +1,27 @@
+WIREFRAME — welcome screen (Stage A · low-fi · pre-styling)
+derived from: prototypes/welcome.json  (Screen > Card > Text, Text, Button)
+
++--------------------------------------------------+
+|  SCREEN   [region: full viewport]                |
+|                                                  |
+|     +--------------------------------------+     |
+|     |  CARD   [region: centered group]     |     |
+|     |                                      |     |
+|     |   [ Text slot ]    title  (bold)     |     |
+|     |   [ Text slot ]    subtitle          |     |
+|     |   [ Button slot ]  primary CTA       |     |
+|     |                                      |     |
+|     +--------------------------------------+     |
+|                                                  |
++--------------------------------------------------+
+
+slots map one-to-one to prototype elements:
+  SCREEN  ->  Screen   (root)
+  CARD    ->  Card     (welcome-card)
+  Text    ->  Text     (title, subtitle)
+  Button  ->  Button   (cta)
+
+notes:
+  - structure only — no color, no type scale, no spacing values yet
+  - styling arrives in Stage B (kit.sample.css bound to tokens.sample.css)
+  - confirm the STRUCTURE here is right before investing in the hi-fi mock