@tekyzinc/gsd-t 2.69.11 → 2.69.13

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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)
+- **Explicit `get_screenshot` prohibition** — agents were choosing `get_screenshot` (returns pixels) instead of `get_design_context` (returns structured code/tokens) for per-widget Figma extraction, defeating structured comparison. Both commands now have explicit tool guards: "NEVER use `get_screenshot` for Figma design extraction." `get_screenshot` is only acceptable for capturing the built page, not for extracting Figma source data.
+
 ## [2.69.11] - 2026-04-05
 
 ### Changed (gsd-t-design-audit)

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

@@ -33,13 +33,16 @@ Figma node tree:
 
 ### 1b. Extract each widget node
 
-For EACH widget-level node, call `get_design_context` with the specific node ID. Record:
+For EACH widget-level node, call **`get_design_context`** (NOT `get_screenshot`) with the specific node ID. `get_design_context` returns structured code and component properties that you can extract exact values from. `get_screenshot` returns only visual images — do NOT use it for Figma data extraction.
+
+Record from the `get_design_context` response:
 - **Chart/element type**: what visual pattern does this node contain?
 - **All text content**: every title, subtitle, label, column header, legend item, KPI value, axis label
 - **Layout properties**: alignment, spacing, sizing from the returned code/structure
 - **Colors**: exact hex values for fills, strokes, text
 
 > **⚠ Size guard**: Never call `get_design_context` on the full page frame. Always call on individual widget/card nodes.
+> **⚠ Tool guard**: NEVER use `get_screenshot` to extract Figma design values. It gives you pixels, not properties. Use `get_design_context` — it gives you code, tokens, and structured data.
 
 ### 1c. Classify each element using the taxonomy
 
@@ -226,7 +229,7 @@ After fixes are applied, **re-run the audit automatically** to verify. Loop unti
 - **You write ZERO code during the audit phase (Steps 1-5).** Report only. Code changes happen in Step 6 via `/user:gsd-t-quick`.
 - **You do NOT "look close" at anything.** Every property gets an exact value from Figma and an exact value from the build. They match or they don't.
 - **You do NOT skip widgets.** Every widget in the Figma AND every widget in the build gets audited.
-- **You call `get_design_context` per widget node.** Do not classify from a page-level screenshot.
+- **You MUST call `get_design_context` per widget node — NOT `get_screenshot`.** `get_design_context` returns structured code, component properties, and design tokens. `get_screenshot` returns only a visual image that you cannot extract exact values from. Using `get_screenshot` for widget extraction defeats the entire purpose of structured comparison — you end up eyeballing instead of measuring. The ONLY acceptable use of `get_screenshot` is for the built page (Step 2) where you need to see what was actually rendered. For Figma source data, ALWAYS use `get_design_context`.
 - **You walk the taxonomy decision tree** for every chart element — document your reasoning.
 - **Minimum 10 rows per widget, 30+ for complex widgets.** Fewer rows means you skipped properties.
 - **If you can't determine a value** (e.g., Figma MCP unavailable for exact px), note "⚠ estimated from screenshot" — but still provide your best measurement.

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

@@ -71,6 +71,8 @@ Node tree for page "Analytics":
 
 **Anti-pattern**: Looking at a page screenshot and writing "I see a donut chart" without calling `get_design_context` on that specific node. The MCP returns structured data about the component — use it.
 
+> **⚠ Tool guard**: NEVER use `get_screenshot` for Figma design extraction. `get_screenshot` returns pixels — you cannot extract exact property values, spacing, colors, or text from an image with confidence. `get_design_context` returns structured code, component properties, and design tokens. Always use `get_design_context` per widget node.
+
 ### 1d. Produce the flat inventory table WITH data inventory
 
 | # | Element on Design | Figma Node ID | Appears On Pages | Text Content Extracted | Visual Variant |

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.11",
+  "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
 ```