@tekyzinc/gsd-t 2.68.12 → 2.69.10

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.69.10] - 2026-04-05
+
+### Added
+- **`/user:gsd-t-design-audit` command** — compare a built screen against a Figma design. Node-level Figma decomposition, per-widget comparison tables (10-30+ rows each), severity-rated deviations (CRITICAL/HIGH/MEDIUM/LOW), fidelity percentage. Writes zero code — report only. Usage: `/user:gsd-t-design-audit {Figma URL} {route}`.
+
+## [2.68.13] - 2026-04-05
+
+### Added (element-contract template)
+- **Chart-type-specific mandatory Visual Spec properties** — bar charts must now specify: `bar_width`, `bar_gap`, `bar_group_gap`, `corner_radius`, `label_position`, `label_min_width`, `segment_order`, `orientation`. Circular charts: `outer_diameter`, `inner_diameter`, `segment_order`, `start_angle`, `label_position`, `center_content`. Line/area: `stroke_width`, `point_radius`, `curve_type`, `fill_opacity`. Progress/gauge: `track_width`, `fill_width`, `track_color`. These are the exact properties that distinguish "matches the design" from "looks close."
+
+### Why
+BDS comparison showed bars with wrong width, wrong gap between groups, labels positioned outside instead of inside, wrong segment stacking order. The element contract's Visual Spec was free-form (`{dimension_1}`) — the agent could skip bar_width, segment_order, and label_position entirely. Chart-type-specific mandatory fields close this gap.
+
 ## [2.68.12] - 2026-04-05
 
 ### Fixed (design-chart-taxonomy template)

package/README.md

@@ -188,6 +188,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |
 | `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches | Manual |
 | `/user:gsd-t-audit` | Harness self-audit — analyze cost/benefit of enforcement components | Manual |
+| `/user:gsd-t-design-audit` | Compare built screen against Figma design — structured deviation report | Manual |
 
 ### Backlog Management
 

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

@@ -0,0 +1,202 @@
+# GSD-T: Design Audit — Compare Built Screen Against Figma Design
+
+You are the design audit agent. Your ONLY job is to compare an existing built screen against the original Figma design and produce a structured deviation report. You write ZERO code. You fix ZERO issues. You report what's wrong.
+
+**Input**: A Figma URL/file key + a running app URL or route path.
+**Output**: A markdown deviation report with per-widget comparison tables.
+
+---
+
+## Step 0: Parse Inputs
+
+Extract from `$ARGUMENTS`:
+- **Figma source**: file key, node ID, or full URL (e.g., `TFojdtYYss7J2qHscfRDRO`, `figma.com/design/...`)
+- **Built app target**: route path (e.g., `/analytics`), full URL (e.g., `http://localhost:5173/analytics`), or "current page"
+- **Scope** (optional): specific widget name or section to audit. Default: full page.
+
+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"
+
+## Step 1: Map the Figma Design — Node-Level Decomposition
+
+### 1a. Get the page tree
+
+Call `get_metadata` on the Figma page/frame to enumerate all child nodes. List every widget-level group:
+
+```
+Figma node tree:
+├── stat-card-campaign (id: 123:456)
+├── stat-card-visitors (id: 123:457)
+├── most-popular-tools-card (id: 123:458)
+├── ...
+```
+
+### 1b. Extract each widget node
+
+For EACH widget-level node, call `get_design_context` with the specific node ID. Record:
+- **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.
+
+### 1c. Classify each element using the taxonomy
+
+For each chart/visualization, walk the taxonomy decision tree (from `~/.claude/templates/design-chart-taxonomy.md`):
+
+```
+Widget: "Member Segmentation: State"
+  I SEE: Two groups of vertical bars, each group has 5 stacked colored segments
+         with percentage labels. Groups labeled "Members in Campaign" and
+         "Members Who Visited Page". Legend below with 5 state names.
+  CLASSIFICATION: chart-bar-stacked-vertical (two instances side-by-side)
+```
+
+## Step 2: Capture the Built Screen
+
+Open the built app at the target URL/route. For each widget identified in Step 1:
+
+1. Locate the corresponding element in the built page
+2. Record:
+   - What chart/element type was actually built?
+   - All visible text (titles, subtitles, labels, headers, legend items)
+   - Layout: alignment, spacing, sizing
+   - Colors: rendered values
+
+If the built page has widgets NOT in the Figma → flag as "EXTRA — not in design"
+If the Figma has widgets NOT in the built page → flag as "MISSING — not built"
+
+## Step 3: Per-Widget Comparison Table (MANDATORY)
+
+For each widget, produce a comparison table with **minimum 10 rows per widget** (30+ rows for complex widgets):
+
+```markdown
+### Widget: {name} — {Figma node ID}
+
+| # | Property | Figma | Built | Verdict |
+|---|----------|-------|-------|---------|
+| 1 | Chart type | chart-bar-stacked-vertical | chart-donut | ❌ CRITICAL |
+| 2 | Title text | "State" | "State" | ✅ MATCH |
+| 3 | Subtitle text | (none) | "By region" | ❌ HIGH — subtitle not in Figma |
+| 4 | Bar width | 32px | 64px | ❌ HIGH |
+| 5 | Bar group gap | 24px | 8px | ❌ HIGH |
+| 6 | Label position | inside-center | outside-right | ❌ HIGH |
+| 7 | Segment order (bottom→top) | [IL, NM, TX, OK, MT] | [NM, MT, OK, TX, IL] | ❌ MEDIUM |
+| 8 | Legend alignment | center | left | ❌ MEDIUM |
+| 9 | Legend items | NM, MT, OK, TX, IL | NM, MT, OK, TX, IL | ✅ MATCH |
+| 10 | Card padding | 16px | 24px | ❌ MEDIUM |
+```
+
+### Mandatory properties to check per widget:
+
+**Structure:**
+- Chart/element type (is it even the right kind of chart?)
+- Element count (right number of charts, legends, sub-components?)
+- Layout arrangement (side-by-side vs stacked, grid vs flex)
+
+**Text content:**
+- Title (exact text match)
+- Subtitle (present/absent + exact text)
+- Column headers / axis labels (exact text + order)
+- Legend items (exact text + order)
+- KPI values and labels
+- Footer text
+
+**Chart-specific (if applicable):**
+- Bar width, bar gap, bar group gap
+- Segment/slice order
+- Label position (inside/outside/above/below)
+- Corner radius on bars
+- Line stroke width, point radius
+- Donut inner/outer diameter, center content
+
+**Layout & spacing:**
+- Card padding (top, right, bottom, left)
+- Gap between title and body
+- Gap between chart and legend
+- Chart dimensions (width × height)
+- Legend alignment (left/center/right)
+- Element alignment within card (centered/left/stretch)
+
+**Colors:**
+- Segment/bar/slice fill colors (exact hex)
+- Text colors
+- Border colors
+- Background colors
+
+**Responsive (if mobile design exists):**
+- Mobile layout (stacked vs side-by-side)
+- Mobile font sizes
+- Mobile spacing changes
+
+### Verdict severity scale:
+
+| Severity | Meaning | Examples |
+|----------|---------|---------|
+| **CRITICAL** | Wrong element type or data model | Donut instead of stacked bar; wrong column headers; invented data |
+| **HIGH** | Wrong layout, sizing, or spacing that changes the visual meaning | Bar width 2× too wide; labels inside vs outside; elements missing |
+| **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 4: Summary Report
+
+After all widgets are audited, produce a summary:
+
+```markdown
+## Design Audit Summary
+
+**Page**: {page name}
+**Figma**: {file key / URL}
+**Built**: {route / URL}
+**Date**: {YYYY-MM-DD}
+
+### Overall Score
+
+| Severity | Count |
+|----------|-------|
+| CRITICAL | {N} |
+| HIGH     | {N} |
+| MEDIUM   | {N} |
+| LOW      | {N} |
+| MATCH    | {N} |
+
+**Fidelity**: {MATCH count} / {total rows} ({percentage}%)
+
+### Top Issues
+
+1. {Most impactful deviation — severity + widget + description}
+2. {Second most impactful}
+3. ...
+
+### Widgets Not in Figma (built but shouldn't exist)
+- {list or "None"}
+
+### Widgets Not Built (in Figma but missing)
+- {list or "None"}
+```
+
+## Step 5: Write Report
+
+Save the full report to `.gsd-t/design-audit-{page-name}-{YYYY-MM-DD}.md`
+
+Display the summary to the user inline.
+
+## Rules
+
+- **You write ZERO code.** Report only. Fixes are a separate step.
+- **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 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.
+
+---
+
+## Document Ripple
+
+- Append audit entry to `.gsd-t/progress.md` Decision Log:
+  `- {YYYY-MM-DD HH:MM}: gsd-t-design-audit — audited {page} against Figma {file key}. {N} CRITICAL, {N} HIGH, {N} MEDIUM, {N} LOW deviations. Fidelity: {N}%.`
+
+$ARGUMENTS

package/docs/GSD-T-README.md

@@ -129,6 +129,7 @@ GSD-T reads all state files and tells you exactly where you left off.
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |
 | `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches | Manual |
 | `/user:gsd-t-audit` | Harness self-audit — analyze cost/benefit of enforcement components | Manual |
+| `/user:gsd-t-design-audit` | Compare built screen against Figma — per-widget deviation report with severity | Manual |
 | `/global-change` | Apply file changes (copy/insert/update/delete) across all GSD-T projects | Manual |
 
 ### Backlog Management

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.68.12",
-  "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",
+  "version": "2.69.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",
   "repository": {

package/templates/CLAUDE-global.md

@@ -70,6 +70,7 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects |
 | `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches |
 | `/user:gsd-t-audit` | Harness self-audit — analyze cost/benefit of enforcement components |
+| `/user:gsd-t-design-audit` | Compare built screen against Figma design — structured deviation report |
 | `/user:gsd-t-backlog-add` | Capture item, auto-categorize, append to backlog |
 | `/user:gsd-t-backlog-list` | Filtered, ordered view of backlog items |
 | `/user:gsd-t-backlog-move` | Reorder items by position (priority) |

package/templates/element-contract.md

@@ -28,6 +28,49 @@ Atomic visual unit. One contract per visual variant (e.g., `chart-bar-stacked-ho
 
 *List every measurable visual property: dimensions, spacing, radii, borders, shadows, opacity. Reference design tokens rather than raw values where possible (`tokens.spacing.4` instead of `16px`).*
 
+### Chart-Type-Specific Mandatory Properties
+
+The free-form table above is necessary but not sufficient. For chart elements, the following properties are **MANDATORY** based on chart category — extract exact values from Figma MCP `get_design_context` or measure from the screenshot. Missing any of these is how "looks off" happens.
+
+**Bar charts** (`chart-bar-*`):
+| Property | Description | Example |
+|----------|-------------|---------|
+| `bar_width` | Width of each bar (px or % of available space) | `32px` / `60%` |
+| `bar_gap` | Gap between bars within a group (grouped only) | `4px` |
+| `bar_group_gap` | Gap between category groups | `24px` |
+| `corner_radius` | Rounding on bar ends (top for vertical, right for horizontal) | `4px top` / `0` |
+| `label_position` | Where percentage/value labels appear | `inside-center` / `outside-right` / `above` |
+| `label_min_width` | Minimum bar width to show label (hide if smaller) | `40px` |
+| `segment_order` | For stacked: order of series from bottom/left to top/right | `[NM, MT, OK, TX, IL]` |
+| `orientation` | Explicit confirmation of horizontal vs vertical | `vertical` |
+
+**Circular charts** (`chart-donut`, `chart-pie`, `chart-radial-bar`):
+| Property | Description | Example |
+|----------|-------------|---------|
+| `outer_diameter` | Total diameter of the chart | `180px` |
+| `inner_diameter` | Hole diameter (donut only, 0 for pie) | `100px` |
+| `segment_order` | Clockwise order of segments from 12 o'clock | `[Steps, Broker, Video, Quick, Plan]` |
+| `start_angle` | Where first segment starts | `12 o'clock (0°)` |
+| `label_position` | Where percentage labels appear | `outside-radial` / `inside-segment` / `none` |
+| `center_content` | What's displayed in the center hole (donut) | `"485" + "Total Interactions"` |
+
+**Line / area charts** (`chart-line-*`, `chart-area-*`):
+| Property | Description | Example |
+|----------|-------------|---------|
+| `stroke_width` | Line thickness | `2px` |
+| `point_radius` | Data point dot radius (0 = no dots) | `4px` |
+| `curve_type` | Linear, bezier, step | `linear` |
+| `fill_opacity` | For area charts: opacity of fill below line | `0.3` |
+
+**Progress / gauge** (`chart-progress-ring`, `chart-progress-bar`):
+| Property | Description | Example |
+|----------|-------------|---------|
+| `track_width` | Width of background track | `12px` |
+| `fill_width` | Width of progress fill (same as track or thinner) | `12px` |
+| `track_color` | Background track color | `#e2e8f0` |
+
+**If your element is a chart and you haven't filled the mandatory properties above, STOP. Go back to Figma and extract them.** These properties are the difference between a chart that "looks close" and one that matches.
+
 ## Labels / Text (if applicable)
 
 | Property      | Value                                                              |