@tekyzinc/gsd-t 2.69.12 → 2.69.13

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [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-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,8 +741,9 @@ 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
@@ -837,7 +849,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,9 +266,12 @@ 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.69.12",
+  "version": "2.69.13",
   "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

@@ -42,7 +42,13 @@ 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
@@ -62,11 +68,17 @@ MANDATORY:
 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
@@ -495,16 +507,23 @@ SEPARATION OF CONCERNS:
   │
   └── 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 |
+           | Element | Figma (get_design_context) | Built | MATCH/DEVIATION |
         7. Fix deviations → re-verify → artifact gate enforces completion
 ```