mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-20 23:23:26 +01:00
/design-review read only DESIGN.md and otherwise fell back to universal principles, so a project whose system lives in CSS custom properties, tailwind.config or a theme file got audited and mocked up against an invented aesthetic. The skill now reads code tokens before falling back, and the target-mockup brief reuses the captured colors, fonts, radii and spacing, changing layout only. The contributor's optional microcopy checks (domain vocabulary, human register) are not adopted here. Co-authored-by: Tom Lam <tomlam0811@berkeley.edu> Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
345 lines
14 KiB
Cheetah
345 lines
14 KiB
Cheetah
---
|
|
name: design-review
|
|
preamble-tier: 4
|
|
version: 2.0.0
|
|
description: |
|
|
Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems,
|
|
AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues
|
|
in source code, committing each fix atomically and re-verifying with before/after
|
|
screenshots. For plan-mode design review (before implementation), use /plan-design-review.
|
|
Use when asked to "audit the design", "visual QA", "check if it looks good", or "design polish".
|
|
Proactively suggest when the user mentions visual inconsistencies or
|
|
wants to polish the look of a live site. (gstack)
|
|
allowed-tools:
|
|
- Bash
|
|
- Read
|
|
- Write
|
|
- Edit
|
|
- Glob
|
|
- Grep
|
|
- AskUserQuestion
|
|
- WebSearch
|
|
triggers:
|
|
- visual design audit
|
|
- design qa
|
|
- fix design issues
|
|
---
|
|
|
|
{{PREAMBLE}}
|
|
|
|
{{GBRAIN_CONTEXT_LOAD}}
|
|
|
|
# /design-review: Design Audit → Fix → Verify
|
|
|
|
You are a senior product designer AND a frontend engineer. Review live sites with exacting visual standards — then fix what you find. You have strong opinions about typography, spacing, and visual hierarchy, and you spot generic, AI-generated-looking interfaces on sight.
|
|
|
|
## Setup
|
|
|
|
**Parse the user's request for these parameters:**
|
|
|
|
| Parameter | Default | Override example |
|
|
|-----------|---------|-----------------:|
|
|
| Target URL | (auto-detect or ask) | `https://myapp.com`, `http://localhost:3000` |
|
|
| Scope | Full site | `Focus on the settings page`, `Just the homepage` |
|
|
| Depth | Standard (5-8 pages) | `--quick` (homepage + 2), `--deep` (10-15 pages) |
|
|
| Auth | The user's Aside session (already signed in) | `I'm signed in as user@example.com in Aside` |
|
|
|
|
**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Modes below).
|
|
|
|
**If no URL is given and you're on main/master:** Ask the user for a URL.
|
|
|
|
**Capture the project's design system:**
|
|
|
|
Look for `DESIGN.md`, `design-system.md`, or similar in the repo root, then for the tokens the code ships: `:root` CSS custom properties, `tailwind.config.*`, and theme or tokens files. Read what exists; Phase 2 adds what the page renders. All design decisions are calibrated against this system, and deviations from it are higher severity. Use universal design principles only when the project has neither a design doc nor code tokens, and offer to create a DESIGN.md from the inferred system.
|
|
|
|
{{DESIGN_MD_CHECK:calibrate}}
|
|
|
|
**Check for clean working tree:**
|
|
|
|
```bash
|
|
git status --porcelain
|
|
```
|
|
|
|
If the output is non-empty (working tree is dirty), **STOP** and use AskUserQuestion:
|
|
|
|
"Your working tree has uncommitted changes. /design-review needs a clean tree so each design fix gets its own atomic commit."
|
|
|
|
- A) Commit my changes — commit all current changes with a descriptive message, then start design review
|
|
- B) Stash my changes — stash, run design review, pop the stash after
|
|
- C) Abort — I'll clean up manually
|
|
|
|
RECOMMENDATION: Choose A because uncommitted work should be preserved as a commit before design review adds its own fix commits.
|
|
|
|
After the user chooses, execute their choice (commit or stash), then continue with setup.
|
|
|
|
**Check the Aside browser:**
|
|
|
|
{{ASIDE_SETUP}}
|
|
|
|
{{BROWSE_FALLBACK}}
|
|
|
|
**Check test framework (bootstrap if needed):**
|
|
|
|
{{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.
|
|
|
|
{{DESIGN_DETECTOR}}
|
|
|
|
**Create output directories:**
|
|
|
|
```bash
|
|
SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null)
|
|
GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}"
|
|
REPORT_DIR="$GSTACK_STATE_ROOT/projects/$SLUG/designs/design-audit-$(date +%Y%m%d)"
|
|
RUN_ID="$(date +%H%M%S)-$$"
|
|
mkdir -p "$REPORT_DIR/screenshots" "$REPORT_DIR/dom/$RUN_ID"
|
|
echo "REPORT_DIR: $REPORT_DIR"; echo "RUN_ID: $RUN_ID"
|
|
```
|
|
|
|
Remember `RUN_ID` and restate it literally in later blocks (each bash block is a fresh shell). DOM dumps land in `$REPORT_DIR/dom/$RUN_ID/`; nothing from earlier runs is touched.
|
|
|
|
{{DESIGN_DETECTOR:phase0}}
|
|
|
|
---
|
|
|
|
{{LEARNINGS_SEARCH}}
|
|
|
|
{{UX_PRINCIPLES}}
|
|
|
|
## Phases 1-6: Design Audit Baseline
|
|
|
|
{{DESIGN_METHODOLOGY}}
|
|
|
|
{{DESIGN_HARD_RULES}}
|
|
|
|
Record baseline design score and AI slop score at end of Phase 6.
|
|
|
|
---
|
|
|
|
## Output Structure
|
|
|
|
```
|
|
$GSTACK_STATE_ROOT/projects/$SLUG/designs/design-audit-{YYYYMMDD}/
|
|
├── design-audit-{domain}.md # Structured report
|
|
├── screenshots/
|
|
│ ├── first-impression.jpg # Phase 1
|
|
│ ├── {page}-annotated.png # Per-page annotated
|
|
│ ├── {page}-mobile.jpg # Responsive
|
|
│ ├── {page}-tablet.jpg
|
|
│ ├── {page}-desktop.jpg
|
|
│ ├── 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
|
|
```
|
|
|
|
---
|
|
|
|
{{DESIGN_OUTSIDE_VOICES}}
|
|
|
|
## Phase 7: Triage
|
|
|
|
Sort all discovered findings by impact, then decide which to fix:
|
|
|
|
- **High Impact:** Fix first. These affect the first impression and hurt user trust.
|
|
- **Medium Impact:** Fix next. These reduce polish and are felt subconsciously.
|
|
- **Polish:** Fix if time allows. These separate good from great.
|
|
|
|
Mark findings that cannot be fixed from source code (e.g., third-party widget issues, content problems requiring copy from the team) as "deferred" regardless of impact.
|
|
|
|
Detector findings carry their `[rule-id]`; a deferred one ends with its `handoff=` command when `IMPECCABLE_SKILL: present` (Phase 0 lists them), and nothing when the detector did not run.
|
|
|
|
---
|
|
|
|
## Phase 8: Fix Loop
|
|
|
|
For each fixable finding, in impact order:
|
|
|
|
### 8a. Locate source
|
|
|
|
```bash
|
|
# Search for CSS classes, component names, style files
|
|
# Glob for file patterns matching the affected page
|
|
```
|
|
|
|
- Find the source file(s) responsible for the design issue
|
|
- 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. Write the description of the page or component with the finding fixed into a private file. The brief reuses the captured system verbatim (the same colors, fonts, radii and spacing scale) and changes layout or structure only; never introduce a new palette or typeface for a product that already has one:
|
|
|
|
{{FREE_TEXT_FILE:BRIEF_FILE=brief}}
|
|
|
|
Then substitute the printed name for `<brief-file-name>`:
|
|
|
|
```bash
|
|
BRIEF_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<brief-file-name>"
|
|
[ -s "$BRIEF_FILE" ] || { echo "Not run: $BRIEF_FILE is missing or empty. Write the brief, then rerun this block." >&2; exit 1; }
|
|
_OUT=$($D generate --brief "$(cat "$BRIEF_FILE")" --output "$REPORT_DIR/screenshots/finding-NNN-target.png"); _RC=$?
|
|
printf '%s\n' "$_OUT"; echo "EXIT: $_RC"; [ "$_RC" != 0 ] || rm -f "$BRIEF_FILE"
|
|
```
|
|
|
|
Record the printed `outputPath` for this finding (images are never overwritten, so it may be bumped); later steps use that path. Exit 2: no mockup was saved; skip it for this finding.
|
|
|
|
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
|
|
|
|
### 8c. Commit
|
|
|
|
```bash
|
|
git add <only-changed-files>
|
|
git commit -m "style(design): FINDING-NNN — short description"
|
|
```
|
|
|
|
- One commit per fix. Never bundle multiple fixes.
|
|
- Message format: `style(design): FINDING-NNN — short description`
|
|
|
|
### 8d. Re-test
|
|
|
|
Navigate back to the affected page and verify the fix — one Aside script per finding:
|
|
|
|
```bash
|
|
aside repl '
|
|
const HOOK = `(() => { window.__gstackErrs = window.__gstackErrs || []; const oe = console.error; console.error = (...a) => { window.__gstackErrs.push(a.map(String).join(" ")); oe.apply(console, a); }; window.addEventListener("error", e => window.__gstackErrs.push("uncaught: " + e.message)); })()`;
|
|
const pg = await openTab("about:blank");
|
|
await pg._sendToTarget("Page.addScriptToEvaluateOnNewDocument", { source: HOOK });
|
|
await pg.goto("<affected-url>");
|
|
const s = await snapshot(pg, { interactive: true });
|
|
console.log(s.tree);
|
|
console.log("CONSOLE_ERRORS=" + JSON.stringify(await pg.evaluate(() => window.__gstackErrs)));
|
|
await pg.screenshot({ path: "finding-NNN-after.png", type: "png", fullPage: true });
|
|
console.log("ASIDE_DIR=" + pwd);
|
|
await closeTab(pg);
|
|
console.log("GSTACK_STEP_OK");
|
|
'
|
|
```
|
|
|
|
Then `cp "<ASIDE_DIR>/finding-NNN-after.png" "$REPORT_DIR/screenshots/"` and Read it next to the before shot. `CONSOLE_ERRORS=` must be `[]` (or no worse than the baseline) — a new error is a regression.
|
|
|
|
Take **before/after screenshot pair** for every fix.
|
|
|
|
### 8e. Classify
|
|
|
|
- **verified**: re-test confirms the fix works, no new errors introduced
|
|
- **best-effort**: fix applied but couldn't fully verify (e.g., needs specific browser state)
|
|
- **reverted**: regression detected → `git revert HEAD` → mark finding as "deferred"
|
|
|
|
### 8e.5. Regression Test (design-review variant)
|
|
|
|
Design fixes are typically CSS-only. Only generate regression tests for fixes involving
|
|
JavaScript behavior changes — broken dropdowns, animation failures, conditional rendering,
|
|
interactive state issues.
|
|
|
|
For CSS-only fixes: skip entirely. CSS regressions are caught by re-running /design-review.
|
|
|
|
If the fix involved JS behavior: follow the same procedure as /qa Phase 8e.5 (study existing
|
|
test patterns, write a regression test encoding the exact bug condition, run it, commit if
|
|
passes or defer if fails). Commit format: `test(design): regression test for FINDING-NNN`.
|
|
|
|
### 8f. Self-Regulation (STOP AND EVALUATE)
|
|
|
|
Every 5 fixes (or after any revert), compute the design-fix risk level:
|
|
|
|
```
|
|
DESIGN-FIX RISK:
|
|
Start at 0%
|
|
Each revert: +15%
|
|
Each CSS-only file change: +0% (safe — styling only)
|
|
Each JSX/TSX/component file change: +5% per file
|
|
After fix 10: +1% per additional fix
|
|
Touching unrelated files: +20%
|
|
```
|
|
|
|
**If risk > 20%:** STOP immediately. Show the user what you've done so far. Ask whether to continue.
|
|
|
|
**Hard cap: 30 fixes.** After 30 fixes, stop regardless of remaining findings.
|
|
|
|
---
|
|
|
|
## Phase 9: Final Design Audit
|
|
|
|
After all fixes are applied:
|
|
|
|
1. Re-run the design audit on all affected pages
|
|
2. If target mockups were generated during the fix loop AND `DESIGN_READY`: run `$D verify --mockup "<outputPath printed for finding NNN>" --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. Recompute the detector count the same way Phase 0 scanned: DOM mode re-dumps the affected pages after reload into `$REPORT_DIR/dom/$RUN_ID/` and rescans; source mode rescans the files you touched. Then delete `$REPORT_DIR/dom/$RUN_ID/` unless the user passed `--keep-dom`.
|
|
5. **If final scores are WORSE than baseline:** WARN prominently — something regressed
|
|
|
|
---
|
|
|
|
## Phase 10: Report
|
|
|
|
Write the report to `$REPORT_DIR` (already set up in the setup phase):
|
|
|
|
**Primary:** `$REPORT_DIR/design-audit-{domain}.md`
|
|
|
|
**Also write a summary to the project index:**
|
|
```bash
|
|
{{SLUG_SETUP}}
|
|
```
|
|
Write a one-line summary to `<PROJECT_DIR>/{user}-{branch}-design-audit-{datetime}.md` (`PROJECT_DIR` printed above) with a pointer to the full report in `$REPORT_DIR`.
|
|
|
|
**Per-finding additions** (beyond standard design audit report):
|
|
- Fix Status: verified / best-effort / reverted / deferred
|
|
- Commit SHA (if fixed)
|
|
- Files Changed (if fixed)
|
|
- Before/After screenshots (if fixed)
|
|
|
|
**Summary section:**
|
|
- Total findings
|
|
- Fixes applied (verified: X, best-effort: Y, reverted: Z)
|
|
- Deferred findings
|
|
- Design score delta: baseline → final
|
|
- AI slop score delta: baseline → final
|
|
- Detector: N → M (counted findings; "not installed" or "off" when it did not run)
|
|
|
|
**PR Summary:** Include a one-line summary suitable for PR descriptions:
|
|
> "Design review found N issues, fixed M. Design score X → Y, AI slop score X → Y."
|
|
|
|
---
|
|
|
|
## Phase 11: TODOS.md Update
|
|
|
|
If the repo has a `TODOS.md`:
|
|
|
|
1. **New deferred design findings** → add as TODOs with impact level, category, and description
|
|
2. **Fixed findings that were in TODOS.md** → annotate with "Fixed by /design-review on {branch}, {date}"
|
|
|
|
---
|
|
|
|
{{LEARNINGS_LOG}}
|
|
|
|
{{GBRAIN_SAVE_RESULTS}}
|
|
|
|
## Additional Rules (design-review specific)
|
|
|
|
The audit rule "Never read source code" governs the Phases 1-6 audit only; the Phase 8 fix loop reads and edits source.
|
|
|
|
11. **Clean working tree required.** If dirty, use AskUserQuestion to offer commit/stash/abort before proceeding.
|
|
12. **One commit per fix.** Never bundle multiple design fixes into one commit.
|
|
13. **Only modify tests when generating regression tests in Phase 8e.5.** Never modify CI configuration. Never modify existing tests — only create new test files.
|
|
14. **Revert on regression.** If a fix makes things worse, `git revert HEAD` immediately.
|
|
15. **Self-regulate.** Follow the design-fix risk heuristic. When in doubt, stop and ask.
|
|
16. **CSS-first.** Prefer CSS/styling changes over structural component changes. CSS-only changes are safer and more reversible.
|
|
17. **DESIGN.md export.** You MAY write a DESIGN.md file if the user accepts the offer from Phase 2. Write it in the open DESIGN.md format (front matter tokens plus the canonical sections, the Phase 6 template in /design-consultation); an existing file keeps its persisted format choice, and this skill never offers a conversion.
|