From 9cf92177b874404348b4efb31d81670d70b5d28d Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Thu, 26 Mar 2026 23:26:11 -0600 Subject: [PATCH] feat: gstack designer target mockups in /design-review fix loop MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add $D generate for target mockups in Phase 8a.5 — before fixing a design finding, generate a mockup showing what it should look like. Add $D verify in Phase 9 to compare fix results against targets. Not plan mode — goes straight to implementation. Co-Authored-By: Claude Opus 4.6 (1M context) --- design-review/SKILL.md | 51 +++++++++++++++++++++++++++++++++++-- design-review/SKILL.md.tmpl | 27 ++++++++++++++++++-- 2 files changed, 74 insertions(+), 4 deletions(-) diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 17f29e38..588e87ca 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -549,6 +549,38 @@ Only commit if there are changes. Stage all bootstrap files (config, test direct --- +**Find the gstack designer (optional — enables target mockup generation):** + +## DESIGN SETUP (run this check BEFORE any design mockup command) + +```bash +_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) +D="" +[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/design/dist/design" ] && D="$_ROOT/.claude/skills/gstack/design/dist/design" +[ -z "$D" ] && D=~/.claude/skills/gstack/design/dist/design +if [ -x "$D" ]; then + echo "DESIGN_READY: $D" +else + echo "DESIGN_NOT_AVAILABLE" +fi +``` + +If `DESIGN_NOT_AVAILABLE`: skip visual mockup generation and fall back to the +existing HTML wireframe approach (`DESIGN_SKETCH`). Design mockups are a +progressive enhancement, not a hard requirement. + +If `DESIGN_READY`: the design binary is available for visual mockup generation. +Commands: +- `$D generate --brief "..." --output /path.png` — generate a single mockup +- `$D variants --brief "..." --count 3 --output-dir /path/` — generate N style variants +- `$D compare --images "a.png,b.png,c.png" --output /path/board.html` — comparison board +- `$D check --image /path.png --brief "..."` — vision quality gate +- `$D iterate --session /path/session.json --feedback "..." --output /path.png` — iterate + +If `DESIGN_READY`: during the fix loop, you can generate "target mockups" showing what a finding should look like after fixing. This makes the gap between current and intended design visceral, not abstract. + +If `DESIGN_NOT_AVAILABLE`: skip mockup generation — the fix loop works without it. + **Create output directories:** ```bash @@ -976,6 +1008,7 @@ Record baseline design score and AI slop score at end of Phase 6. │ ├── {page}-tablet.png │ ├── {page}-desktop.png │ ├── finding-001-before.png # Before fix +│ ├── finding-001-target.png # Target mockup (if generated) │ ├── finding-001-after.png # After fix │ └── ... └── design-baseline.json # For regression mode @@ -1091,10 +1124,23 @@ For each fixable finding, in impact order: - ONLY modify files directly related to the finding - Prefer CSS/styling changes over structural component changes +### 8a.5. Target Mockup (if DESIGN_READY) + +If the gstack designer is available and the finding involves visual layout, hierarchy, or spacing (not just a CSS value fix like wrong color or font-size), generate a target mockup showing what the corrected version should look like: + +```bash +$D generate --brief "" --output "$REPORT_DIR/screenshots/finding-NNN-target.png" +``` + +Show the user: "Here's the current state (screenshot) and here's what it should look like (mockup). Now I'll fix the source to match." + +This step is optional — skip for trivial CSS fixes (wrong hex color, missing padding value). Use it for findings where the intended design isn't obvious from the description alone. + ### 8b. Fix - Read the source code, understand the context - Make the **minimal fix** — smallest change that resolves the design issue +- If a target mockup was generated in 8a.5, use it as the visual reference for the fix - CSS-only changes are preferred (safer, more reversible) - Do NOT refactor surrounding code, add features, or "improve" unrelated things @@ -1164,8 +1210,9 @@ DESIGN-FIX RISK: After all fixes are applied: 1. Re-run the design audit on all affected pages -2. Compute final design score and AI slop score -3. **If final scores are WORSE than baseline:** WARN prominently — something regressed +2. If target mockups were generated during the fix loop AND `DESIGN_READY`: run `$D verify --mockup "$REPORT_DIR/screenshots/finding-NNN-target.png" --screenshot "$REPORT_DIR/screenshots/finding-NNN-after.png"` to compare the fix result against the target. Include pass/fail in the report. +3. Compute final design score and AI slop score +4. **If final scores are WORSE than baseline:** WARN prominently — something regressed --- diff --git a/design-review/SKILL.md.tmpl b/design-review/SKILL.md.tmpl index bb169142..abfd2bc7 100644 --- a/design-review/SKILL.md.tmpl +++ b/design-review/SKILL.md.tmpl @@ -78,6 +78,14 @@ After the user chooses, execute their choice (commit or stash), then continue wi {{TEST_BOOTSTRAP}} +**Find the gstack designer (optional — enables target mockup generation):** + +{{DESIGN_SETUP}} + +If `DESIGN_READY`: during the fix loop, you can generate "target mockups" showing what a finding should look like after fixing. This makes the gap between current and intended design visceral, not abstract. + +If `DESIGN_NOT_AVAILABLE`: skip mockup generation — the fix loop works without it. + **Create output directories:** ```bash @@ -109,6 +117,7 @@ Record baseline design score and AI slop score at end of Phase 6. │ ├── {page}-tablet.png │ ├── {page}-desktop.png │ ├── finding-001-before.png # Before fix +│ ├── finding-001-target.png # Target mockup (if generated) │ ├── finding-001-after.png # After fix │ └── ... └── design-baseline.json # For regression mode @@ -145,10 +154,23 @@ For each fixable finding, in impact order: - ONLY modify files directly related to the finding - Prefer CSS/styling changes over structural component changes +### 8a.5. Target Mockup (if DESIGN_READY) + +If the gstack designer is available and the finding involves visual layout, hierarchy, or spacing (not just a CSS value fix like wrong color or font-size), generate a target mockup showing what the corrected version should look like: + +```bash +$D generate --brief "" --output "$REPORT_DIR/screenshots/finding-NNN-target.png" +``` + +Show the user: "Here's the current state (screenshot) and here's what it should look like (mockup). Now I'll fix the source to match." + +This step is optional — skip for trivial CSS fixes (wrong hex color, missing padding value). Use it for findings where the intended design isn't obvious from the description alone. + ### 8b. Fix - Read the source code, understand the context - Make the **minimal fix** — smallest change that resolves the design issue +- If a target mockup was generated in 8a.5, use it as the visual reference for the fix - CSS-only changes are preferred (safer, more reversible) - Do NOT refactor surrounding code, add features, or "improve" unrelated things @@ -218,8 +240,9 @@ DESIGN-FIX RISK: After all fixes are applied: 1. Re-run the design audit on all affected pages -2. Compute final design score and AI slop score -3. **If final scores are WORSE than baseline:** WARN prominently — something regressed +2. If target mockups were generated during the fix loop AND `DESIGN_READY`: run `$D verify --mockup "$REPORT_DIR/screenshots/finding-NNN-target.png" --screenshot "$REPORT_DIR/screenshots/finding-NNN-after.png"` to compare the fix result against the target. Include pass/fail in the report. +3. Compute final design score and AI slop score +4. **If final scores are WORSE than baseline:** WARN prominently — something regressed ---