@tekyzinc/gsd-t 2.69.13 → 2.70.11

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.70.11] - 2026-04-06
+
+### Added (design pipeline — DOM box model inspection + layout arithmetic)
+- **DOM Box Model Inspection** — new mandatory verification step for fixed-height containers. Uses Playwright to evaluate `offsetHeight` vs `scrollHeight` for each child element. Flags elements where `offsetHeight > scrollHeight * 1.5` as INFLATED (symptom: `flex: 1` on a content element inflating its box beyond content size). Added to: `gsd-t-execute` (Step 5.5 inside Design Verification Agent), `gsd-t-quick` (step 8 inside Design Verification Agent), `gsd-t-design-audit` (Step 3.75).
+- **Internal Layout Arithmetic** — widget contract template now requires computed height budgets for fixed-height cards: `card_height - padding - header = body_available`, then `child1 + gap1 + child2 + ... = total_content ≤ body_available`. Forces the agent to write the math before coding — prevents `gap: 12px` when only `gap: 8px` fits.
+- **Flex Centering Anti-Pattern Rule** — `design-to-code.md` Section 8 now explicitly prohibits `flex: 1` on content elements (KPI, labels, text) for centering. Rule: `flex: 1` belongs on containers, `justify-content: center` on the parent. Children keep natural size.
+- **4 new verification checklist items** in `design-to-code.md` and `widget-contract.md`: box model inspection, layout arithmetic, no content flex:1, inflated element detection.
+
+### Why
+BDS horizontal stacked bar cards required 5 user-prompted fix iterations to get spacing right. Root cause: agent used `flex: 1` on `.kpi` to center it vertically, which inflated the element to 144px (content was 40px), displacing the chart section. The property comparison table and SVG overlay both missed this because the *positions* were close enough — the problem was *how space was distributed*, not where elements landed. DOM box model inspection catches the cause (inflated element) not just the symptom (displaced sibling).
+
+## [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,84 @@ 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 3.75: DOM Box Model Inspection (MANDATORY for fixed-height containers)
+
+For each card/widget with a fixed height, inspect the internal space distribution:
+
+1. **Evaluate in browser** (via Playwright) for each card body child:
+   - `offsetHeight` (layout box size), `scrollHeight` (content size), `flex-grow` (computed)
+
+2. **Flag inflated elements**: any element where `offsetHeight > scrollHeight * 1.5`
+   - This means `flex: 1` or `flex-grow: 1` is inflating the element's box beyond its content
+   - Severity: HIGH — "`.kpi` offsetHeight=144px but content only needs 40px — inflated by flex growth"
+
+3. **Verify layout arithmetic**: sum all child `offsetHeight` values + computed gaps. Compare against card body `offsetHeight`:
+   - Sum > body → content overflows (❌ DEVIATION)
+   - Sum < body by >20px with no centering strategy → space is unaccounted (❌ DEVIATION)
+
+4. **Produce box model table** per widget:
+
+```markdown
+### Box Model: {widget-name}
+
+| # | Element | offsetHeight | scrollHeight | flex-grow | Verdict |
+|---|---------|-------------|-------------|-----------|---------|
+| 1 | .kpi    | 144px       | 40px        | 1         | ❌ INFLATED |
+| 2 | .chart  | 74px        | 74px        | 0         | ✅ MATCH |
+```
+
 ## Step 4: Summary Report
 
-After all widgets are audited, produce a summary:
+After all widgets are audited (property tables + SVG structural diff + box model), 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,100 @@ 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 5.5: DOM Box Model Inspection (MANDATORY for fixed-height containers)
+
+The property table catches wrong values. The SVG overlay catches wrong positions.
+This step catches wrong SPACE DISTRIBUTION — elements whose box model is inflated
+by flex growth, pushing siblings out of position even when the visual appears close.
+
+For each card/widget with a fixed height (container_height is not 'auto'):
+
+1. Use Playwright to evaluate in the browser:
+   ```javascript
+   // For each child element of the card body:
+   const children = await page.$$eval('.card-body > *', els =>
+     els.map(el => ({
+       selector: el.className,
+       offsetHeight: el.offsetHeight,
+       scrollHeight: el.scrollHeight,
+       computedFlex: getComputedStyle(el).flex,
+       computedFlexGrow: getComputedStyle(el).flexGrow,
+     }))
+   );
+   ```
+
+2. Flag any element where `offsetHeight > scrollHeight * 1.5`:
+   This means the element's layout box is ≥50% larger than its content.
+   Symptom: element is using `flex: 1` or `flex-grow: 1` and inflating.
+   ❌ DEVIATION (severity HIGH): '{selector} offsetHeight={X}px but
+   content only needs {scrollHeight}px — inflated by flex growth.
+   Fix: remove flex:1 from this element, apply justify-content:center
+   on its parent container instead.'
+
+3. Verify layout arithmetic:
+   - Read the widget contract's Internal Layout Arithmetic section
+   - Sum all child offsetHeights + computed gaps
+   - Compare against the card body's offsetHeight
+   - If sum > body height → ❌ DEVIATION: content overflows
+   - If sum < body height by >20px with no centering strategy → ❌ DEVIATION
+
+4. Produce box model table:
+   | # | Element | offsetHeight | scrollHeight | flex-grow | Verdict |
+   |---|---------|-------------|-------------|-----------|---------|
+   | 1 | .kpi    | 144px       | 40px        | 1         | ❌ INFLATED |
+   | 2 | .chart  | 74px        | 74px        | 0         | ✅ MATCH |
+
+## 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,28 @@ 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. DOM Box Model Inspection (for fixed-height containers):
+   a. For each card body child, evaluate: offsetHeight, scrollHeight, flex-grow
+   b. Flag elements where offsetHeight > scrollHeight * 1.5 as INFLATED
+      (element using flex:1 when it shouldn't — box larger than content)
+   c. Verify layout arithmetic: sum of child heights + gaps = body height
+   d. Produce box model table:
+      | Element | offsetHeight | scrollHeight | flex-grow | Verdict |
+9. Write results (property table + SVG diff + box model) 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.11",
   "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:
@@ -245,9 +281,50 @@ MANDATORY:
 
 **GOOD** — Extracting gap as exactly `24px` from the design, then: `display: flex; gap: 1.5rem; /* 24px — design contract: section-gap */`
 
+### Flex Centering Anti-Pattern (MANDATORY)
+
+```
+NEVER use flex: 1 on a content element to center its text/content.
+flex: 1 makes the ELEMENT GROW to fill available space — the content
+centers within an oversized box, but the box itself displaces siblings.
+
+  WRONG — content element grows, inflated box shifts layout:
+    .kpi { flex: 1; display: flex; justify-content: center; }
+
+  RIGHT — parent grows, children keep natural size:
+    .body { flex: 1; display: flex; flex-direction: column;
+            justify-content: center; }
+    .kpi  { /* no flex: 1 — natural height only */ }
+
+  RULE: flex: 1 belongs on CONTAINERS, not on CONTENT elements.
+        To center content vertically, apply justify-content: center
+        on the parent — never flex: 1 on the child.
+```
+
+### Fixed-Height Container Arithmetic (MANDATORY)
+
+```
+When a card or container has a fixed height, BEFORE writing any CSS:
+  1. Compute the total available body height:
+     body_available = card_height - padding_top - padding_bottom
+                      - header_height - header_to_body_gap
+  2. List every child element's height (from the design contract)
+  3. List every gap between children
+  4. SUM them: total_content = child1 + gap1 + child2 + gap2 + ...
+  5. Compare: total_content MUST ≤ body_available
+  6. If total_content < body_available:
+     Document the centering strategy (justify-content: center on parent)
+  7. If total_content > body_available:
+     The design extraction is wrong — go back to Figma
+
+  This arithmetic goes in the widget contract's Internal Layout
+  Arithmetic section. The implementation MUST match the arithmetic.
+  If gap: 12px makes the math exceed body_available, use gap: 8px.
+```
+
 ---
 
-## 8. Responsive Breakpoint Strategy
+## 9. Responsive Breakpoint Strategy
 
 ```
 MANDATORY:
@@ -280,7 +357,7 @@ MANDATORY:
 
 ---
 
-## 9. Semantic HTML Structure
+## 10. Semantic HTML Structure
 
 ```
 MANDATORY:
@@ -300,7 +377,7 @@ MANDATORY:
 
 ---
 
-## 10. Naming Conventions (Classes, IDs, Data Attributes)
+## 11. Naming Conventions (Classes, IDs, Data Attributes)
 
 ```
 MANDATORY:
@@ -339,7 +416,7 @@ MANDATORY:
 
 ---
 
-## 11. CSS Precision Rules
+## 12. CSS Precision Rules
 
 ```
 MANDATORY:
@@ -370,7 +447,7 @@ MANDATORY:
 
 ---
 
-## 12. Typography Rendering
+## 13. Typography Rendering
 
 ```
 MANDATORY:
@@ -403,7 +480,7 @@ MANDATORY:
 
 ---
 
-## 13. Color Accuracy
+## 14. Color Accuracy
 
 ```
 MANDATORY:
@@ -437,7 +514,7 @@ MANDATORY:
 
 ---
 
-## 14. Interactive States
+## 15. Interactive States
 
 ```
 MANDATORY:
@@ -474,7 +551,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 +565,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 +607,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 +625,7 @@ The verification agent enforces the **FAIL-BY-DEFAULT** rule: every visual eleme
 
 ---
 
-## 16. Anti-Patterns
+## 17. Anti-Patterns
 
 ```
 NEVER DO THESE:
@@ -553,10 +645,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 +668,8 @@ 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
+- [ ] DOM box model inspection passed — no inflated elements (offsetHeight >> scrollHeight)
+- [ ] Layout arithmetic verified — child heights + gaps = body available height (fixed-height cards)
+- [ ] No content element uses `flex: 1` for centering — only parent containers
 - [ ] Verification results logged in design contract Verification Status table

package/templates/widget-contract.md

@@ -95,6 +95,41 @@ This section specifies how elements are sized, spaced, and aligned WITHIN the ca
 - `body_layout` + `body_justify` + `body_align` together define whether the chart is centered in its card, left-aligned, or stretched. Get this wrong and every widget "looks off."
 - These values are WIDGET-OWNED — they describe how the widget positions its elements, not the elements' internal specs (which live in element contracts).
 
+### Internal Layout Arithmetic (MANDATORY for fixed-height cards)
+
+When `container_height` is fixed (not `auto`), you MUST compute and document the internal height budget. The math must add up exactly — no approximation.
+
+```
+card_height:           {e.g., 334px}
+card_padding_top:      {e.g., 16px}
+card_padding_bottom:   {e.g., 16px}
+header_height:         {title + subtitle + gap} = {e.g., 48px}
+header_to_body_gap:    {e.g., 16px}
+─────────────────────────────────────────────────
+body_available:        {card_height - padding_top - padding_bottom
+                        - header_height - header_to_body_gap}
+                       = {e.g., 334 - 16 - 16 - 48 - 16 = 238px}
+
+body_breakdown:
+  kpi_height:          {natural content height, e.g., 40px — NOT flex:1}
+  kpi_to_chart_gap:    {e.g., 16px}
+  chart_section:       {bar + gap + labels + gap + legend}
+                       = {e.g., 30 + 8 + 12 + 8 + 16 = 74px}
+  ────────────────────
+  total_body_content:  {40 + 16 + 74 = 130px}
+  remaining_space:     {238 - 130 = 108px}
+
+centering_strategy:    {e.g., body uses flex-column + justify-content: center
+                        to vertically center the content group (KPI + chart)
+                        in the 238px body area. KPI keeps natural height.}
+```
+
+**Rules:**
+- Every row must be an exact pixel value extracted from the Figma design
+- The sum of all body content MUST equal `body_available` OR explicitly document how remaining space is distributed (centering, padding, etc.)
+- **NEVER use `flex: 1` on a content element (KPI, label, text) to center it.** `flex: 1` makes the element grow to fill available space, inflating its box model. Use `flex: 1` + `justify-content: center` on the PARENT container instead. The parent grows; children keep natural size.
+- If the math doesn't add up, the design extraction is incomplete — go back to Figma
+
 ## Data Binding
 
 **Widget input shape:**
@@ -189,6 +224,9 @@ Widget-level verification runs AFTER all referenced elements pass their own veri
 - [ ] Element sizing matches design (chart_width, chart_height, legend_width)
 - [ ] Legend alignment matches design (footer_legend_justify: center vs left)
 - [ ] Card container values match design (padding, border, radius, shadow)
+- [ ] Layout arithmetic adds up: sum of child heights + gaps = body_available (fixed-height cards only)
+- [ ] No content element uses `flex: 1` for centering — only parent containers may use `flex: 1`
+- [ ] DOM box model check: no element's offsetHeight >> its content height (inflated box = wrong flex)
 - [ ] Responsive breakpoints adapt as specified
 - [ ] Data binding produces correct element inputs (spot-check with sample data)
 - [ ] Inter-element interactions fire (hover sync, click propagation)