@tekyzinc/gsd-t 2.69.13 → 2.70.10

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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)

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

@@ -748,19 +748,57 @@ Rules:
 - 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'
 

package/commands/gsd-t-quick.md

@@ -277,9 +277,21 @@ cannot be redeemed by visual polish.
 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.13",
+  "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,7 +35,43 @@ 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:
@@ -62,7 +98,7 @@ MANDATORY:
 
 ---
 
-## 2. MCP & Tool Detection
+## 3. MCP & Tool Detection
 
 ```
 MANDATORY:
@@ -95,7 +131,7 @@ MANDATORY:
 
 ---
 
-## 3. Stack Capability Evaluation
+## 4. Stack Capability Evaluation
 
 ```
 MANDATORY:
@@ -147,7 +183,7 @@ MANDATORY:
 
 ---
 
-## 4. Design Token Extraction Protocol
+## 5. Design Token Extraction Protocol
 
 ```
 MANDATORY:
@@ -172,7 +208,7 @@ MANDATORY:
 
 ---
 
-## 5. Design Contract Generation
+## 6. Design Contract Generation
 
 ```
 MANDATORY:
@@ -188,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:
@@ -226,7 +262,7 @@ Page
 
 ---
 
-## 7. Layout Analysis
+## 8. Layout Analysis
 
 ```
 MANDATORY:
@@ -247,7 +283,7 @@ MANDATORY:
 
 ---
 
-## 8. Responsive Breakpoint Strategy
+## 9. Responsive Breakpoint Strategy
 
 ```
 MANDATORY:
@@ -280,7 +316,7 @@ MANDATORY:
 
 ---
 
-## 9. Semantic HTML Structure
+## 10. Semantic HTML Structure
 
 ```
 MANDATORY:
@@ -300,7 +336,7 @@ MANDATORY:
 
 ---
 
-## 10. Naming Conventions (Classes, IDs, Data Attributes)
+## 11. Naming Conventions (Classes, IDs, Data Attributes)
 
 ```
 MANDATORY:
@@ -339,7 +375,7 @@ MANDATORY:
 
 ---
 
-## 11. CSS Precision Rules
+## 12. CSS Precision Rules
 
 ```
 MANDATORY:
@@ -370,7 +406,7 @@ MANDATORY:
 
 ---
 
-## 12. Typography Rendering
+## 13. Typography Rendering
 
 ```
 MANDATORY:
@@ -403,7 +439,7 @@ MANDATORY:
 
 ---
 
-## 13. Color Accuracy
+## 14. Color Accuracy
 
 ```
 MANDATORY:
@@ -437,7 +473,7 @@ MANDATORY:
 
 ---
 
-## 14. Interactive States
+## 15. Interactive States
 
 ```
 MANDATORY:
@@ -474,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.
 
@@ -488,20 +524,26 @@ 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
   │
@@ -524,7 +566,16 @@ SEPARATION OF CONCERNS:
            `get_design_context` response?
         6. Produce structured comparison table (30+ rows):
            | Element | Figma (get_design_context) | Built | MATCH/DEVIATION |
-        7. Fix deviations → re-verify → artifact gate enforces completion
+        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.
@@ -533,7 +584,7 @@ The verification agent enforces the **FAIL-BY-DEFAULT** rule: every visual eleme
 
 ---
 
-## 16. Anti-Patterns
+## 17. Anti-Patterns
 
 ```
 NEVER DO THESE:
@@ -553,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)
@@ -574,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