@tekyzinc/gsd-t 2.68.13 → 2.69.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +10 -0
- package/README.md +1 -0
- package/commands/gsd-t-design-audit.md +241 -0
- package/docs/GSD-T-README.md +1 -0
- package/package.json +2 -2
- package/templates/CLAUDE-global.md +1 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to GSD-T are documented here. Updated with each release.
|
|
4
4
|
|
|
5
|
+
## [2.69.11] - 2026-04-05
|
|
6
|
+
|
|
7
|
+
### Changed (gsd-t-design-audit)
|
|
8
|
+
- **Auto-fix prompt** — after audit completes, if CRITICAL/HIGH deviations found, automatically prompts `/user:gsd-t-quick` with the audit report as source of truth. Re-runs audit after fixes to verify. Up to 2 fix cycles before stopping.
|
|
9
|
+
|
|
10
|
+
## [2.69.10] - 2026-04-05
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- **`/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}`.
|
|
14
|
+
|
|
5
15
|
## [2.68.13] - 2026-04-05
|
|
6
16
|
|
|
7
17
|
### Added (element-contract template)
|
package/README.md
CHANGED
|
@@ -188,6 +188,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
|
|
|
188
188
|
| `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |
|
|
189
189
|
| `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches | Manual |
|
|
190
190
|
| `/user:gsd-t-audit` | Harness self-audit — analyze cost/benefit of enforcement components | Manual |
|
|
191
|
+
| `/user:gsd-t-design-audit` | Compare built screen against Figma design — structured deviation report | Manual |
|
|
191
192
|
|
|
192
193
|
### Backlog Management
|
|
193
194
|
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
# GSD-T: Design Audit — Compare Built Screen Against Figma Design
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
**Input**: A Figma URL/file key + a running app URL or route path.
|
|
6
|
+
**Output**: A markdown deviation report with per-widget comparison tables.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Step 0: Parse Inputs
|
|
11
|
+
|
|
12
|
+
Extract from `$ARGUMENTS`:
|
|
13
|
+
- **Figma source**: file key, node ID, or full URL (e.g., `TFojdtYYss7J2qHscfRDRO`, `figma.com/design/...`)
|
|
14
|
+
- **Built app target**: route path (e.g., `/analytics`), full URL (e.g., `http://localhost:5173/analytics`), or "current page"
|
|
15
|
+
- **Scope** (optional): specific widget name or section to audit. Default: full page.
|
|
16
|
+
|
|
17
|
+
If Figma source is missing → ask user: "Provide the Figma file key or URL"
|
|
18
|
+
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"
|
|
19
|
+
|
|
20
|
+
## Step 1: Map the Figma Design — Node-Level Decomposition
|
|
21
|
+
|
|
22
|
+
### 1a. Get the page tree
|
|
23
|
+
|
|
24
|
+
Call `get_metadata` on the Figma page/frame to enumerate all child nodes. List every widget-level group:
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
Figma node tree:
|
|
28
|
+
├── stat-card-campaign (id: 123:456)
|
|
29
|
+
├── stat-card-visitors (id: 123:457)
|
|
30
|
+
├── most-popular-tools-card (id: 123:458)
|
|
31
|
+
├── ...
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### 1b. Extract each widget node
|
|
35
|
+
|
|
36
|
+
For EACH widget-level node, call `get_design_context` with the specific node ID. Record:
|
|
37
|
+
- **Chart/element type**: what visual pattern does this node contain?
|
|
38
|
+
- **All text content**: every title, subtitle, label, column header, legend item, KPI value, axis label
|
|
39
|
+
- **Layout properties**: alignment, spacing, sizing from the returned code/structure
|
|
40
|
+
- **Colors**: exact hex values for fills, strokes, text
|
|
41
|
+
|
|
42
|
+
> **⚠ Size guard**: Never call `get_design_context` on the full page frame. Always call on individual widget/card nodes.
|
|
43
|
+
|
|
44
|
+
### 1c. Classify each element using the taxonomy
|
|
45
|
+
|
|
46
|
+
For each chart/visualization, walk the taxonomy decision tree (from `~/.claude/templates/design-chart-taxonomy.md`):
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
Widget: "Member Segmentation: State"
|
|
50
|
+
I SEE: Two groups of vertical bars, each group has 5 stacked colored segments
|
|
51
|
+
with percentage labels. Groups labeled "Members in Campaign" and
|
|
52
|
+
"Members Who Visited Page". Legend below with 5 state names.
|
|
53
|
+
CLASSIFICATION: chart-bar-stacked-vertical (two instances side-by-side)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Step 2: Capture the Built Screen
|
|
57
|
+
|
|
58
|
+
Open the built app at the target URL/route. For each widget identified in Step 1:
|
|
59
|
+
|
|
60
|
+
1. Locate the corresponding element in the built page
|
|
61
|
+
2. Record:
|
|
62
|
+
- What chart/element type was actually built?
|
|
63
|
+
- All visible text (titles, subtitles, labels, headers, legend items)
|
|
64
|
+
- Layout: alignment, spacing, sizing
|
|
65
|
+
- Colors: rendered values
|
|
66
|
+
|
|
67
|
+
If the built page has widgets NOT in the Figma → flag as "EXTRA — not in design"
|
|
68
|
+
If the Figma has widgets NOT in the built page → flag as "MISSING — not built"
|
|
69
|
+
|
|
70
|
+
## Step 3: Per-Widget Comparison Table (MANDATORY)
|
|
71
|
+
|
|
72
|
+
For each widget, produce a comparison table with **minimum 10 rows per widget** (30+ rows for complex widgets):
|
|
73
|
+
|
|
74
|
+
```markdown
|
|
75
|
+
### Widget: {name} — {Figma node ID}
|
|
76
|
+
|
|
77
|
+
| # | Property | Figma | Built | Verdict |
|
|
78
|
+
|---|----------|-------|-------|---------|
|
|
79
|
+
| 1 | Chart type | chart-bar-stacked-vertical | chart-donut | ❌ CRITICAL |
|
|
80
|
+
| 2 | Title text | "State" | "State" | ✅ MATCH |
|
|
81
|
+
| 3 | Subtitle text | (none) | "By region" | ❌ HIGH — subtitle not in Figma |
|
|
82
|
+
| 4 | Bar width | 32px | 64px | ❌ HIGH |
|
|
83
|
+
| 5 | Bar group gap | 24px | 8px | ❌ HIGH |
|
|
84
|
+
| 6 | Label position | inside-center | outside-right | ❌ HIGH |
|
|
85
|
+
| 7 | Segment order (bottom→top) | [IL, NM, TX, OK, MT] | [NM, MT, OK, TX, IL] | ❌ MEDIUM |
|
|
86
|
+
| 8 | Legend alignment | center | left | ❌ MEDIUM |
|
|
87
|
+
| 9 | Legend items | NM, MT, OK, TX, IL | NM, MT, OK, TX, IL | ✅ MATCH |
|
|
88
|
+
| 10 | Card padding | 16px | 24px | ❌ MEDIUM |
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Mandatory properties to check per widget:
|
|
92
|
+
|
|
93
|
+
**Structure:**
|
|
94
|
+
- Chart/element type (is it even the right kind of chart?)
|
|
95
|
+
- Element count (right number of charts, legends, sub-components?)
|
|
96
|
+
- Layout arrangement (side-by-side vs stacked, grid vs flex)
|
|
97
|
+
|
|
98
|
+
**Text content:**
|
|
99
|
+
- Title (exact text match)
|
|
100
|
+
- Subtitle (present/absent + exact text)
|
|
101
|
+
- Column headers / axis labels (exact text + order)
|
|
102
|
+
- Legend items (exact text + order)
|
|
103
|
+
- KPI values and labels
|
|
104
|
+
- Footer text
|
|
105
|
+
|
|
106
|
+
**Chart-specific (if applicable):**
|
|
107
|
+
- Bar width, bar gap, bar group gap
|
|
108
|
+
- Segment/slice order
|
|
109
|
+
- Label position (inside/outside/above/below)
|
|
110
|
+
- Corner radius on bars
|
|
111
|
+
- Line stroke width, point radius
|
|
112
|
+
- Donut inner/outer diameter, center content
|
|
113
|
+
|
|
114
|
+
**Layout & spacing:**
|
|
115
|
+
- Card padding (top, right, bottom, left)
|
|
116
|
+
- Gap between title and body
|
|
117
|
+
- Gap between chart and legend
|
|
118
|
+
- Chart dimensions (width × height)
|
|
119
|
+
- Legend alignment (left/center/right)
|
|
120
|
+
- Element alignment within card (centered/left/stretch)
|
|
121
|
+
|
|
122
|
+
**Colors:**
|
|
123
|
+
- Segment/bar/slice fill colors (exact hex)
|
|
124
|
+
- Text colors
|
|
125
|
+
- Border colors
|
|
126
|
+
- Background colors
|
|
127
|
+
|
|
128
|
+
**Responsive (if mobile design exists):**
|
|
129
|
+
- Mobile layout (stacked vs side-by-side)
|
|
130
|
+
- Mobile font sizes
|
|
131
|
+
- Mobile spacing changes
|
|
132
|
+
|
|
133
|
+
### Verdict severity scale:
|
|
134
|
+
|
|
135
|
+
| Severity | Meaning | Examples |
|
|
136
|
+
|----------|---------|---------|
|
|
137
|
+
| **CRITICAL** | Wrong element type or data model | Donut instead of stacked bar; wrong column headers; invented data |
|
|
138
|
+
| **HIGH** | Wrong layout, sizing, or spacing that changes the visual meaning | Bar width 2× too wide; labels inside vs outside; elements missing |
|
|
139
|
+
| **MEDIUM** | Wrong alignment, color, or order that looks incorrect but doesn't change meaning | Legend left instead of center; segment order reversed; wrong shade |
|
|
140
|
+
| **LOW** | Minor sizing or spacing that's barely noticeable | 2px padding difference; slight font-size mismatch |
|
|
141
|
+
|
|
142
|
+
## Step 4: Summary Report
|
|
143
|
+
|
|
144
|
+
After all widgets are audited, produce a summary:
|
|
145
|
+
|
|
146
|
+
```markdown
|
|
147
|
+
## Design Audit Summary
|
|
148
|
+
|
|
149
|
+
**Page**: {page name}
|
|
150
|
+
**Figma**: {file key / URL}
|
|
151
|
+
**Built**: {route / URL}
|
|
152
|
+
**Date**: {YYYY-MM-DD}
|
|
153
|
+
|
|
154
|
+
### Overall Score
|
|
155
|
+
|
|
156
|
+
| Severity | Count |
|
|
157
|
+
|----------|-------|
|
|
158
|
+
| CRITICAL | {N} |
|
|
159
|
+
| HIGH | {N} |
|
|
160
|
+
| MEDIUM | {N} |
|
|
161
|
+
| LOW | {N} |
|
|
162
|
+
| MATCH | {N} |
|
|
163
|
+
|
|
164
|
+
**Fidelity**: {MATCH count} / {total rows} ({percentage}%)
|
|
165
|
+
|
|
166
|
+
### Top Issues
|
|
167
|
+
|
|
168
|
+
1. {Most impactful deviation — severity + widget + description}
|
|
169
|
+
2. {Second most impactful}
|
|
170
|
+
3. ...
|
|
171
|
+
|
|
172
|
+
### Widgets Not in Figma (built but shouldn't exist)
|
|
173
|
+
- {list or "None"}
|
|
174
|
+
|
|
175
|
+
### Widgets Not Built (in Figma but missing)
|
|
176
|
+
- {list or "None"}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Step 5: Write Report
|
|
180
|
+
|
|
181
|
+
Save the full report to `.gsd-t/design-audit-{page-name}-{YYYY-MM-DD}.md`
|
|
182
|
+
|
|
183
|
+
Display the summary to the user inline.
|
|
184
|
+
|
|
185
|
+
## Step 6: Fix Prompt (auto-triggered if deviations found)
|
|
186
|
+
|
|
187
|
+
If ANY CRITICAL or HIGH deviations were found, automatically prompt the fix workflow:
|
|
188
|
+
|
|
189
|
+
```
|
|
190
|
+
───────────────────────────────────────────────────────────────
|
|
191
|
+
|
|
192
|
+
## ▶ Fix Deviations
|
|
193
|
+
|
|
194
|
+
**{N} CRITICAL + {N} HIGH deviations found.** Fix them now?
|
|
195
|
+
|
|
196
|
+
The audit report at `.gsd-t/design-audit-{page-name}-{YYYY-MM-DD}.md`
|
|
197
|
+
has the exact Figma values for each deviation.
|
|
198
|
+
|
|
199
|
+
`/user:gsd-t-quick fix all CRITICAL and HIGH deviations from .gsd-t/design-audit-{page-name}-{YYYY-MM-DD}.md — use the Figma values in the report as the source of truth`
|
|
200
|
+
|
|
201
|
+
───────────────────────────────────────────────────────────────
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
If ONLY MEDIUM or LOW deviations remain, show:
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
───────────────────────────────────────────────────────────────
|
|
208
|
+
|
|
209
|
+
## ▶ Polish (optional)
|
|
210
|
+
|
|
211
|
+
**{N} MEDIUM + {N} LOW deviations.** These are minor — fix if you want pixel-perfect.
|
|
212
|
+
|
|
213
|
+
`/user:gsd-t-quick fix MEDIUM and LOW deviations from .gsd-t/design-audit-{page-name}-{YYYY-MM-DD}.md`
|
|
214
|
+
|
|
215
|
+
───────────────────────────────────────────────────────────────
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
If ZERO deviations → display "✅ Pixel-perfect. No fixes needed."
|
|
219
|
+
|
|
220
|
+
After fixes are applied, **re-run the audit automatically** to verify. Loop until:
|
|
221
|
+
- All CRITICAL and HIGH are resolved, OR
|
|
222
|
+
- 2 fix cycles have been attempted (then stop and present remaining deviations to user)
|
|
223
|
+
|
|
224
|
+
## Rules
|
|
225
|
+
|
|
226
|
+
- **You write ZERO code during the audit phase (Steps 1-5).** Report only. Code changes happen in Step 6 via `/user:gsd-t-quick`.
|
|
227
|
+
- **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.
|
|
228
|
+
- **You do NOT skip widgets.** Every widget in the Figma AND every widget in the build gets audited.
|
|
229
|
+
- **You call `get_design_context` per widget node.** Do not classify from a page-level screenshot.
|
|
230
|
+
- **You walk the taxonomy decision tree** for every chart element — document your reasoning.
|
|
231
|
+
- **Minimum 10 rows per widget, 30+ for complex widgets.** Fewer rows means you skipped properties.
|
|
232
|
+
- **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.
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## Document Ripple
|
|
237
|
+
|
|
238
|
+
- Append audit entry to `.gsd-t/progress.md` Decision Log:
|
|
239
|
+
`- {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}%.`
|
|
240
|
+
|
|
241
|
+
$ARGUMENTS
|
package/docs/GSD-T-README.md
CHANGED
|
@@ -129,6 +129,7 @@ GSD-T reads all state files and tells you exactly where you left off.
|
|
|
129
129
|
| `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects | Manual |
|
|
130
130
|
| `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches | Manual |
|
|
131
131
|
| `/user:gsd-t-audit` | Harness self-audit — analyze cost/benefit of enforcement components | Manual |
|
|
132
|
+
| `/user:gsd-t-design-audit` | Compare built screen against Figma — per-widget deviation report with severity | Manual |
|
|
132
133
|
| `/global-change` | Apply file changes (copy/insert/update/delete) across all GSD-T projects | Manual |
|
|
133
134
|
|
|
134
135
|
### Backlog Management
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tekyzinc/gsd-t",
|
|
3
|
-
"version": "2.
|
|
4
|
-
"description": "GSD-T: Contract-Driven Development for Claude Code —
|
|
3
|
+
"version": "2.69.11",
|
|
4
|
+
"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",
|
|
5
5
|
"author": "Tekyz, Inc.",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"repository": {
|
|
@@ -70,6 +70,7 @@ PROJECT or FEATURE or SCAN
|
|
|
70
70
|
| `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects |
|
|
71
71
|
| `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches |
|
|
72
72
|
| `/user:gsd-t-audit` | Harness self-audit — analyze cost/benefit of enforcement components |
|
|
73
|
+
| `/user:gsd-t-design-audit` | Compare built screen against Figma design — structured deviation report |
|
|
73
74
|
| `/user:gsd-t-backlog-add` | Capture item, auto-categorize, append to backlog |
|
|
74
75
|
| `/user:gsd-t-backlog-list` | Filtered, ordered view of backlog items |
|
|
75
76
|
| `/user:gsd-t-backlog-move` | Reorder items by position (priority) |
|