@tekyzinc/gsd-t 2.67.10 → 2.68.11

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.68.11] - 2026-04-05
+
+### Changed (widget-contract template)
+- **Alignment column in Card Chrome Slots** — every slot now requires explicit alignment (left/center/right) extracted from Figma. Incorrect legend alignment was the #2 cause of "looks off" results.
+- **Internal Element Layout section (MANDATORY)** — new section replacing the flat layout table. Documents: body_layout (flex-row/column/grid), body_justify, body_align, body_gap, chart_width/height, legend_width, footer_legend_justify, header_to_body_gap, body_to_footer_gap. These are the exact values that control spacing and sizing of elements within a widget card.
+- **Verification checklist expanded** — now checks: chrome alignment, internal layout, inter-element spacing, element sizing, legend alignment, card container values (6 new items).
+
+### Why
+BDS Analytics comparison revealed consistent intra-widget layout errors: legends left-aligned instead of centered, inconsistent spacing between chart and legend, wrong element sizing within cards. The widget contract template had a Layout section but it specified only container-level properties (padding, border, gap) — not how elements were sized, spaced, and aligned WITHIN the card body. These new fields close that gap.
+
+## [2.68.10] - 2026-04-05
+
+### Changed (gsd-t-design-decompose)
+- **Node-level Figma decomposition (MANDATORY)** — Step 1 now requires `get_metadata` to map page tree, then `get_design_context` on EACH widget node individually. No more classifying from page screenshots alone. Extracted text content (titles, subtitles, column headers, legend items) becomes mandatory data inventory column.
+- **Classification reasoning (MANDATORY)** — Step 2 now requires written decision-tree walkthrough for every chart element: "I see [description]. Decision tree: [walkthrough]. Classification: [entry]. Confidence: [HIGH/MEDIUM/LOW]". Low/medium confidence entries flagged for human review.
+- **Human contract review checkpoint** — Step 5 now presents classification reasoning table + data inventory alongside decomposition summary. User reviews chart type assignments and text content before contracts are written. 5-minute gate that catches misclassification before it propagates.
+- **Contract-vs-Figma verification gate (MANDATORY)** — New Step 6.5 re-reads each Figma node after contracts are written and produces a mismatch report. Catches: wrong chart types, hallucinated column headers, missing elements, invented data models. Mismatches must be fixed before proceeding to build.
+
+### Changed (design-to-code stack rule)
+- **Visual verification against FIGMA, not just contracts** — Section 15 now requires the Design Verification Agent to compare the built screen against the original Figma screenshot (Target 2), not just against design contracts (Target 1). This closes the gap where wrong contracts produce wrong code that still scores 50/50 against itself.
+
+### Why
+Post-validation comparison of the built BDS Analytics screen against the original Figma design revealed: wrong chart types (donuts instead of stacked bars in Member Segmentation), hallucinated column headers (Video Playlist), invented data models (Tool Engagement). All scored 50/50 against their contracts — because the contracts were wrong. The contracts→code pipeline is airtight; the Figma→contracts pipeline was unverified. These changes close that gap at four layers: node-level extraction, classification reasoning, human review, and contract-vs-Figma gate.
+
 ## [2.67.10] - 2026-04-05
 
 ### Added (design-chart-taxonomy)

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

@@ -38,33 +38,84 @@ Run these checks, log results to user inline:
    - Keep the taxonomy in working memory while classifying — every element you identify MUST be matched against it
    - **Filename rule**: the element contract filename MUST match the taxonomy name exactly (`chart-bar-vertical-single.contract.md`, not `bar-vertical-single.contract.md`). Shortened aliases are FORBIDDEN — they create taxonomy drift and make link-integrity checks fail. If an existing legacy contract uses a shortened name, prefer renaming it to the taxonomy name over creating a parallel file.
 
-## Step 1: Survey the Design
+## Step 1: Survey the Design — Node-Level Figma Decomposition (MANDATORY)
 
-Enumerate every visual element on every page/screen in the design. Use Figma MCP `get_metadata` or `get_design_context` if available; otherwise use visual analysis on the image.
+> **⚠  This is the highest-leverage step in the entire workflow.** Most design-to-code errors originate here — the agent glances at a page screenshot, guesses chart types, and writes contracts from wrong assumptions. The fix is STRUCTURED NODE-LEVEL EXTRACTION, not "look harder."
 
-> **⚠  Figma MCP size guard**: `get_design_context` on a full-page frame (e.g., a 390×3372px mobile screen) can return 250KB+ and be auto-saved to a tool-results file, forcing you to grep through it. **Always call `get_metadata` FIRST** to map the tree, then call `get_design_context` **only on leaf card/component nodes** (typically < 100KB). If you must call it on a frame, use `excludeScreenshot: true` to halve the payload.
+### 1a. Map the page tree
 
-Produce an initial flat inventory table:
+Call `get_metadata` on the page/frame to get the full node tree. This returns the Figma component hierarchy — every group, frame, and component instance as named nodes with IDs.
 
-| # | Element on Design                  | Appears On Pages       | Visual Variant                       |
-|---|------------------------------------|------------------------|--------------------------------------|
-| 1 | Donut chart with center label      | Overview, Analytics    | chart-donut                          |
-| 2 | Horizontal stacked bar chart       | Analytics              | chart-bar-stacked-horizontal         |
-| 3 | Vertical legend on right           | Overview               | legend-vertical-right                |
-| 4 | KPI tile with delta indicator      | Overview (×4)          | stat-card-with-delta                 |
-| ...
+### 1b. Identify widget-level nodes
+
+From the metadata tree, identify every distinct visual group (card, widget, section). These are typically direct children of a page frame or section frame. List them:
+
+```
+Node tree for page "Analytics":
+├── stat-card-campaign (id: 123:456)
+├── stat-card-visitors (id: 123:457)
+├── most-popular-tools-card (id: 123:458)
+├── number-of-tools-card (id: 123:459)
+├── ...
+```
+
+### 1c. Call `get_design_context` on EACH widget node individually (MANDATORY)
+
+**Do NOT skip this.** Do NOT classify from the page screenshot alone. For each widget node identified in 1b:
+
+1. Call `get_design_context` with the specific node ID
+2. Record the returned: component type, code hints, text content, layout properties
+3. Extract EVERY text string visible in the node (titles, subtitles, labels, column headers, legend items, axis labels, KPI values)
+
+> **⚠  Figma MCP size guard**: `get_design_context` on a full-page frame (e.g., a 390×3372px mobile screen) can return 250KB+ and be auto-saved to a tool-results file. **Never call it on the full page.** Call it on each leaf card/component node individually (typically < 100KB each). If you must inspect a large frame, use `excludeScreenshot: true` to halve the payload.
+
+**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.
 
-**Rule**: distinct visual variants = distinct rows. A horizontal stacked bar and a vertical stacked bar are TWO rows, not one.
+### 1d. Produce the flat inventory table WITH data inventory
 
-## Step 2: Classify Each Element (taxonomy-enforced)
+| # | Element on Design | Figma Node ID | Appears On Pages | Text Content Extracted | Visual Variant |
+|---|-------------------|---------------|------------------|----------------------|----------------|
+| 1 | Donut chart with center label | 123:458 | Overview, Analytics | Title: "Most Popular Tools", Subtitle: "Which tools members interact with most", Center: "485", Center sub: "Total Interactions", Legend: ["Steps to Stay Covered 30%", "Broker Contact 21%", ...] | chart-donut |
+| 2 | Stacked bar with KPI header | 123:459 | Analytics | Title: "Number of Tools", Subtitle: "How many tools members interact with", KPI: "2.4", KPI sub: "Avg tools per member", Legend: ["1 Tool", "2 Tools", "3 Tools", "4+ Tools"], Labels: ["{num}%", ...] | chart-bar-stacked-horizontal-percentage |
+| ... | | | | | |
+
+**Rules**:
+- Distinct visual variants = distinct rows. A horizontal stacked bar and a vertical stacked bar are TWO rows.
+- The "Text Content Extracted" column is MANDATORY. Every text string visible in the Figma node MUST be listed. This kills hallucinated column headers and invented data models.
+- If `get_design_context` is unavailable (no Figma MCP), extract text from the screenshot with maximum care and flag "⚠ extracted from screenshot, not MCP — verify manually".
+
+## Step 2: Classify Each Element — Show Your Reasoning (MANDATORY)
 
 For each row in the inventory, assign:
 
-- **Category** — chart / legend / axis / card / table / control / atom / typography / layout
+- **Category** — chart / legend / axis / card / table / list / control / atom / typography / layout
 - **Element name** — **MUST come from `templates/design-chart-taxonomy.md`** (closed set). If no match found, STOP and ask user to extend the taxonomy with rationale.
 - **Reuse count** — how many times does it appear across the entire design?
 - **Owner layer** — element / widget-internal / page-internal
 
+### Classification reasoning (MANDATORY — show your work)
+
+For EACH chart/visualization element, you MUST walk the taxonomy decision tree and document your reasoning. This is not optional — skipping this step is how donut charts get classified as stacked bars and vice versa.
+
+**Required format for each element:**
+
+```
+Element #2: node 123:459 "Number of Tools"
+  I SEE: A horizontal bar that fills full width, divided into 4 colored segments
+         with percentage labels above each segment. Legend below: "1 Tool", "2 Tools",
+         "3 Tools", "4+ Tools". Single bar, not multiple bars per category.
+  DECISION TREE:
+    - Is it a bar chart? YES — has rectangular segments
+    - Stacked or grouped? STACKED — segments touch, share one bar
+    - Horizontal or vertical? HORIZONTAL — bar extends left to right
+    - Percentage or absolute? PERCENTAGE — single bar, segments sum to 100%,
+      labels show {num}%
+  CLASSIFICATION: chart-bar-stacked-horizontal-percentage
+  CONFIDENCE: HIGH — matches taxonomy distinguisher exactly
+```
+
+**If confidence is LOW or MEDIUM**, flag it for human review in Step 5.
+
 ### Visual distinguisher decision rules (consult taxonomy)
 
 Before naming an element, apply the visual distinguisher rules from the taxonomy:
@@ -72,9 +123,12 @@ Before naming an element, apply the visual distinguisher rules from the taxonomy
 - **Bar chart?** → is it stacked/grouped, horizontal/vertical, percentage/absolute? These are ALL distinct element contracts.
 - **Circular?** → pie vs donut (hole in center?) vs gauge (partial arc?)
 - **Line?** → single vs multi, stepped vs smooth, with area or without
+- **Table vs list?** → columns aligned across rows with header = table; self-contained rows = list
 
 **Anti-pattern to avoid**: "it has bars so it's a bar chart" → WRONG. The failure mode is picking `chart-bar-grouped-vertical` when the design is `chart-bar-stacked-horizontal-percentage`. These render completely differently with completely different data bindings.
 
+**Anti-pattern to avoid**: "it has circles so it's a donut" → WRONG. A pair of stacked vertical bar charts side-by-side is NOT two donut charts, even if the bars have rounded segments. LOOK AT THE ACTUAL SHAPE.
+
 **Promotion rule**: an item becomes an **element contract** if:
 - It appears ≥2 times across the design, OR
 - It has non-trivial visual spec (≥5 distinct spec properties), OR
@@ -110,15 +164,15 @@ Each page/screen in the design becomes a page contract. Document:
 - Global layout (header, sidebar, main)
 - Route + auth guards
 
-## Step 5: Confirm Decomposition With User
+## Step 5: Confirm Decomposition With User — Contract Review Checkpoint
 
-Present the full hierarchy summary:
+Present the full hierarchy summary WITH classification reasoning:
 
 ```
 DECOMPOSITION SUMMARY
 ─────────────────────
 Elements: 14 contracts
-  Charts: 4 (chart-donut, chart-bar-stacked-horizontal, chart-line, chart-sparkline)
+  Charts: 4 (chart-donut, chart-bar-stacked-horizontal-percentage, chart-line-single, chart-sparkline-line)
   Legends: 2 (legend-vertical-right, legend-horizontal-bottom)
   Cards: 2 (stat-card, stat-card-with-delta)
   Tables: 1 (table-dense)
@@ -132,18 +186,33 @@ Pages: 3 contracts
   dashboard-overview, analytics-detail, settings
 
 Total: 23 contracts (vs. flat: ~57 elements in single file)
-
-Cost estimate:
-  - Decomposition effort: ~{N} hours to write all contracts
-  - Verification: elements verified once, reused everywhere → no drift
-  - Implementation: widgets become assembly, not reinvention
 ```
 
+**Then present the classification reasoning table** (from Step 2) as a condensed review:
+
+| # | Widget/Element | Classified As | Key Reasoning | Confidence |
+|---|----------------|---------------|---------------|------------|
+| 1 | Most Popular Tools body | chart-donut | Circle with center hole + center label "485" + 5 colored segments | HIGH |
+| 2 | Number of Tools body | chart-bar-stacked-horizontal-percentage | Single horizontal bar, 4 segments summing to 100%, {num}% labels | HIGH |
+| 3 | Member State chart | chart-bar-stacked-vertical | Multiple stacked vertical bars, 2 groups side-by-side, percentage labels | MEDIUM — verify |
+| ... | | | | |
+
+**Highlight any MEDIUM/LOW confidence entries** — these are the misclassification risks.
+
+**Present the data inventory** for each widget — the user can quickly spot if column headers or labels were hallucinated:
+
+| Widget | Title | Subtitle | Data Labels |
+|--------|-------|----------|-------------|
+| Video Playlist | "Video Playlist" | (none) | Columns: Video, Viewed, Clicked Thumbnail, Clicked CTA, Avg. Seconds Watched |
+| Tool Engagement | "Tool Engagement" | (none) | Tabs: [Your 2026 Plan Options, ...], Stats: "487 Total members who viewed", "300 Total members who clicked CTA" |
+
 Ask user: "Proceed with this decomposition? [y/n/edit]"
 - **y** → Step 6
 - **n** → abort
 - **edit** → accept user revisions to the hierarchy, re-present
 
+> **Why this checkpoint matters**: The 13-task validation (v2.59–v2.67) proved contracts→code is airtight. But Figma→contracts was unverified — misclassifications at this step propagate through the entire build uncaught. This 5-minute review catches: wrong chart types, hallucinated data models, missing elements, wrong labels.
+
 ## Step 6: Write Contracts
 
 Create the directory structure:
@@ -204,6 +273,41 @@ element contract > widget contract > page contract
 Widgets and pages reference elements by name. They CANNOT override element visual spec. To customize, create a new element variant.
 ```
 
+## Step 6.5: Contract-vs-Figma Verification Gate (MANDATORY)
+
+After writing all contracts but BEFORE proceeding to partition or build, verify that each contract accurately represents the Figma design. This gate catches errors that would otherwise propagate through the entire build.
+
+### For each widget contract:
+
+1. **Re-read the Figma node** — call `get_design_context` (or re-examine the screenshot) for the specific widget node
+2. **Compare the contract's claimed structure against the actual Figma node:**
+
+| Check | What to verify | Failure mode it prevents |
+|-------|---------------|------------------------|
+| Chart type | Contract's element name matches the actual visual pattern | Donut classified as stacked bar (or vice versa) |
+| Data labels | Contract's Test Fixture labels match the Figma text exactly | Hallucinated column headers, invented metrics |
+| Element count | Number of sub-elements in contract matches Figma | Missing legends, extra charts, wrong layout |
+| Text content | Every title, subtitle, label, legend item matches Figma verbatim | "Engagement per video" subtitle that doesn't exist in Figma |
+| Layout structure | Widget's claimed layout matches Figma arrangement | Side-by-side classified as stacked, 2 charts classified as 1 |
+
+3. **Produce a contract-vs-Figma mismatch report:**
+
+```
+CONTRACT-VS-FIGMA VERIFICATION
+───────────────────────────────
+✅ most-popular-tools-card: chart-donut — MATCHES Figma node 123:458
+✅ number-of-tools-card: chart-bar-stacked-horizontal-percentage — MATCHES
+❌ member-state-card: chart-donut — MISMATCH: Figma shows stacked vertical bars, not donuts
+   → Fix: reclassify as chart-bar-stacked-vertical, rewrite element contract
+❌ video-playlist-table: columns [Title, Duration, Views, Watch Time, Completion]
+   — MISMATCH: Figma shows [Video, Viewed, Clicked Thumbnail, Clicked CTA, Avg. Seconds Watched]
+   → Fix: update Test Fixture column headers
+```
+
+4. **If ANY mismatches found**: fix the contracts BEFORE proceeding. Do not build from wrong contracts.
+
+> **Why this gate exists**: The two-terminal validation (tasks 001-013) proved the system produces 50/50 scores when contracts are correct — but also revealed that scoring code-vs-contract doesn't catch contract-vs-Figma errors. This gate closes that gap.
+
 ## Step 7: Wire Into Partition
 
 If `.gsd-t/domains/` exists (project is already partitioned), append to relevant domain's `scope.md`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.67.10",
+  "version": "2.68.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 51 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

@@ -462,11 +462,30 @@ MANDATORY:
 
 ---
 
-## 15. Visual Verification
+## 15. 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. The verification agent's ONLY job is to open a browser, compare the built frontend against the original design, and produce a structured element-by-element comparison table.
+**Visual verification is handled by a dedicated Design Verification Agent**, spawned automatically by `gsd-t-execute` (Step 5.25) after all domain tasks complete.
 
-**Your job as the coding agent**: Write precise code from the design contract tokens. Every CSS value must trace to a design contract entry. Use exact hex colors, exact spacing values, exact typography. The verification agent will open a browser and prove whether your code matches.
+### Critical distinction: TWO verification targets
+
+The verification agent compares the built frontend against **TWO sources** — not just one:
+
+```
+VERIFICATION TARGETS:
+  ├── TARGET 1: Built screen vs DESIGN CONTRACTS
+  │     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 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.
+
+### Verification agent workflow
 
 ```
 SEPARATION OF CONCERNS:
@@ -475,13 +494,24 @@ SEPARATION OF CONCERNS:
   │     Do NOT open a browser or attempt visual comparison yourself
   │
   └── DESIGN VERIFICATION AGENT (Step 5.25 of gsd-t-execute):
-        Open browser → screenshot at breakpoints → build element inventory →
-        produce structured comparison table (30+ rows) → report MATCH/DEVIATION
-        per element → fix deviations → re-verify → artifact gate enforces completion
+        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
+        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)
+           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?
+        6. Produce structured comparison table (30+ rows):
+           | Element | Figma Shows | Built Shows | MATCH/DEVIATION |
+        7. 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.
 
+> **Why "vs Figma" matters**: The two-terminal validation (v2.59–v2.67, 13 tasks, all 50/50) proved contracts→code is reliable. But when the BUILT screen was compared to the ACTUAL Figma design, major deviations emerged: wrong chart types (donuts instead of stacked bars), hallucinated column headers, invented data models — all of which scored 50/50 against their (wrong) contracts. Verifying against Figma, not just contracts, is the fix.
+
 ---
 
 ## 16. Anti-Patterns

package/templates/widget-contract.md

@@ -19,18 +19,20 @@ Composition of elements + data binding + layout. Widgets SELECT and POSITION ele
 
 Every widget is a card with consistent chrome. Missing chrome is the #1 cause of "looks off" verification results. Document EVERY slot, even if empty.
 
-| Slot                    | Element Contract (or N/A)                | Content / Behavior                               |
-|-------------------------|------------------------------------------|--------------------------------------------------|
-| `title`                 | heading-h3                               | {exact title text from design}                   |
-| `subtitle`              | text-caption or N/A                      | {exact subtitle text — "Which tools members interact with most."} |
-| `header_right_control`  | select-dropdown, button-ghost, or N/A    | {e.g., "Members ▼" filter dropdown in card header} |
-| `kpi_header`            | stat-card-kpi-large or N/A               | {e.g., "2.4" + "Avg tools per member" shown above chart} |
-| `body`                  | {primary element, e.g., chart-donut}     | {main visual}                                    |
-| `body_sidebar`          | {e.g., legend-vertical-right or N/A}     | {element positioned alongside body}              |
-| `footer`                | {e.g., text-caption or N/A}              | {e.g., "Last updated: ..."}                      |
-| `footer_legend`         | {e.g., legend-horizontal-bottom or N/A}  | {legend below body}                              |
-
-**Rule**: If the design shows it, document it. If the design doesn't show it, write "N/A". Do NOT leave blank.
+| Slot                    | Element Contract (or N/A)                | Content / Behavior                               | Alignment       |
+|-------------------------|------------------------------------------|--------------------------------------------------|-----------------|
+| `title`                 | heading-h3                               | {exact title text from design}                   | {left / center} |
+| `subtitle`              | text-caption or N/A                      | {exact subtitle text — "Which tools members interact with most."} | {left / center} |
+| `header_right_control`  | select-dropdown, button-ghost, or N/A    | {e.g., "Members ▼" filter dropdown in card header} | right           |
+| `kpi_header`            | stat-card-kpi-large or N/A               | {e.g., "2.4" + "Avg tools per member" shown above chart} | {left / center} |
+| `body`                  | {primary element, e.g., chart-donut}     | {main visual}                                    | {center / left} |
+| `body_sidebar`          | {e.g., legend-vertical-right or N/A}     | {element positioned alongside body}              | {left / center} |
+| `footer`                | {e.g., text-caption or N/A}              | {e.g., "Last updated: ..."}                      | {left / center} |
+| `footer_legend`         | {e.g., legend-horizontal-bottom or N/A}  | {legend below body}                              | {center / left} |
+
+**Rules**:
+- If the design shows it, document it. If the design doesn't show it, write "N/A". Do NOT leave blank.
+- The **Alignment** column is MANDATORY. Incorrect alignment (left vs center) is the #2 cause of "looks off" results after missing chrome. Extract alignment from the Figma node — do not default to left.
 
 ## Elements Used (body composition)
 
@@ -46,25 +48,52 @@ Every widget is a card with consistent chrome. Missing chrome is the #1 cause of
 ```
 ┌──────────────────────────────────────────────┐
 │ {title}                        [{filter}]    │
+│ {subtitle}                                   │
 ├──────────────────────────────────────────────┤
 │              │                               │
 │   {chart}    │      {legend}                 │
 │              │                               │
+├──────────────────────────────────────────────┤
+│          {footer_legend}                     │
 └──────────────────────────────────────────────┘
 ```
 
+### Card Container
+
 | Property           | Value                                               |
 |--------------------|-----------------------------------------------------|
 | container_width    | {100% of parent / fixed 480px}                      |
 | container_height   | {auto / fixed 320px}                                |
-| padding            | {tokens.spacing.6}                                  |
-| gap                | {tokens.spacing.4}                                  |
-| background         | {tokens.color.surface.card}                         |
-| border             | {1px solid tokens.color.border.subtle}              |
-| border_radius      | {tokens.radius.lg}                                  |
-| shadow             | {tokens.shadow.sm}                                  |
-| chart_area_ratio   | {60% of widget width}                               |
-| legend_area_ratio  | {40% of widget width}                               |
+| padding            | {16px — extract exact value from Figma}             |
+| background         | {#ffffff}                                           |
+| border             | {1px solid #e2e8f0}                                 |
+| border_radius      | {8px}                                               |
+| shadow             | {none / 0 2px 8px rgba(0,0,0,0.1)}                 |
+
+### Internal Element Layout (MANDATORY — the "looks off" killer)
+
+This section specifies how elements are sized, spaced, and aligned WITHIN the card body. Missing or wrong values here produce the "spacing inside widgets" and "legends incorrectly aligned" class of errors.
+
+| Property                    | Value                                                      |
+|-----------------------------|------------------------------------------------------------|
+| header_to_body_gap          | {16px — gap between title/subtitle row and body content}   |
+| body_layout                 | {flex-row / flex-column / grid}                            |
+| body_justify                | {center / flex-start / space-between}                      |
+| body_align                  | {center / flex-start / stretch}                            |
+| body_gap                    | {24px — gap between body element and sidebar element}      |
+| chart_width                 | {180px / 60% of body / auto}                               |
+| chart_height                | {180px / auto}                                             |
+| chart_align_self            | {center / flex-start}                                      |
+| legend_width                | {auto / 40% of body}                                       |
+| legend_align_self           | {center / flex-start}                                      |
+| body_to_footer_gap          | {16px — gap between body and footer/footer_legend}         |
+| footer_legend_justify       | {center / flex-start — EXTRACT FROM FIGMA, do not default} |
+
+**Rules**:
+- Extract EVERY value from the Figma node — do not approximate.
+- `footer_legend_justify` is critical: center-aligned legends look completely different from left-aligned. Check the Figma.
+- `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).
 
 ## Data Binding
 
@@ -154,7 +183,12 @@ The widget harness page (`/design-system/{widget-name}`) renders ONE widget inst
 Widget-level verification runs AFTER all referenced elements pass their own verification. Widget verification only checks composition — element internals are out of scope.
 
 - [ ] All referenced elements present and correctly slotted
-- [ ] Layout dimensions (width, height, padding, gap) match design
+- [ ] Card chrome alignment matches design (title left/center, legend center/left, etc.)
+- [ ] Internal element layout matches design (body_layout, body_justify, body_align)
+- [ ] Inter-element spacing matches design (header_to_body_gap, body_gap, body_to_footer_gap)
+- [ ] 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)
 - [ ] Responsive breakpoints adapt as specified
 - [ ] Data binding produces correct element inputs (spot-check with sample data)
 - [ ] Inter-element interactions fire (hover sync, click propagation)