gstack-design-review

UX principles from Steve Krug's "Don't Make Me Think."

Contract

This skill guarantees:

• Structured design audit with letter grades (A-F) across 10 categories
• AI Slop Score as standalone headline metric
• 6 usability tests on every page (Trunk Test, 3-Second Scan, Page Area Test, Happy Talk Detection, Mindless Choice Audit, Goodwill Reservoir)
• First-person narration mode (anti-slop: if you can't name the specific element, you're generating platitudes)
• Before/after screenshots for every fix
• One atomic commit per fix
• Findings sorted by impact (High > Medium > Polish)

Review modes and authority

Use surface mode for a screen, flow, or product and the six-phase rendered audit below. Use change mode when the target is uncommitted work, a branch, a commit range, or a pull request. A review request is read-only; run the Fix Loop only when the user also asks for implementation.

Change mode: review the affected interface

Resolve the change before judging it:

1. Determine the default branch and merge base before checking a dirty working tree. A stray edit must not hide a multi-commit branch. Include tracked, staged, and untracked files and report those counts separately. If the tree is clean and the branch has no commits ahead, check for an open pull request or an explicitly named ref. If neither identifies the target, stop and ask which commit, branch, pull request, or whole-repository surface to review; never silently substitute HEAD~1..HEAD.
2. Exclude lockfiles, snapshots, generated output, vendored code, and binaries, but name every exclusion. Keep the referencing code for changed fonts and images in scope.
3. Expand changed files to direct rendered consumers. Expand two hops only for tokens, themes, and shared primitives. Review at most five consumers, ordered by route/layout entry point, importer count, then package proximity; state how many were omitted.
4. Read both sides of every diff. Treat removed accessible names, native semantics, labels, focus treatments, reduced-motion rules, logical properties, language/direction metadata, wrapping, numeric alignment, color tokens, and explanatory copy as regression leads. Confirm an equivalent replacement is absent before reporting one.
5. Read the PR title/body, linked issue, and commit subjects. Check every promised variant, interaction state, translation, empty/loading/error state, narrow viewport, and sibling surface implied by that intent.

Classify each confirmed finding as Introduced, Regression, or Pre-existing. Only the first two affect the finding cap and verdict; pre-existing issues are reported separately, at most three, and never turn a clean change into a block. Source findings cite the reviewed ref, not whichever files happen to be checked out. Rendered claims require browser evidence; source-only claims must say Not visually verified.

For pull requests, fetch the head into refs/remotes/pr/<n> and inspect it with git show/git diff; never check it out over the author's tree. Rendered PR verification is opt-in and uses an isolated disposable worktree. Record every .git write (fetch, deepen, worktree) in Verification so the read-only claim is auditable.

UX Principles: How Users Actually Behave

The Three Laws of Usability

1. Don't make me think. Every page should be self-evident. If a user stops to think "What do I click?" — the design has failed.
2. Clicks don't matter, thinking does. Three mindless, unambiguous clicks beat one click that requires thought.
3. Omit, then omit again. Get rid of half the words on each page, then get rid of half of what's left. Happy talk must die. Instructions must die.

How Users Actually Behave

• Users scan, they don't read. Design for scanning: visual hierarchy, clearly defined areas, headings and bullet lists, highlighted key terms. We're designing billboards at 60 mph.
• Users satisfice. They pick the first reasonable option, not the best. Make the right choice the most visible choice.
• Users muddle through. They don't figure out how things work. They wing it.
• Users don't read instructions. Guidance must be brief, timely, and unavoidable.

Billboard Design for Interfaces

• Use conventions. Logo top-left, nav top/left, search = magnifying glass. Don't innovate on navigation to be clever.
• Visual hierarchy is everything. More important = more prominent. If everything shouts, nothing is heard.
• Make clickable things obviously clickable. No relying on hover states for discoverability.
• Eliminate noise. Fix noise by removal, not addition.
• Clarity trumps consistency.

Navigation as Wayfinding

Users on the web have no sense of scale, direction, or location. Navigation must always answer: What site is this? What page am I on? What are the major sections? What are my options at this level? Where am I? How can I search?

The Goodwill Reservoir

Users start with a reservoir of goodwill. Every friction point depletes it.

Deplete faster: Hiding info users want. Punishing users for not doing things your way. Asking for unnecessary information. Putting sizzle in their way. Unprofessional appearance.

Replenish: Know what users want and make it obvious. Tell them what they want to know upfront. Save them steps. Make it easy to recover from errors.

Phases

Phase 1: First Impression

Navigate to the target URL. Take a screenshot.

agent-browser snapshot <url> --output first-impression.png

Write the first impression in first-person narration mode:

• "The site communicates [what]."
• "I notice [observation]."
• "The first 3 things my eye goes to are: [1], [2], [3]."
• "If I had to describe this in one word: [word]."

Page Area Test: Point at each clearly defined area. Can you instantly name its purpose? Areas you can't name in 2 seconds are poorly defined.

Phase 2: Design System Extraction

Extract the actual design system rendered on the page (not what a config says):

• Fonts: list with usage counts. Flag if >3 distinct families.
• Colors: palette. Flag if >12 unique non-gray colors.
• Heading Scale: h1-h6 sizes. Flag skipped levels.
• Spacing Patterns: sample padding/margin values.

Phase 3: Page-by-Page Visual Audit

For each page in scope, run the Trunk Test:

1. What site is this? (Site ID visible)
2. What page am I on? (Page name prominent)
3. What are the major sections? (Nav visible and clear)
4. What are my options at this level? (Local nav obvious)
5. Where am I in the scheme of things? (Breadcrumbs, "you are here")
6. How can I search?

Score: PASS (all 6) / PARTIAL (4-5) / FAIL (3 or fewer). A FAIL is HIGH-impact.

Then apply the 10-Category Checklist (~80 items):

1. Visual Hierarchy & Composition (8 items) — focal point, eye flow, visual noise, information density, above-the-fold purpose, squint test, white space
2. Typography (15 items) — font count <=3, scale ratio, line-height, measure 45-75 chars, heading hierarchy, weight contrast, no blacklisted fonts, flag generic (Inter/Roboto), text-wrap balance, tabular-nums on number columns, body >=16px
3. Color & Contrast (10 items) — palette coherent <=12 colors, WCAG AA (4.5:1 body, 3:1 large), semantic consistency, no color-only encoding, dark mode elevation
4. Spacing & Layout (12 items) — grid consistent, 4/8px scale, alignment, rhythm, concentric border-radius, no horizontal scroll, max content width, safe-area-inset
5. Interaction States (10 items) — hover, focus-visible, active/pressed, disabled, loading skeletons, empty states, error messages, touch targets >=44px, mindless choice audit
6. Responsive Design (8 items) — mobile layout makes design sense, touch targets, no horizontal scroll, images responsive, text readable without zoom, nav collapses
7. Motion & Animation (6 items) — ease-out for entering / ease-in for exiting, 50-700ms duration, every animation communicates something, prefers-reduced-motion, no transition:all
8. Content & Microcopy (8 items) — empty states designed, error messages specific, button labels specific, no lorem ipsum, happy talk detection with word count, instructions detection
9. AI Slop Detection (10 anti-patterns) — purple gradients, 3-column feature grid, icons in colored circles, centered everything, uniform bubbly radius, decorative blobs, emoji as design, colored left-border cards, generic hero copy, cookie-cutter section rhythm
10. Performance as Design (6 items) — LCP <2.0s, CLS <0.1, skeleton quality, image optimization, font-display swap, no FOUT

Phase 4: Interaction Flow Review

Walk 2-3 key user flows in first-person narration mode.

Goodwill Reservoir tracking (start at 70/100):

• Hidden information: -15
• Format punishment: -10
• Unnecessary info requests: -10
• Interstitials blocking task: -15
• Sloppy appearance: -10
• Ambiguous choices requiring thought: -5 each
• Obvious top tasks: +10
• Upfront about costs: +5
• Saves steps: +5 each
• Graceful error recovery: +10

Report with visual dashboard. Below 30 = critical UX debt.

Phase 5: Cross-Page Consistency

Compare across pages: nav consistent? Footer consistent? Component reuse? Tone consistency? Spacing rhythm?

Phase 6: Compile Report

Dual headline scores:

• Design Score: A-F (weighted average of 10 categories)
• AI Slop Score: A-F (standalone)

Category weights: Visual Hierarchy 15%, Typography 15%, Spacing 15%, Color 10%, Interactions 10%, Responsive 10%, Content 10%, AI Slop 5%, Motion 5%, Performance 5%.

Grade computation: Start at A. Each High-impact finding drops one letter. Each Medium drops half a letter. Polish findings noted but don't affect grade.

Fix Loop

For each fixable finding, in impact order:

1. Locate source files
2. Make the minimal fix (CSS-first, smallest change)
3. One commit per fix: style(design): FINDING-NNN — short description
4. Re-test and take after screenshot
5. Classify: verified / best-effort / reverted / deferred

Hard cap: 30 fixes. After 30, stop regardless. Self-regulate every 5 fixes.

Anti-Patterns

• Generating platitudes instead of naming specific elements
• Fixing things without before/after screenshots
• Bundling multiple fixes into one commit
• Refactoring unrelated code while fixing design issues
• Evaluating source code instead of the rendered site
• Skipping the Trunk Test or Goodwill Reservoir tracking

Output Format

DESIGN AUDIT: {domain}
========================
Design Score: {A-F}
AI Slop Score: {A-F}

Pages audited: N
Findings: N (High: X, Medium: Y, Polish: Z)
Fixes applied: N (verified: X, best-effort: Y, reverted: Z)

Top 5 findings:
1. [HIGH] {finding} — {suggestion}
...

Goodwill: {score}/100
Quick Wins (3-5 highest-impact, <30min each):
1. {quick win}
...