@tekyzinc/gsd-t 2.53.11 → 2.54.11

package/README.md

@@ -12,7 +12,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Generates visual scan reports** — every `/gsd-t-scan` produces a self-contained HTML report with 6 live architectural diagrams, a tech debt register, and domain health scores; optional DOCX/PDF export via `--export docx|pdf`.
 **Self-learning rule engine** — declarative rules in rules.jsonl detect failure patterns from task metrics. Candidate patches progress through a 5-stage lifecycle (candidate, applied, measured, promoted, graduated) with >55% improvement gates before becoming permanent methodology artifacts.
 **Cross-project learning** — proven rules propagate to `~/.claude/metrics/` and sync across all registered projects via `update-all`. Rules validated in 3+ projects become universal; 5+ projects qualify for npm distribution. Cross-project signal comparison and global ELO rankings available via `gsd-t-metrics --cross-project` and `gsd-t-status`.
-**Stack Rules Engine** — auto-detects project tech stack (React, TypeScript, Node API, Python, Go, Rust) from manifest files and injects mandatory best-practice rules into subagent prompts at execute-time. Universal security rules always apply; stack-specific rules layer on top. Extensible: drop a `.md` file in `templates/stacks/` to add a new stack.
+**Stack Rules Engine** — auto-detects project tech stack (React, TypeScript, Node API, Python, Go, Rust) from manifest files and injects mandatory best-practice rules into subagent prompts at execute-time. Universal security rules always apply; stack-specific rules layer on top. Includes **design-to-code** rules for pixel-perfect frontend implementation from Figma, screenshots, or design images — with Figma MCP integration, design token extraction, stack capability evaluation, and visual verification loops. Extensible: drop a `.md` file in `templates/stacks/` to add a new stack.
 **Self-Calibrating QA** — `qa-calibrator.js` tracks QA miss-rates across milestones, detects weak-spot categories (error paths, boundaries, state transitions), and automatically injects targeted guidance into QA subagent prompts. Projects on the same stack share miss-rate data for faster calibration.
 **Token-Aware Orchestration** — `token-budget.js` tracks session token consumption and applies graduated degradation: downgrade model assignments when approaching limits, checkpoint and skip non-essential operations to conserve budget, and halt cleanly with a resume instruction at the ceiling. Wave and execute phases check budget before each subagent spawn.
 **Quality North Star** — projects define a `## Quality North Star` section in CLAUDE.md (1–3 sentences, e.g., "This is a published npm library. Every public API must be intuitive and backward-compatible."). `gsd-t-init` auto-detects preset (library/web-app/cli) from package.json signals; `gsd-t-setup` configures it for existing projects. Subagents read it as a quality lens; absent = silent skip (backward compatible).
@@ -343,7 +343,7 @@ get-stuff-done-teams/
 │   ├── branch.md                      # Git branch helper
 │   ├── checkin.md                     # Auto-version + commit/push helper
 │   └── Claude-md.md                   # Reload CLAUDE.md directives
-├── templates/                         # Document templates (9 base + stacks/)
+├── templates/                         # Document templates (10 base + stacks/)
 │   ├── CLAUDE-global.md
 │   ├── CLAUDE-project.md
 │   ├── requirements.md
@@ -353,10 +353,12 @@ get-stuff-done-teams/
 │   ├── progress.md
 │   ├── backlog.md
 │   ├── backlog-settings.md
+│   ├── design-contract.md             # Design-to-code token extraction template
 │   └── stacks/                        # Stack Rules Engine templates
 │       ├── _security.md               # Universal — always injected
 │       ├── react.md
 │       ├── typescript.md
+│       ├── design-to-code.md          # Pixel-perfect design implementation
 │       └── node-api.md
 ├── scripts/                           # Runtime utility scripts (installed to ~/.claude/scripts/)
 │   ├── gsd-t-tools.js                 # State CLI (get/set/validate/list)

package/commands/gsd-t-debug.md

@@ -53,6 +53,8 @@ if [ -d "$STACKS_DIR" ]; then
   ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && _add playwright.md
   [ -f "go.mod" ] && _add go.md
   [ -f "Cargo.toml" ] && _add rust.md
+  # Design-to-code detection (design contract, design tokens, or Figma config)
+  ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && _add design-to-code.md
 fi
 ```
 

package/commands/gsd-t-execute.md

@@ -193,6 +193,8 @@ if [ -d "$STACKS_DIR" ]; then
   ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && _add playwright.md
   [ -f "go.mod" ] && _add go.md
   [ -f "Cargo.toml" ] && _add rust.md
+  # Design-to-code detection (design contract, design tokens, or Figma config)
+  ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && _add design-to-code.md
 fi
 ```
 
@@ -280,20 +282,31 @@ Execute the task above:
         recovers (retry button works, form can be resubmitted, etc.).
      A test that would pass on an empty HTML page with the right element IDs is useless.
      Every assertion must prove the FEATURE WORKS, not that the ELEMENT EXISTS.
-7. Run ALL test suites — this is NOT optional, not conditional, not "if applicable":
+7. **Visual Design Verification** (only if design-to-code stack rule is active):
+   If the task involves UI implementation from a design reference:
+   a. Check if Claude Preview or Chrome MCP browser tools are available
+   b. If available: render the implemented component at each target breakpoint (mobile 375px, tablet 768px, desktop 1280px)
+   c. Screenshot each rendered breakpoint
+   d. Compare against the source design reference (from `.gsd-t/contracts/design-contract.md`)
+   e. Identify any deviations: spacing, color, typography, alignment, sizing
+   f. Fix deviations — every fix must trace to a design contract value (max 2 fix iterations)
+   g. Log verification results in the design contract's Verification Status table
+   h. If no browser tools available: log warning "Visual verification unavailable — manual review recommended" to `.gsd-t/qa-issues.md`
+   Skip this step entirely if no design-to-code stack rule was injected.
+8. Run ALL test suites — this is NOT optional, not conditional, not "if applicable":
    a. Detect configured test runners: check for vitest/jest config, playwright.config.*, cypress.config.*
    b. Run EVERY detected suite. Unit tests alone are NEVER sufficient when E2E exists.
    c. If `playwright.config.*` exists → run `npx playwright test` (full suite, not just affected specs)
    d. If E2E tests fail → fix (up to 2 attempts) before proceeding
    e. Report ALL suite results: "Unit: X/Y pass | E2E: X/Y pass" — never report just one
-8. Run Pre-Commit Gate checklist from CLAUDE.md — update all affected docs BEFORE committing
-9. Commit immediately: feat({domain-name}/task-{task-id}): {description}
-10. Update .gsd-t/progress.md — mark this task complete; prefix the Decision Log entry:
+9. Run Pre-Commit Gate checklist from CLAUDE.md — update all affected docs BEFORE committing
+10. Commit immediately: feat({domain-name}/task-{task-id}): {description}
+11. Update .gsd-t/progress.md — mark this task complete; prefix the Decision Log entry:
     - Completed successfully on first attempt → prefix `[success]`
     - Completed after a fix → prefix `[learning]`
     - Deferred to .gsd-t/deferred-items.md → prefix `[deferred]`
     - Failed after 3 attempts → prefix `[failure]`
-11. Spawn QA subagent (model: sonnet) after completing the task:
+12. Spawn QA subagent (model: sonnet) after completing the task:
     'Run ALL configured test suites — detect and run every one:
      a. Unit tests (vitest/jest/mocha): run the full suite, report pass/fail counts
      b. E2E tests: check for playwright.config.* or cypress.config.* — if found, run the FULL E2E suite
@@ -728,7 +741,7 @@ Report: 'Doc-ripple: {N} checked, {N} updated, {N} skipped'"
 
 ## Document Ripple
 
-Execute modifies source code, so the Pre-Commit Gate (referenced in Step 9) covers document updates. For clarity, the key documents affected by execution:
+Execute modifies source code, so the Pre-Commit Gate (referenced in Step 10) covers document updates. For clarity, the key documents affected by execution:
 
 ### Always update:
 1. **`.gsd-t/progress.md`** — Mark tasks complete, update domain status, log execution summary

package/commands/gsd-t-help.md

@@ -260,6 +260,7 @@ Use these when user asks for help on a specific command:
 - **Note (M22)**: Task-level fresh dispatch (one subagent per task, ~10-20% context each). Team mode uses worktree isolation (`isolation: "worktree"`) — zero file conflicts. Adaptive replanning between domain completions.
 - **Note (M26)**: Active rule injection — evaluates declarative rules from rules.jsonl before dispatching each domain's tasks. Fires matching rules as warnings in subagent prompts.
 - **Note (M29)**: Stack Rules Engine — auto-detects project tech stack from manifest files and injects mandatory best-practice rules into each task subagent prompt. Universal rules (`_security.md`, `_auth.md`) always apply; stack-specific rules layer on top. Violations are task failures (same weight as contract violations).
+- **Note (M33)**: Design-to-code — when a design contract, design tokens, or Figma config is detected, injects pixel-perfect implementation rules: Figma MCP auto-detection, design token extraction, stack capability evaluation (recommends alternatives if stack can't achieve the design), visual verification loop via Claude Preview or Chrome MCP. Adds Step 7 (Visual Design Verification) to task execution flow.
 
 ### test-sync
 - **Summary**: Keep tests aligned with code changes

package/commands/gsd-t-integrate.md

@@ -64,7 +64,7 @@ If rolled-back domains exist, report them to the user (or if Level 3: log to `.g
 
 **Stack Rules Detection (before spawning subagent):**
 Run via Bash to detect project stack and collect matching rules:
-`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; fi`
+`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && [ -f "$STACKS_DIR/design-to-code.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/design-to-code.md")"$'\n\n'; fi`
 
 If STACK_RULES is non-empty, append to the subagent prompt:
 ```

package/commands/gsd-t-quick.md

@@ -68,6 +68,8 @@ if [ -d "$STACKS_DIR" ]; then
   ([ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]) && _add playwright.md
   [ -f "go.mod" ] && _add go.md
   [ -f "Cargo.toml" ] && _add rust.md
+  # Design-to-code detection (design contract, design tokens, or Figma config)
+  ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && _add design-to-code.md
 fi
 ```
 

package/commands/gsd-t-wave.md

@@ -67,7 +67,7 @@ For each phase, spawn the agent like this:
 
 **Stack Rules Detection (before spawning subagent):**
 Run via Bash to detect project stack and collect matching rules:
-`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; fi`
+`GSD_T_DIR=$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t; STACKS_DIR="$GSD_T_DIR/templates/stacks"; STACK_RULES=""; if [ -d "$STACKS_DIR" ]; then for f in "$STACKS_DIR"/_*.md; do [ -f "$f" ] && STACK_RULES="${STACK_RULES}$(cat "$f")"$'\n\n'; done; if [ -f "package.json" ]; then grep -q '"react"' package.json 2>/dev/null && [ -f "$STACKS_DIR/react.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/react.md")"$'\n\n'; (grep -q '"typescript"' package.json 2>/dev/null || [ -f "tsconfig.json" ]) && [ -f "$STACKS_DIR/typescript.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/typescript.md")"$'\n\n'; grep -qE '"(express|fastify|hono|koa)"' package.json 2>/dev/null && [ -f "$STACKS_DIR/node-api.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/node-api.md")"$'\n\n'; fi; [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] && [ -f "$STACKS_DIR/python.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/python.md")"$'\n\n'; [ -f "go.mod" ] && [ -f "$STACKS_DIR/go.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/go.md")"$'\n\n'; [ -f "Cargo.toml" ] && [ -f "$STACKS_DIR/rust.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/rust.md")"$'\n\n'; ([ -f ".gsd-t/contracts/design-contract.md" ] || [ -f "design-tokens.json" ] || [ -d "design-tokens" ] || [ -f ".figmarc" ] || [ -f "figma.config.json" ]) && [ -f "$STACKS_DIR/design-to-code.md" ] && STACK_RULES="${STACK_RULES}$(cat "$STACKS_DIR/design-to-code.md")"$'\n\n'; fi`
 
 If STACK_RULES is non-empty, append to the subagent prompt:
 ```

package/docs/GSD-T-README.md

@@ -239,7 +239,7 @@ GSD-T auto-detects your project's tech stack and injects mandatory best-practice
 4. Project-level overrides in `.gsd-t/stacks/` replace global files of the same name.
 5. Rules are appended to the subagent prompt as a `## Stack Rules (MANDATORY)` section.
 
-### Stack Detection (27 files)
+### Stack Detection (28 files)
 
 | Project File | Detected Stack(s) |
 |---|---|
@@ -270,6 +270,7 @@ GSD-T auto-detects your project's tech stack and injects mandatory best-practice
 | `requirements.txt` with `celery`, `dramatiq`, `rq`, or `arq` | `queues.md` |
 | `requirements.txt` with `openai`, `anthropic`, `langchain` | `llm.md` |
 | `pubspec.yaml` | `flutter.md` |
+| `.gsd-t/contracts/design-contract.md`, `design-tokens.json`, `design-tokens/`, `.figmarc`, or `figma.config.json` | `design-to-code.md` |
 
 ### Commands That Inject Stack Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.53.11",
+  "version": "2.54.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 51 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/CLAUDE-global.md

@@ -617,6 +617,8 @@ GSD-T auto-detects project tech stack at subagent spawn time and injects mandato
 
 **Stack-specific rules**: Injected only when the matching stack is detected (e.g., `react.md` when `"react"` is in `package.json`).
 
+**Design-to-code**: Activated when `.gsd-t/contracts/design-contract.md`, `design-tokens.json`, `design-tokens/`, `.figmarc`, or `figma.config.json` exists. Enforces pixel-perfect frontend implementation from designs with: Figma MCP auto-detection, design token extraction protocol, stack capability evaluation (recommends alternatives if stack can't achieve the design), component decomposition, responsive breakpoint strategy, and a visual verification loop using Claude Preview or Chrome MCP.
+
 **Enforcement**: Stack rule violations have the same weight as contract violations — they are task failures, not warnings.
 
 **Extensible**: Drop a `.md` file into `templates/stacks/` in the GSD-T package to add rules for a new stack. If the directory is missing, detection skips silently.

package/templates/design-contract.md

@@ -0,0 +1,128 @@
+# Design Contract: {Component/Page Name}
+
+## Source
+
+| Property         | Value                                             |
+|------------------|---------------------------------------------------|
+| Source Type      | {Figma MCP / Image / Screenshot / Prototype URL}  |
+| Source Reference | {Figma URL, file path, image path, etc.}          |
+| Extracted Via    | {Figma MCP / Visual Analysis / Design Tokens File} |
+| Extracted Date   | {YYYY-MM-DD}                                      |
+| Precision Level  | {Exact (MCP) / High (exported tokens) / Estimated (visual analysis)} |
+| Breakpoints      | {mobile: 375px, tablet: 768px, desktop: 1280px}   |
+
+## Stack Evaluation
+
+| Requirement          | Stack Capability | Notes                                        |
+|----------------------|------------------|----------------------------------------------|
+| {CSS Grid layouts}   | {Supported}      | {e.g., framework supports CSS Grid natively} |
+| {Custom fonts}       | {Supported}      | {e.g., font loading via next/font}           |
+| {Complex animations} | {Partial}        | {e.g., may need Framer Motion addon}         |
+| {SVG manipulation}   | {Supported}      | {e.g., inline SVG supported}                 |
+
+## Color Palette
+
+| Token Name             | Value                    | Usage                        |
+|------------------------|--------------------------|------------------------------|
+| --color-primary        | {#1A73E8}                | {Primary buttons, links}     |
+| --color-primary-hover  | {#1557B0}                | {Primary button hover state} |
+| --color-text-primary   | {#202124}                | {Body text, headings}        |
+| --color-text-secondary | {#5F6368}                | {Captions, helper text}      |
+| --color-surface        | {#FFFFFF}                | {Card backgrounds}           |
+| --color-border         | {#DADCE0}                | {Dividers, input borders}    |
+
+## Typography
+
+| Token Name     | Family  | Weight | Size   | Line-Height | Letter-Spacing | Usage          |
+|----------------|---------|--------|--------|-------------|----------------|----------------|
+| --font-h1      | {Inter} | {700}  | {36px} | {1.2}       | {-0.02em}      | {Page title}   |
+| --font-h2      | {Inter} | {600}  | {24px} | {1.3}       | {-0.01em}      | {Section head}  |
+| --font-body    | {Inter} | {400}  | {16px} | {1.5}       | {normal}       | {Body text}    |
+| --font-caption | {Inter} | {400}  | {12px} | {1.4}       | {0.01em}       | {Helper text}  |
+
+## Spacing System
+
+| Token Name    | Value  | Usage                              |
+|---------------|--------|------------------------------------|
+| --spacing-xs  | {4px}  | {Inline element gaps}              |
+| --spacing-sm  | {8px}  | {Tight element spacing}            |
+| --spacing-md  | {16px} | {Standard padding, component gaps} |
+| --spacing-lg  | {24px} | {Section padding, card padding}    |
+| --spacing-xl  | {32px} | {Section margins}                  |
+| --spacing-2xl | {48px} | {Page-level spacing}               |
+
+## Borders & Shadows
+
+| Token Name      | Property      | Value                            |
+|-----------------|---------------|----------------------------------|
+| --radius-sm     | border-radius | {4px}                            |
+| --radius-md     | border-radius | {8px}                            |
+| --radius-lg     | border-radius | {16px}                           |
+| --radius-full   | border-radius | {9999px}                         |
+| --shadow-sm     | box-shadow    | {0 1px 2px rgba(0,0,0,0.05)}    |
+| --shadow-card   | box-shadow    | {0 2px 8px rgba(0,0,0,0.1)}     |
+| --shadow-modal  | box-shadow    | {0 8px 32px rgba(0,0,0,0.15)}   |
+| --border-default| border        | {1px solid var(--color-border)}  |
+
+## Component Tree
+
+```
+{Page/Component Name}
+  ├── {Section}
+  │     ├── {Component} (variant: {variants})
+  │     │     ├── {SubComponent}
+  │     │     └── {SubComponent}
+  │     └── {Component}
+  ├── {Section}
+  │     └── {Component} (x{count}, reusable)
+  │           ├── {Element}
+  │           └── {Element}
+  └── {Section}
+```
+
+## Layout Specifications
+
+### Mobile ({breakpoint}px)
+
+| Container      | Layout  | Columns/Direction | Gap    | Alignment | Notes          |
+|----------------|---------|-------------------|--------|-----------|----------------|
+| {.page}        | {grid}  | {1fr}             | {16px} | {stretch} | {full-width}   |
+| {.feature-grid}| {grid}  | {1fr}             | {16px} | {stretch} | {stacked}      |
+
+### Tablet ({breakpoint}px)
+
+| Container      | Layout  | Columns/Direction | Gap    | Alignment | Notes          |
+|----------------|---------|-------------------|--------|-----------|----------------|
+| {.page}        | {grid}  | {1fr}             | {24px} | {stretch} | {centered}     |
+| {.feature-grid}| {grid}  | {repeat(2, 1fr)}  | {24px} | {stretch} | {2-column}     |
+
+### Desktop ({breakpoint}px)
+
+| Container      | Layout  | Columns/Direction | Gap    | Alignment | Notes          |
+|----------------|---------|-------------------|--------|-----------|----------------|
+| {.page}        | {grid}  | {max-width 1280px}| {32px} | {center}  | {contained}    |
+| {.feature-grid}| {grid}  | {repeat(3, 1fr)}  | {32px} | {stretch} | {3-column}     |
+
+## Interactive States
+
+| Component    | Default         | Hover            | Focus              | Active           | Disabled         |
+|--------------|-----------------|------------------|--------------------|------------------|------------------|
+| {CTAButton}  | {bg: primary}   | {bg: primary-hover}| {outline: 2px primary}| {scale: 0.98} | {bg: border, 0.6}|
+| {NavLink}    | {color: text}   | {color: primary} | {underline}        | {font-weight: 600}| {color: muted}  |
+| {TextInput}  | {border: default}| {border: primary}| {ring: 2px primary}| {—}             | {bg: gray-50}    |
+
+## Verification Status
+
+| Check                              | Status      | Notes                             |
+|------------------------------------|-------------|-----------------------------------|
+| Token extraction complete          | {pending}   |                                   |
+| Component tree matches design      | {pending}   |                                   |
+| Mobile layout verified             | {pending}   |                                   |
+| Tablet layout verified             | {pending}   |                                   |
+| Desktop layout verified            | {pending}   |                                   |
+| Typography matches design          | {pending}   |                                   |
+| Colors match design                | {pending}   |                                   |
+| Spacing matches design             | {pending}   |                                   |
+| Interactive states implemented     | {pending}   |                                   |
+| Accessibility checks pass          | {pending}   |                                   |
+| Visual verification loop completed | {pending}   |                                   |

package/templates/stacks/design-to-code.md

@@ -0,0 +1,466 @@
+# Design-to-Code Standards
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+These rules apply when implementing a visual design as frontend code. The design already exists (Figma, screenshot, image, prototype) — your job is to replicate it faithfully in code with pixel-perfect accuracy.
+
+---
+
+## 1. Design Source Setup
+
+```
+MANDATORY:
+  ├── NEVER write CSS or layout code without a design reference
+  ├── Identify the source type: Figma file, image, screenshot, prototype URL
+  ├── If source is a Figma URL/file → check if Figma MCP is available
+  │     YES → Use Figma MCP to extract component data, styles, and layout
+  │     NO  → Inform user: "Figma MCP recommended for precise extraction"
+  │           Fallback: use image analysis (Claude's multimodal vision)
+  ├── If source is an image/screenshot → use visual analysis to extract values
+  ├── Store the source reference in the design contract
+  └── NEVER proceed to implementation without completing the extraction step
+```
+
+**BAD** — Glancing at a design and writing CSS from memory or approximation.
+
+**GOOD** — Systematically extracting every value from the design before writing a single line of CSS.
+
+---
+
+## 2. MCP & Tool Detection
+
+```
+MANDATORY:
+  ├── Before extraction, detect available tools:
+  │     Figma MCP → precise token extraction from Figma files
+  │     Claude Preview → render + screenshot for verification loop
+  │     Chrome MCP → alternative render + screenshot for verification
+  ├── If Figma MCP is available and source is Figma:
+  │     Use MCP to get exact colors, spacing, typography, component structure
+  │     MCP values are authoritative — override visual estimates
+  ├── If no Figma MCP but source is Figma:
+  │     Recommend setup: "For precise extraction, install the Figma MCP server.
+  │       Remote (recommended): https://mcp.figma.com/mcp
+  │       Or install the Figma Plugin for Claude Code which includes MCP settings."
+  │     Fallback: request a screenshot/export of each component at 1x and 2x
+  │     Use visual analysis — note reduced precision in the design contract
+  ├── Log which tools were used in the design contract Source section
+  └── Future MCPs (Sketch, Adobe XD, Penpot) follow the same pattern
+```
+
+**BAD** — Ignoring available MCPs and eyeballing a Figma screenshot.
+
+**GOOD** — Detecting Figma MCP, using it to extract exact `fill: #1A73E8`, `font-size: 14px`, `padding: 16px 24px`, then writing CSS from those exact values.
+
+---
+
+## 3. Stack Capability Evaluation
+
+```
+MANDATORY:
+  ├── BEFORE implementation, evaluate whether the project's chosen stack
+  │   can achieve pixel-perfect fidelity for this specific design:
+  │
+  ├── Evaluate these capabilities against design requirements:
+  │     CSS Grid / Flexbox support → complex layouts
+  │     Custom font loading → non-system typography
+  │     CSS custom properties → design token system
+  │     Animation / transition support → interactive states, micro-interactions
+  │     SVG support → icons, illustrations, complex shapes
+  │     Responsive units (clamp, container queries) → fluid scaling
+  │     Pseudo-elements (::before, ::after) → decorative elements
+  │     Backdrop filters / blend modes → glassmorphism, overlays
+  │     Gradient support → complex gradient fills
+  │     Component scoping → style isolation (CSS Modules, Shadow DOM, scoped styles)
+  │
+  ├── For each design requirement, assess:
+  │     Supported → stack handles this natively, proceed
+  │     Partial → needs an addon/library — name it, estimate effort
+  │     Unsupported → stack CANNOT achieve this — flag as a blocker
+  │
+  ├── If ANY requirement is Unsupported:
+  │     STOP and present to the user:
+  │       1. What the design requires
+  │       2. What the current stack cannot do
+  │       3. Recommended alternatives that CAN achieve it:
+  │            Example: "Design requires backdrop-filter blur — current stack
+  │            uses older browser targets that don't support it. Options:
+  │            (a) Update browserslist to modern-only
+  │            (b) Switch from CSS Modules to Tailwind (has backdrop-blur utility)
+  │            (c) Use a polyfill (reduced fidelity)"
+  │       4. Wait for user decision before proceeding
+  │
+  ├── If design requires a component library:
+  │     Evaluate: Can it be customized to match the design exactly?
+  │     Component libraries with opinionated styling (Material UI defaults,
+  │     Bootstrap themes) often FIGHT pixel-perfect custom designs
+  │     Recommend headless/unstyled alternatives when customization is needed:
+  │       Radix UI, Headless UI, React Aria, Shadcn/ui (Tailwind-based)
+  │
+  └── Document all findings in the design contract Stack Evaluation table
+```
+
+**BAD** — Starting implementation with Material UI and discovering halfway through that you can't match the design's custom border radius, shadow, and spacing because MUI's theme system fights you.
+
+**GOOD** — Evaluating upfront: "Design uses custom card shadows and non-standard spacing. MUI's elevation system won't match. Recommend: Tailwind + Radix for full styling control, or MUI with a fully custom theme override."
+
+---
+
+## 4. Design Token Extraction Protocol
+
+```
+MANDATORY:
+  ├── Extract EVERY value before writing any implementation code:
+  │     Colors    → exact hex/rgba/hsl for every fill, stroke, text color
+  │     Typography → family, weight, size, line-height, letter-spacing per text style
+  │     Spacing   → padding, margin, gap values for every element
+  │     Borders   → radius, width, style, color
+  │     Shadows   → x-offset, y-offset, blur, spread, color
+  │     Opacity   → any transparency values
+  │     Sizing    → exact width/height for fixed-size elements
+  │     Z-index   → layering order for overlapping elements
+  ├── Record each token with its usage context (which element, which state)
+  ├── Group tokens into a consistent naming system (--color-primary, --spacing-md, etc.)
+  ├── Cross-reference: if a value appears multiple times, it's a shared token
+  └── Write ALL tokens to .gsd-t/contracts/design-contract.md BEFORE coding
+```
+
+**BAD** — Writing `padding: 15px` because "it looks about right."
+
+**GOOD** — Extracting `padding: 16px` from the design tool, recording it as `--spacing-md: 1rem`, tracing it to "card container padding" in the design contract.
+
+---
+
+## 5. Design Contract Generation
+
+```
+MANDATORY:
+  ├── Write extracted tokens to .gsd-t/contracts/design-contract.md
+  │     Use the design-contract template from templates/design-contract.md
+  ├── Every CSS value in the implementation MUST trace to a contract entry
+  ├── If a value isn't in the contract, the extraction was incomplete — go back
+  ├── The contract is the source of truth — not the code, not your memory
+  └── Update the contract if the design changes during implementation
+```
+
+The design contract serves the same purpose as API contracts in GSD-T: it defines the exact interface between design and code. Any deviation is a violation.
+
+---
+
+## 6. Component Decomposition
+
+```
+MANDATORY:
+  ├── Before coding, analyze the design and produce a component tree:
+  │     Root container → sections → components → sub-components → atoms
+  ├── Identify repeated patterns → these become reusable components
+  ├── Identify variant states → these become component props
+  │     Example: Button has primary/secondary/ghost → variant prop
+  ├── Identify slot boundaries → where dynamic content gets injected
+  ├── Map the tree to your framework's component model (React, Vue, etc.)
+  ├── Name components semantically — match the design's layer names when clear
+  └── Document the tree in the design contract's Component Tree section
+```
+
+**BAD** — Writing one monolithic 400-line component that renders the entire page.
+
+**GOOD**
+```
+Page
+  ├── Header
+  │     ├── Logo
+  │     ├── NavLinks
+  │     └── UserMenu (variant: logged-in | logged-out)
+  ├── HeroSection
+  │     ├── Headline
+  │     ├── Subheadline
+  │     └── CTAButton (variant: primary)
+  ├── FeatureGrid
+  │     └── FeatureCard (x3, reusable)
+  │           ├── Icon
+  │           ├── Title
+  │           └── Description
+  └── Footer
+```
+
+---
+
+## 7. Layout Analysis
+
+```
+MANDATORY:
+  ├── Identify the layout system for every container:
+  │     Is it a grid? → CSS Grid with explicit columns/rows/gaps
+  │     Is it a row/column? → Flexbox with explicit direction/gap/alignment
+  │     Is it positioned? → Relative/absolute with exact offsets
+  ├── Measure exact gap values between elements — never approximate
+  ├── Identify alignment: start, center, end, stretch, space-between
+  ├── Determine sizing: fixed width/height vs flex-grow vs percentage vs min/max
+  ├── Note content overflow behavior: hidden, scroll, wrap, ellipsis
+  └── Document layout per breakpoint in the design contract
+```
+
+**BAD** — `display: flex; gap: 10px;` without measuring the actual gap.
+
+**GOOD** — Extracting gap as exactly `24px` from the design, then: `display: flex; gap: 1.5rem; /* 24px — design contract: section-gap */`
+
+---
+
+## 8. Responsive Breakpoint Strategy
+
+```
+MANDATORY:
+  ├── Analyze the design for breakpoint behavior BEFORE coding
+  │     What layout changes? (stack, reorder, hide, resize)
+  │     What typography changes? (font-size, line-height)
+  │     What spacing changes? (padding, margins, gaps)
+  ├── Define breakpoints explicitly — match the design's target viewports
+  │     Common: mobile 375px, tablet 768px, desktop 1280px, wide 1440px+
+  ├── Choose mobile-first or desktop-first per project convention
+  ├── Use fluid values where appropriate:
+  │     clamp(min, preferred, max) for font sizes
+  │     percentage or vw-based widths for flexible containers
+  │     container queries for component-level responsiveness
+  ├── NEVER assume "it'll work at intermediate sizes" — test every breakpoint
+  └── Document breakpoint behavior in the design contract
+```
+
+**BAD** — Building desktop only, then adding `@media (max-width: 768px)` as an afterthought.
+
+**GOOD** — Analyzing all breakpoints upfront, building mobile-first, progressively enhancing:
+```css
+/* Mobile (default) */
+.feature-grid { display: grid; grid-template-columns: 1fr; gap: 1rem; }
+/* Tablet */
+@media (min-width: 768px) { .feature-grid { grid-template-columns: repeat(2, 1fr); gap: 1.5rem; } }
+/* Desktop */
+@media (min-width: 1280px) { .feature-grid { grid-template-columns: repeat(3, 1fr); gap: 2rem; } }
+```
+
+---
+
+## 9. Semantic HTML Structure
+
+```
+MANDATORY:
+  ├── Use semantic elements: nav, main, section, article, aside, header, footer
+  ├── Heading hierarchy: one h1 per page, h2 → h3 → h4 in order, no skips
+  ├── Interactive elements: button for actions, a for navigation — NEVER div with onClick
+  ├── Form elements: label + input pairs, fieldset + legend for groups
+  ├── ARIA landmarks: role attributes only when semantic HTML doesn't suffice
+  ├── Alt text: descriptive for content images, empty (alt="") for decorative
+  ├── Tab order: logical, follows visual layout, no positive tabindex values
+  └── Focus indicators: visible on every interactive element
+```
+
+**BAD** — `<div class="button" onclick="...">Click me</div>`
+
+**GOOD** — `<button type="button" class="cta-button">Click me</button>`
+
+---
+
+## 10. CSS Precision Rules
+
+```
+MANDATORY:
+  ├── EVERY value must trace to the design contract — no "looks about right"
+  ├── Use CSS custom properties for design tokens:
+  │     :root { --color-primary: #1A73E8; --spacing-md: 1rem; }
+  ├── NO magic numbers without a comment tracing to the design spec
+  │     BAD:  padding: 13px;
+  │     GOOD: padding: var(--spacing-card); /* 16px — design contract: card-padding */
+  ├── Consistent units: rem for spacing/typography, px for borders/shadows
+  ├── Box model: use box-sizing: border-box universally
+  ├── When the project uses Tailwind: map design tokens to Tailwind config
+  │     extend theme with exact values from the design contract
+  └── Zero tolerance for deviation — if the design says 16px, the code says 16px
+```
+
+**BAD** — Freestyle CSS with values pulled from thin air.
+
+**GOOD** — Every value traceable:
+```css
+.card {
+  padding: var(--spacing-lg);         /* 24px — design contract */
+  border-radius: var(--radius-md);    /* 8px — design contract */
+  box-shadow: var(--shadow-card);     /* 0 2px 8px rgba(0,0,0,0.1) — design contract */
+  background: var(--color-surface);   /* #FFFFFF — design contract */
+}
+```
+
+---
+
+## 11. Typography Rendering
+
+```
+MANDATORY:
+  ├── Font loading: preload primary fonts, use font-display: swap
+  ├── Exact values from design: family, weight, size, line-height, letter-spacing
+  │     NEVER approximate: "looks like 14px" → measure it, confirm it
+  ├── Line-height: use unitless values (1.5, not 24px) for scalability
+  │     Exception: fixed-height single-line elements where px matches design
+  ├── Letter-spacing: convert from design tool units if needed
+  │     Figma uses percentage or px; CSS uses em or px
+  │     0.5% in Figma ≈ 0.005em in CSS
+  ├── Text overflow: match design behavior (ellipsis, wrap, clamp lines)
+  ├── Font weight mapping: design tools may use names — map to numeric values
+  │     Thin=100, Light=300, Regular=400, Medium=500, SemiBold=600, Bold=700
+  └── Responsive typography: use clamp() or breakpoint-specific sizes per design
+```
+
+**BAD** — `font-size: 16px; line-height: 1.5;` without checking the actual design values.
+
+**GOOD** — Exact extraction:
+```css
+.headline {
+  font-family: var(--font-heading);       /* Inter — design contract */
+  font-weight: 600;                        /* SemiBold — design contract */
+  font-size: clamp(1.5rem, 2vw, 2.25rem); /* 24-36px responsive — design contract */
+  line-height: 1.3;                        /* 31.2px at 24px — design contract */
+  letter-spacing: -0.01em;                 /* -0.16px at 16px — design contract */
+}
+```
+
+---
+
+## 12. Color Accuracy
+
+```
+MANDATORY:
+  ├── Extract exact color values — never approximate
+  │     #1A73E8 is NOT #1A74E9 — match exactly
+  ├── Use the format from the design tool: hex for solid, rgba for transparent
+  ├── Define as CSS custom properties — NEVER hardcode throughout stylesheets
+  ├── Gradients: extract exact stops (color + position %)
+  ├── Opacity: apply via rgba/hsla or opacity property — match the design's approach
+  ├── Dark mode (if applicable):
+  │     Map each light token to its dark equivalent
+  │     Use prefers-color-scheme or class-based toggle per project convention
+  ├── Semantic naming: --color-primary, --color-text-secondary, --color-surface
+  │     NOT --blue-500 — use design intent, not visual description
+  └── Background images/patterns: export at correct resolution, use srcset for retina
+```
+
+**BAD** — Using `blue` or `#0000ff` when the design uses `#1A73E8`.
+
+**GOOD** — Exact match with semantic naming:
+```css
+:root {
+  --color-primary: #1A73E8;
+  --color-primary-hover: #1557B0;
+  --color-text-primary: #202124;
+  --color-text-secondary: #5F6368;
+  --color-surface: #FFFFFF;
+  --color-border: #DADCE0;
+}
+```
+
+---
+
+## 13. Interactive States
+
+```
+MANDATORY:
+  ├── Every interactive element MUST have ALL states defined:
+  │     default, hover, focus-visible, active, disabled
+  ├── Extract state styles from the design — designers often spec these
+  │     If not specified: derive logically (hover = slightly darker/lighter)
+  │     Document derived states in the design contract with "derived" note
+  ├── Transitions: specify duration and easing — don't rely on browser defaults
+  │     Standard: transition: all 150ms ease-in-out (or per design spec)
+  ├── Focus indicators: visible, high-contrast, not just outline:none
+  ├── Touch targets: minimum 44x44px on mobile — pad with transparent area if needed
+  ├── Cursor states: pointer for clickable, not-allowed for disabled, text for inputs
+  └── Loading states: skeleton/spinner/disabled during async operations
+```
+
+**BAD** — Styling only the default state, leaving hover/focus as browser defaults.
+
+**GOOD**
+```css
+.cta-button {
+  background: var(--color-primary);
+  color: white;
+  padding: 12px 24px;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: background 150ms ease-in-out, transform 100ms ease-in-out;
+}
+.cta-button:hover { background: var(--color-primary-hover); }
+.cta-button:focus-visible { outline: 2px solid var(--color-primary); outline-offset: 2px; }
+.cta-button:active { transform: scale(0.98); }
+.cta-button:disabled { background: var(--color-border); cursor: not-allowed; opacity: 0.6; }
+```
+
+---
+
+## 14. Visual Verification Loop
+
+```
+MANDATORY:
+  ├── After implementing any design component, run a visual verification:
+  │   1. Render the component (Claude Preview, Chrome MCP, or dev server)
+  │   2. Screenshot the rendered output
+  │   3. Compare side-by-side with the source design
+  │   4. Identify EVERY deviation (spacing, color, font, alignment, sizing)
+  │   5. Fix each deviation — trace fix to design contract values
+  │   6. Re-render and re-compare
+  ├── Maximum 3 verification iterations per component
+  │     If still deviating after 3 → log specific deltas to .gsd-t/qa-issues.md
+  ├── Tool priority for rendering:
+  │     1. Claude Preview (if available) — fastest loop
+  │     2. Chrome MCP (if available) — full browser rendering
+  │     3. Dev server + manual screenshot — last resort
+  ├── Check at EVERY breakpoint — not just desktop
+  │     Mobile (375px), Tablet (768px), Desktop (1280px) minimum
+  ├── Verification is NOT optional — skipping it is a task failure
+  └── Log verification results in the design contract Verification Status table
+```
+
+**BAD** — Writing CSS, committing, moving on without ever seeing the rendered result.
+
+**GOOD** — Render → Screenshot → Compare → Fix spacing from 14px to 16px → Re-render → Confirm match → Log "verified at 3 breakpoints" in design contract.
+
+---
+
+## 15. Anti-Patterns
+
+```
+NEVER DO THESE:
+  ├── Eyeballing values — "looks like about 12px padding" (EXTRACT the exact value)
+  ├── Hardcoding without traceability — magic numbers with no design reference
+  ├── "Close enough" mentality — 14px when the design says 16px is a FAILURE
+  ├── Desktop-only implementation — ignoring responsive breakpoints
+  ├── State-less components — only styling default, ignoring hover/focus/disabled
+  ├── Layout-only testing — checking element existence without visual verification
+  ├── Skipping the extraction step — jumping straight to code
+  ├── Approximating colors — using a "close" shade instead of the exact value
+  ├── Ignoring typography details — wrong font weight, missing letter-spacing
+  ├── Fixed pixel values everywhere — not using rem/em for scalable sizing
+  ├── Mixing styling approaches — Tailwind + inline styles + CSS modules in one project
+  └── Skipping the verification loop — submitting unverified visual output
+```
+
+---
+
+## 16. Design-to-Code Verification Checklist
+
+Before marking any design implementation task as complete:
+
+- [ ] Design source identified and documented in design contract
+- [ ] Stack capability evaluated — all design requirements achievable (or alternatives approved)
+- [ ] All design tokens extracted (colors, typography, spacing, borders, shadows)
+- [ ] Tokens written to `.gsd-t/contracts/design-contract.md`
+- [ ] Component tree documented and matches design hierarchy
+- [ ] Every CSS value traces to a design contract entry
+- [ ] CSS custom properties (or Tailwind config) define all design tokens
+- [ ] Semantic HTML used (no div-soup, proper heading hierarchy)
+- [ ] All interactive states implemented (hover, focus, active, disabled)
+- [ ] Responsive behavior implemented for all target breakpoints
+- [ ] Visual verification loop completed at mobile, tablet, and desktop widths
+- [ ] Typography exact: family, weight, size, line-height, letter-spacing all match
+- [ ] Colors exact: every fill, stroke, text color matches design values
+- [ ] Spacing exact: every padding, margin, gap matches design values
+- [ ] Accessibility: focus indicators, alt text, ARIA where needed, 44px touch targets
+- [ ] No magic numbers — every value is documented or uses a design token
+- [ ] Verification results logged in design contract Verification Status table