@tekyzinc/gsd-t 2.69.12 → 2.70.10

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.70.10] - 2026-04-06
+
+### Added (design pipeline — 2 new capabilities)
+- **Design System Detection** — all design pipeline commands now ask for a design system / component library URL upfront before extraction or implementation. If provided, the agent fetches the library docs, catalogs available components, and maps design elements to library primitives (use library components instead of building custom). Added to: `gsd-t-design-decompose` (Step 0.4), `gsd-t-design-audit` (Step 0), `design-to-code.md` (new Section 1 — all subsequent sections renumbered). Verification checklist updated with 2 new items.
+- **SVG Structural Overlay Comparison** — new mandatory verification layer that exports the Figma frame as SVG, parses element positions/dimensions/colors from the SVG DOM, maps to built DOM bounding boxes, and compares geometry mechanically (≤2px = MATCH, 3-5px = REVIEW, >5px = DEVIATION). Catches aggregate spacing drift, alignment issues, and proportion errors that pass property-level checks but are visually wrong. Added to: `gsd-t-execute` (Step 5 inside Design Verification Agent), `gsd-t-quick` (step 7 inside Design Verification Agent), `gsd-t-design-audit` (Step 3.5), `design-to-code.md` (Target 3 + workflow step 7 + checklist item).
+
+### Why
+- **Design system**: Building custom cards, tables, tabs, and buttons from scratch when a library like shadcn-vue already provides them wastes effort and produces inferior results (missing accessibility, focus states, interactive states). Asking upfront eliminates redundant work.
+- **SVG overlay**: The property-level comparison table catches wrong values but misses aggregate visual drift — spacing rhythm, alignment, proportions that are individually correct but collectively off. SVG structural diff is mechanical and non-interpretive: geometry vs geometry, no agent reasoning required.
+
+## [2.69.13] - 2026-04-05
+
+### Fixed (design-to-code pipeline — extraction + verification)
+- **Mandate `get_design_context` everywhere in the pipeline** — initial build (design-to-code.md sections 1-2), verification agent (gsd-t-execute.md Step 5.25), quick verification (gsd-t-quick.md Step 5.25), and Red Team design fidelity check all now explicitly require `get_design_context` per widget node for Figma data extraction. `get_screenshot` is prohibited for extraction and restricted to visual-only comparison of built output. This closes the gap where agents chose `get_screenshot` (pixels) over `get_design_context` (structured code/tokens) at every stage.
+
 ## [2.69.12] - 2026-04-05
 
 ### Fixed (gsd-t-design-audit, gsd-t-design-decompose)

package/commands/gsd-t-design-audit.md

@@ -17,6 +17,12 @@ Extract from `$ARGUMENTS`:
 If Figma source is missing → ask user: "Provide the Figma file key or URL"
 If built app target is missing → check if a dev server is running. If not → ask user: "Provide the route or URL of the built page to audit"
 
+**Design system / component library?**
+- Ask user: "Is a design system or component library being used (e.g., shadcn-vue, Vuetify, Radix, MUI)? If so, provide the URL."
+- If yes → fetch the docs, note which components the library provides and their default styling (padding, radius, shadows, colors)
+- Factor into Step 3 comparisons: deviations that match library defaults (not Figma) may indicate "used library default instead of design value" — flag as a distinct deviation category
+- If no → proceed as normal
+
 ## Step 1: Map the Figma Design — Node-Level Decomposition
 
 ### 1a. Get the page tree
@@ -142,9 +148,58 @@ For each widget, produce a comparison table with **minimum 10 rows per widget**
 | **MEDIUM** | Wrong alignment, color, or order that looks incorrect but doesn't change meaning | Legend left instead of center; segment order reversed; wrong shade |
 | **LOW** | Minor sizing or spacing that's barely noticeable | 2px padding difference; slight font-size mismatch |
 
+## Step 3.5: SVG Structural Overlay Comparison (MANDATORY)
+
+After the per-widget property comparison, run a mechanical SVG-based diff to catch aggregate visual drift that individual property checks miss.
+
+1. **Export the Figma frame as SVG**:
+   - Use the Figma REST API or MCP to export the page/frame as SVG
+   - If export is unavailable, ask the user to export and provide the SVG path
+   - Store the SVG at `.gsd-t/design-verify/{page-name}-figma.svg`
+
+2. **Parse the SVG DOM**: extract every `<rect>`, `<text>`, `<circle>`, `<path>`, `<g>` with their positions (x, y), dimensions (width, height), fills, strokes, and text content
+
+3. **Screenshot the built page** at the same viewport width via Playwright
+
+4. **Map SVG elements → built DOM elements** by:
+   - Text content matching (highest confidence)
+   - Position proximity (x,y within 10px tolerance)
+   - Dimensional similarity (width/height within 10% tolerance)
+
+5. **Compare each mapped pair**:
+
+| Check | SVG Value | Built Value | Threshold |
+|-------|-----------|-------------|-----------|
+| Position (x,y) | SVG coordinates | DOM bounding box | ≤2px = MATCH, 3-5px = REVIEW, >5px = DEVIATION |
+| Dimensions (w,h) | SVG width/height | DOM width/height | ≤2px = MATCH, 3-5px = REVIEW, >5px = DEVIATION |
+| Colors | SVG fill/stroke hex | Computed CSS color | Exact hex = MATCH |
+| Text content | SVG `<text>` | DOM textContent | Exact = MATCH |
+
+6. **Produce SVG structural diff table**:
+
+```markdown
+### SVG Structural Diff
+
+| # | SVG Element | SVG Position | Built Position | Δ px | Verdict |
+|---|-------------|-------------|----------------|------|---------|
+| 1 | stat-card-1 rect | (24, 120) 320×200 | (24, 118) 320×204 | 2/4 | ⚠ REVIEW |
+| 2 | chart-title text | (40, 140) | (40, 140) | 0 | ✅ MATCH |
+```
+
+7. **Unmapped elements**:
+   - SVG elements with no DOM match → flag as "MISSING IN BUILD"
+   - DOM elements with no SVG match → flag as "EXTRA — not in design"
+
+8. **Visual overlay** (optional but recommended):
+   - Render SVG in browser at target viewport size
+   - Overlay on built page screenshot with 50% opacity or difference blend mode
+   - Save to `.gsd-t/design-verify/{page-name}-overlay.png`
+
+This step catches spacing rhythm, alignment drift, and proportion issues that pass the per-widget property check but are visually wrong in aggregate.
+
 ## Step 4: Summary Report
 
-After all widgets are audited, produce a summary:
+After all widgets are audited (property tables + SVG structural diff), produce a summary:
 
 ```markdown
 ## Design Audit Summary

package/commands/gsd-t-design-decompose.md

@@ -32,7 +32,14 @@ Run these checks, log results to user inline:
 3. **Design source provided?**
    - Required: Figma URL, image path, or prototype URL in `$ARGUMENTS`
    - If missing → ask user: "Provide the design source (Figma URL, image path, or prototype URL)"
-4. **Load the chart taxonomy (MANDATORY)**
+4. **Design system / component library?**
+   - Ask user: "Is a design system or component library being used (e.g., shadcn-vue, Vuetify, Radix, MUI, Ant Design)? If so, provide the URL."
+   - If yes → fetch the docs landing page, catalog available components (cards, tables, tabs, charts, buttons, etc.)
+   - Record in working memory: which design elements can be mapped to library primitives vs. built custom
+   - Factor into Step 2 classification: if the library provides a component (e.g., `Card`, `Table`, `Tabs`), the element contract should reference it as the implementation target
+   - Factor into Step 3 widget composition: library layout primitives (e.g., `Grid`, `Flex`, `Sheet`) inform widget structure
+   - If no → proceed as normal (all components built custom)
+5. **Load the chart taxonomy (MANDATORY)**
    - READ `templates/design-chart-taxonomy.md` from the GSD-T package (or `~/.claude/` if installed)
    - This is the **CLOSED SET** of valid element names. You MUST pick from this list. Inventing new element names is FORBIDDEN without user approval to extend the taxonomy.
    - Keep the taxonomy in working memory while classifying — every element you identify MUST be matched against it

package/commands/gsd-t-execute.md

@@ -662,10 +662,16 @@ wrong.
 ## Step 1: Get the Design Reference
 
 Read .gsd-t/contracts/design-contract.md for the source reference.
-- If Figma MCP available → call get_screenshot with nodeId + fileKey from the contract
+- If Figma MCP available → call `get_metadata` to enumerate widget/component nodes,
+  then call `get_design_context` per widget node to extract structured data
+  (code, component properties, design tokens, text content, layout values).
+  ⚠ Do NOT use `get_screenshot` for Figma data extraction — it returns pixels
+    you cannot extract exact values from. `get_design_context` returns structured
+    code and tokens. Use `get_design_context` for extraction, `get_screenshot`
+    ONLY if you need a visual reference image for side-by-side comparison.
 - If design image files → locate them from the contract's Source Reference field
 - If no MCP and no images → log CRITICAL blocker to .gsd-t/qa-issues.md and STOP
-You MUST have a reference image before proceeding.
+You MUST have structured design data (or reference images) before proceeding.
 
 ## Step 2: Build the Element Inventory
 
@@ -697,22 +703,27 @@ VIEW 1 — BUILT FRONTEND:
   Navigate to the exact route/component being verified.
   You MUST see real rendered output — not just read the code.
 
-VIEW 2 — ORIGINAL DESIGN REFERENCE:
-  If Figma URL available → open the Figma page in a browser tab/window.
-    Use the Figma URL from the design contract Source Reference field.
-    Navigate to the specific frame/component being compared.
+VIEW 2 — ORIGINAL DESIGN REFERENCE (structured data, not just images):
+  If Figma MCP available → you already have `get_design_context` data from Step 1.
+    Use the STRUCTURED DATA (component properties, text content, layout values,
+    colors, spacing) as the authoritative design reference — not screenshots.
+    Optionally open the Figma URL in a browser for visual context, but extract
+    values from `get_design_context` responses, not from visual inspection.
   If design image file → open the image in a browser tab/window.
     Use: file://{absolute-path-to-image} or render in an HTML page.
-  If Figma MCP screenshot was captured → open that screenshot image.
+  If no Figma MCP → use reference images from the design contract.
 
 COMPARISON APPROACH:
-  With both views open, walk through each component/section:
-    - Position views side-by-side (or switch between tabs)
-    - Compare each element visually at the same zoom level
-    - Screenshot BOTH views at matching viewport sizes
+  For each widget/component, compare the BUILT DOM/styles against the
+  STRUCTURED values from `get_design_context`:
+    - Chart type: does the built component match the Figma node's structure?
+    - Text content: do titles, labels, legends match `get_design_context` text?
+    - Layout: do spacing, alignment, sizing match the structured properties?
+    - Colors: do fills, strokes, text colors match the exact hex values?
   Capture implementation screenshots at each target breakpoint:
     Mobile (375px), Tablet (768px), Desktop (1280px) minimum.
-  Each breakpoint is a separate screenshot pair (design + implementation).
+  Compare screenshots against Figma for overall visual impression,
+  but use `get_design_context` data for the authoritative value comparison.
 
 If Claude Preview, Chrome MCP, and Playwright are ALL unavailable:
   This is a CRITICAL blocker. Log to .gsd-t/qa-issues.md:
@@ -730,25 +741,64 @@ the inventory gets its own row. No summarizing, no grouping, no prose.
 | 2 | Summary | Chart colors | #4285F4, #34A853, #FBBC04 | #4285F4, #34A853, #FBBC04 | ✅ MATCH |
 
 Rules:
-- 'Design' column: SPECIFIC values (chart type name, hex color, px size, font weight)
-- 'Implementation' column: SPECIFIC observed values from the SCREENSHOT — not code assumptions
+- 'Design' column: SPECIFIC values from `get_design_context` structured data
+  (chart type name, hex color, px size, font weight, text content)
+- 'Implementation' column: SPECIFIC observed values from the built page DOM/styles
 - Verdict: only ✅ MATCH or ❌ DEVIATION — never 'appears to match' or 'need to verify'
 - NEVER write 'Appears to match' or 'Looks correct' — measure and verify
 - If the table has fewer than 30 rows for a full-page comparison, you skipped elements
 
-## Step 5: Report Deviations
+## Step 5: SVG Structural Overlay Comparison (MANDATORY)
+
+After the property-level comparison, run a mechanical SVG-based diff to catch
+aggregate visual drift that individual property checks miss.
+
+1. Export the Figma frame as SVG:
+   - Use the Figma REST API or MCP to export the page/frame as SVG
+   - If export is unavailable, ask the user to export and provide the SVG path
+   - Store the SVG at .gsd-t/design-verify/{page-name}-figma.svg
+2. Parse the SVG DOM: extract every <rect>, <text>, <circle>, <path>, <g>
+   with their positions (x, y), dimensions (width, height), fills, strokes,
+   and text content
+3. Screenshot the built page at the same viewport width via Playwright
+4. Inspect the built page DOM: extract element bounding boxes, computed
+   styles (colors, dimensions), and text content
+5. Map SVG elements → built DOM elements by:
+   - Text content matching (highest confidence)
+   - Position proximity (x,y within 10px tolerance)
+   - Dimensional similarity (width/height within 10% tolerance)
+6. For each mapped pair, compare:
+   - Position: SVG (x,y) vs DOM bounding box (x,y). Within 2px = MATCH
+   - Dimensions: SVG (w,h) vs DOM (w,h). Within 2px = MATCH
+   - Colors: SVG fill/stroke vs computed CSS color. Exact hex = MATCH
+   - Text: SVG <text> content vs DOM textContent. Exact = MATCH
+7. Produce an SVG structural diff table:
+   | # | SVG Element | SVG Position | Built Position | Δ px | Verdict |
+   Threshold: ≤2px = ✅ MATCH, 3-5px = ⚠ REVIEW, >5px = ❌ DEVIATION
+8. Unmapped SVG elements (no DOM match) → flag as MISSING IN BUILD
+   Unmapped DOM elements (no SVG match) → flag as EXTRA IN BUILD
+9. Generate a visual overlay image (optional but recommended):
+   - Render SVG in browser at target viewport size
+   - Overlay on built page screenshot with 50% opacity or difference blend
+   - Save to .gsd-t/design-verify/{page-name}-overlay.png
+
+This step catches spacing rhythm, alignment drift, and proportion issues
+that pass the property-level check but are visually wrong in aggregate.
+
+## Step 6: Report Deviations
 
 For each ❌ DEVIATION, write a specific finding:
   'Design: {exact value}. Implementation: {exact value}. File: {path}:{line}'
 
-Write the FULL comparison table to .gsd-t/contracts/design-contract.md
-under a '## Verification Status' section.
+Write the FULL comparison table (property-level from Step 4 + SVG structural
+from Step 5) to .gsd-t/contracts/design-contract.md under a
+'## Verification Status' section.
 
 Any ❌ DEVIATION → also append to .gsd-t/qa-issues.md with severity HIGH
 and tag [VISUAL]:
 | {date} | gsd-t-execute | Step 5.25 | opus | {duration} | HIGH | [VISUAL] {description} |
 
-## Step 6: Verdict
+## Step 7: Verdict
 
 Count results: '{MATCH_COUNT}/{TOTAL} elements match at {breakpoints} breakpoints'
 
@@ -837,7 +887,7 @@ Rules:
    FAIL-BY-DEFAULT: assume NOTHING matches. Prove each element individually.
    a. Open every implemented screen in a real browser. Screenshot at mobile
       (375px), tablet (768px), desktop (1280px). Get Figma reference via
-      Figma MCP get_screenshot (or design contract images).
+      `get_design_context` per widget node (structured data — NOT `get_screenshot`).
    b. Build an element inventory: enumerate every distinct visual element
       in the design top-to-bottom. Every chart, label, icon, heading, card,
       spacing boundary, and color. Data visualizations expand: chart type,

package/commands/gsd-t-quick.md

@@ -266,17 +266,32 @@ rendered UI. If any is missing → CRITICAL DEVIATION (wrong data). Wrong data
 cannot be redeemed by visual polish.
 
 1. Read .gsd-t/contracts/design-contract.md (flat) OR .gsd-t/contracts/design/ (hierarchical) for design source reference + Test Fixtures
-2. Get design reference (Figma MCP screenshot, or design images from contract)
+2. Get Figma structured data via `get_metadata` (enumerate nodes) then `get_design_context`
+   per widget node. ⚠ Do NOT use `get_screenshot` for Figma extraction — it returns pixels,
+   not properties. `get_design_context` returns structured code and tokens.
+   If no Figma MCP → use design images from contract as fallback.
 3. Start dev server, open the built frontend in browser (Claude Preview/Chrome MCP/Playwright)
-4. Open the original design reference in a second browser view
+4. Compare built page values against `get_design_context` structured data
 5. Build element inventory (30+ elements for a full page): every chart, label,
    icon, heading, card, button, spacing, color — each a separate row
 6. Produce structured comparison table:
    | # | Section | Element | Design (specific) | Implementation (specific) | Verdict |
    Only valid verdicts: ✅ MATCH or ❌ DEVIATION (never 'appears to match')
-7. Write results to .gsd-t/contracts/design-contract.md under '## Verification Status'
-8. Any ❌ → append to .gsd-t/qa-issues.md with [VISUAL] tag
-9. Report: DESIGN VERIFIED | DESIGN DEVIATIONS FOUND ({count})"
+7. SVG Structural Overlay Comparison:
+   a. Export Figma frame as SVG (or ask user for SVG path if export unavailable)
+   b. Parse SVG DOM: extract positions, dimensions, fills, text for every element
+   c. Screenshot built page at same viewport width via Playwright
+   d. Map SVG elements → built DOM elements by text content + position proximity
+   e. Compare: position (≤2px=MATCH, 3-5px=REVIEW, >5px=DEVIATION),
+      dimensions, colors (exact hex), text (exact match)
+   f. Produce SVG structural diff table:
+      | # | SVG Element | SVG Position | Built Position | Δ px | Verdict |
+   g. Flag unmapped SVG elements as MISSING, unmapped DOM elements as EXTRA
+   This catches aggregate visual drift that property-level checks miss.
+8. Write results (property table + SVG diff) to .gsd-t/contracts/design-contract.md
+   under '## Verification Status'
+9. Any ❌ → append to .gsd-t/qa-issues.md with [VISUAL] tag
+10. Report: DESIGN VERIFIED | DESIGN DEVIATIONS FOUND ({count})"
 ```
 
 After subagent returns — run observability Bash and append to token-log.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.69.12",
+  "version": "2.70.10",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 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/stacks/design-to-code.md

@@ -35,14 +35,56 @@ A widget that uses `chart-donut` cannot change `chart-donut`'s bar-gap, colors,
 
 ---
 
-## 1. Design Source Setup
+## 1. Design System Detection
+
+```
+MANDATORY:
+  ├── BEFORE any extraction or implementation, check for a design system:
+  │     Ask user: "Is a design system or component library being used
+  │       (e.g., shadcn-vue, Vuetify, Radix, MUI, Ant Design, Chakra)?
+  │       If so, provide the URL."
+  ├── If YES:
+  │     Fetch the library's docs landing page
+  │     Catalog available components (cards, tables, tabs, charts, buttons,
+  │       inputs, dialogs, dropdowns, etc.)
+  │     Identify the theming system (CSS variables, Tailwind config, theme object)
+  │     Determine customization model:
+  │       Copy-paste (shadcn) → full control, edit component source directly
+  │       Config-based (MUI theme) → customize via theme overrides
+  │       Utility-first (Tailwind + headless) → style via utility classes
+  │     Map design elements to library primitives — use library components
+  │       instead of building custom whenever a match exists
+  │     Record in the design contract: library name, URL, version,
+  │       components used, theming approach
+  ├── If NO:
+  │     Proceed with fully custom implementation
+  │     Note in design contract: "No design system — all components custom"
+  └── WHY: Design system components provide battle-tested accessibility,
+        interactive states, and responsive behavior out of the box.
+        Building custom when a library component exists wastes effort
+        and produces inferior results (missing focus states, ARIA, etc.)
+```
+
+**BAD** — Building a custom card component, dropdown, and table from scratch when shadcn-vue already provides them with full accessibility and Tailwind theming.
+
+**GOOD** — Detecting shadcn-vue, mapping 60% of the design's UI elements to library components, customizing via Tailwind theme tokens, and only building custom for elements the library doesn't cover (specialized charts, domain-specific widgets).
+
+---
+
+## 2. 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
+  │     YES → Use Figma MCP `get_design_context` per widget/component node
+  │           `get_design_context` returns structured code, component properties,
+  │           and design tokens — this is what you extract values from.
+  │           ⚠ NEVER use `get_screenshot` for extraction — it returns pixels,
+  │             not properties. You cannot reliably extract exact spacing, colors,
+  │             or text from an image. `get_screenshot` is only for verification
+  │             (comparing built output to design visually).
   │     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
@@ -56,17 +98,23 @@ MANDATORY:
 
 ---
 
-## 2. MCP & Tool Detection
+## 3. MCP & Tool Detection
 
 ```
 MANDATORY:
   ├── Before extraction, detect available tools:
   │     Figma MCP → precise token extraction from Figma files
+  │       `get_design_context` → structured code + tokens (USE THIS for extraction)
+  │       `get_metadata` → node tree enumeration (USE THIS to find widget nodes)
+  │       `get_screenshot` → visual image only (NEVER use for extraction —
+  │         only for post-build verification comparisons)
   │     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
+  │     Call `get_metadata` to enumerate the page's widget/component nodes
+  │     Call `get_design_context` per widget node to extract structured data
+  │     Extract exact colors, spacing, typography, component structure from the response
+  │     MCP `get_design_context` 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
@@ -83,7 +131,7 @@ MANDATORY:
 
 ---
 
-## 3. Stack Capability Evaluation
+## 4. Stack Capability Evaluation
 
 ```
 MANDATORY:
@@ -135,7 +183,7 @@ MANDATORY:
 
 ---
 
-## 4. Design Token Extraction Protocol
+## 5. Design Token Extraction Protocol
 
 ```
 MANDATORY:
@@ -160,7 +208,7 @@ MANDATORY:
 
 ---
 
-## 5. Design Contract Generation
+## 6. Design Contract Generation
 
 ```
 MANDATORY:
@@ -176,7 +224,7 @@ The design contract serves the same purpose as API contracts in GSD-T: it define
 
 ---
 
-## 6. Component Decomposition
+## 7. Component Decomposition
 
 ```
 MANDATORY:
@@ -214,7 +262,7 @@ Page
 
 ---
 
-## 7. Layout Analysis
+## 8. Layout Analysis
 
 ```
 MANDATORY:
@@ -235,7 +283,7 @@ MANDATORY:
 
 ---
 
-## 8. Responsive Breakpoint Strategy
+## 9. Responsive Breakpoint Strategy
 
 ```
 MANDATORY:
@@ -268,7 +316,7 @@ MANDATORY:
 
 ---
 
-## 9. Semantic HTML Structure
+## 10. Semantic HTML Structure
 
 ```
 MANDATORY:
@@ -288,7 +336,7 @@ MANDATORY:
 
 ---
 
-## 10. Naming Conventions (Classes, IDs, Data Attributes)
+## 11. Naming Conventions (Classes, IDs, Data Attributes)
 
 ```
 MANDATORY:
@@ -327,7 +375,7 @@ MANDATORY:
 
 ---
 
-## 11. CSS Precision Rules
+## 12. CSS Precision Rules
 
 ```
 MANDATORY:
@@ -358,7 +406,7 @@ MANDATORY:
 
 ---
 
-## 12. Typography Rendering
+## 13. Typography Rendering
 
 ```
 MANDATORY:
@@ -391,7 +439,7 @@ MANDATORY:
 
 ---
 
-## 13. Color Accuracy
+## 14. Color Accuracy
 
 ```
 MANDATORY:
@@ -425,7 +473,7 @@ MANDATORY:
 
 ---
 
-## 14. Interactive States
+## 15. Interactive States
 
 ```
 MANDATORY:
@@ -462,7 +510,7 @@ MANDATORY:
 
 ---
 
-## 15. Visual Verification — Against FIGMA, Not Just Contracts
+## 16. Visual Verification — Against FIGMA, Not Just Contracts
 
 **Visual verification is handled by a dedicated Design Verification Agent**, spawned automatically by `gsd-t-execute` (Step 5.25) after all domain tasks complete.
 
@@ -476,36 +524,58 @@ VERIFICATION TARGETS:
   │     Does the code match the contract's claimed values?
   │     (This is what the 13-task validation proved works — airtight.)
   │
-  └── TARGET 2: Built screen vs FIGMA DESIGN (MANDATORY — this is new)
-        Does the BUILT SCREEN match the ORIGINAL FIGMA SCREENSHOT?
-        This catches: contracts that were wrong to begin with,
-        chart type misclassification, hallucinated data, missing elements.
-        (This is what was missing — and what caused the BDS failures.)
+  ├── TARGET 2: Built screen vs FIGMA DESIGN (MANDATORY)
+  │     Does the BUILT SCREEN match the ORIGINAL FIGMA STRUCTURED DATA?
+  │     This catches: contracts that were wrong to begin with,
+  │     chart type misclassification, hallucinated data, missing elements.
+  │
+  └── TARGET 3: SVG STRUCTURAL OVERLAY (MANDATORY)
+        Export Figma frame as SVG → parse element positions/dimensions/colors
+        → compare geometrically against built DOM bounding boxes.
+        This catches: aggregate spacing drift, alignment issues, proportion
+        errors that pass property-level checks but look wrong visually.
+        Mechanical, non-interpretive — no agent reasoning, just geometry.
 ```
 
-**Target 2 is the critical addition.** Verifying code-vs-contract is necessary but not sufficient. If the contract said "donut" when Figma showed a stacked bar, the code will faithfully build a donut, the contract verification will say MATCH, and the screen will be WRONG.
+**Targets 2 and 3 are complementary.** Target 2 catches wrong values (property-level). Target 3 catches wrong placement (geometry-level). Together they cover both "is each value correct?" and "does the whole page look right?"
 
 ### Verification agent workflow
 
 ```
 SEPARATION OF CONCERNS:
-  ├── CODING AGENT (you — Sections 1-14 above):
+  ├── CODING AGENT (you — Sections 1-15 above):
   │     Extract tokens → write precise CSS → trace every value to design contract
   │     Do NOT open a browser or attempt visual comparison yourself
   │
   └── DESIGN VERIFICATION AGENT (Step 5.25 of gsd-t-execute):
         1. Open browser → screenshot built page at each breakpoint
-        2. Get Figma screenshot (via MCP get_screenshot or saved reference image)
-        3. SIDE-BY-SIDE comparison: built screenshot vs Figma screenshot
+        2. Get Figma STRUCTURED DATA via `get_design_context` per widget node
+           ⚠ Do NOT use `get_screenshot` for Figma data — it returns pixels
+             you can't extract exact values from. `get_design_context` returns
+             structured code, component properties, and design tokens.
+           Use `get_metadata` first to enumerate widget nodes, then
+             `get_design_context` on each widget node individually.
+        3. STRUCTURED comparison: built page values vs Figma `get_design_context` values
         4. For EACH widget/section on the page:
-           a. What chart type does the FIGMA show? (look at the Figma screenshot)
-           b. What chart type did the CODE build? (look at the built screenshot)
+           a. What does `get_design_context` say this Figma node contains?
+              (chart type, text content, layout properties, colors)
+           b. What did the CODE actually build? (inspect built page DOM/styles)
            c. Do they match? Not "does code match contract" — does CODE match FIGMA?
         5. Check every text label: does the built screen show the same titles,
-           subtitles, column headers, legend items, KPI values as the Figma?
+           subtitles, column headers, legend items, KPI values as the Figma
+           `get_design_context` response?
         6. Produce structured comparison table (30+ rows):
-           | Element | Figma Shows | Built Shows | MATCH/DEVIATION |
-        7. Fix deviations → re-verify → artifact gate enforces completion
+           | Element | Figma (get_design_context) | Built | MATCH/DEVIATION |
+        7. SVG STRUCTURAL OVERLAY — mechanical geometry comparison:
+           a. Export Figma frame as SVG (API/MCP or user-provided)
+           b. Parse SVG DOM: positions, dimensions, fills, text per element
+           c. Map SVG elements → built DOM elements by text + position proximity
+           d. Compare geometry: position (≤2px=MATCH), dimensions, colors, text
+           e. Produce SVG diff table:
+              | SVG Element | SVG Position | Built Position | Δ px | Verdict |
+           f. Flag unmapped elements (MISSING IN BUILD / EXTRA IN BUILD)
+           This catches aggregate spacing/alignment drift the property table misses.
+        8. Fix deviations → re-verify → artifact gate enforces completion
 ```
 
 The verification agent enforces the **FAIL-BY-DEFAULT** rule: every visual element starts as UNVERIFIED. The only valid verdicts are MATCH (with proof) or DEVIATION (with specifics). "Looks close" and "appears to match" are not verdicts. An artifact gate in the orchestrator blocks completion if the comparison table is missing or empty.
@@ -514,7 +584,7 @@ The verification agent enforces the **FAIL-BY-DEFAULT** rule: every visual eleme
 
 ---
 
-## 16. Anti-Patterns
+## 17. Anti-Patterns
 
 ```
 NEVER DO THESE:
@@ -534,10 +604,12 @@ NEVER DO THESE:
 
 ---
 
-## 17. Design-to-Code Verification Checklist
+## 18. Design-to-Code Verification Checklist
 
 Before marking any design implementation task as complete:
 
+- [ ] Design system / component library identified (or confirmed none) and documented in design contract
+- [ ] Library components mapped to design elements — custom build only where no library match exists
 - [ ] 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)
@@ -555,4 +627,5 @@ Before marking any design implementation task as complete:
 - [ ] 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
+- [ ] SVG structural overlay comparison completed — geometry diff ≤2px per element
 - [ ] Verification results logged in design contract Verification Status table