/web-design-review

name: web-design-review
description: 'Use when the user runs /web-design-review with a URL to visually audit and fix a live UI. Not for design direction: use design. Not for variant galleries: use design-variants.'

Web design review

Contract

| Field | Bound contract | |---|---| | Trigger | the user runs `/web-design-review` with a URL | | Authority | Reversible local: writes only source-file edits and a local design findings report; rollback is version control. No remote mutation. One atomic commit per fix. | | Side effect | writes a web-design-audit report directory with screenshots and applies minimal source fixes | | Done | the design fix-and-verify loop has completed: every fixable finding fixed, re-tested, and classified, with final scores computed |

Inputs

• A target URL for the live UI to audit (required). If absent, ask the user for one.
• An optional mode flag: `--quick` (homepage plus 2 key pages), `--deep` (audit only pages affected by the current branch diff), or `--regression` (compare against a prior `web-design-baseline.json`). Default is full: 5-8 pages reachable from the homepage.
• A repo with source for the UI (required for the fix loop). If the URL is a remote site with no local source, run audit-only: report findings, skip the fix loop, mark every finding deferred.
• An optional `DESIGN.md` or `design-system.md` in the repo root. If present, calibrate every finding against it; deviations from the stated system are higher severity.

Procedure

1. Create a report directory `web-design-audit-<YYYYMMDD>/screenshots/`. **Done when:** the report directory and screenshots subfolder exist.

2. Navigate to the target URL in the browser. Take a full-page desktop screenshot. Capture responsive screenshots at mobile 375, tablet 768, desktop 1024, and wide 1440. Capture console errors and performance metrics (LCP, CLS). Read each screenshot file back so it is visible inline; screenshots are evidence, not background. **Done when:** desktop plus four responsive screenshots, console errors, and LCP/CLS are captured and read back inline.

3. Form a First Impression before analyzing anything: state what the site communicates at a glance, what stands out, the first three elements the eye lands on (hierarchy check against designer intent), and a one-word gut verdict. **Done when:** the four First Impression fields are stated.

4. Extract the Inferred Design System: fonts with usage counts (flag more than 3 families), color palette (flag more than 12 unique non-gray colors), heading scale h1-h6 (flag skipped levels and non-systematic jumps), spacing patterns (flag non-scale values). **Done when:** fonts, palette, heading scale, and spacing are extracted with their flags applied.

5. Run the Trunk Test on every page: dropped on the page with no context, answer what site this is, what page is shown, what the key tasks are, where to start, whether oriented, and what the primary action is. Score PASS (6 clear) / PARTIAL (4-5) / FAIL (3 or fewer). A FAIL is a HIGH-impact finding regardless of visual polish. **Done when:** every page carries a Trunk Test score.

6. During audit, evaluate the rendered site only, not source code. Apply the 10-category Design Audit Checklist on each page. Document each finding in the report as it is found, not in a batch. Prefer 5-10 findings with screenshots and specific suggestions over 20 vague observations. Each finding gets an impact rating (high / medium / polish) and a category:

• Visual Hierarchy & Composition: clear focal point, one primary CTA per view, natural eye flow, squint test, intentional white space.
• Typography: font count 3 or fewer, scale ratio, line-height, measure 45-75 chars, no skipped heading levels, body 16px or larger, tabular-nums on number columns, generic-font flag (Inter/Roboto/Open Sans/Poppins as primary).
• Color & Contrast: coherent palette, WCAG AA (body 4.5:1, large 3:1), no color-only encoding, dark mode uses elevation not lightness inversion, no red/green-only combinations.
• Spacing & Layout: consistent grid, spacing scale on a 4px or 8px base, border-radius hierarchy, inner radius equals outer minus gap, no horizontal scroll, breakpoints at 375/768/1024/1440.
• Interaction States: hover, focus-visible ring (never bare outline:none), active/pressed, disabled, loading skeletons matching content layout, warm empty states, specific error messages with a next step, touch targets 44px or larger, mindless-choice audit (every click obvious without thought).
• Responsive Design: mobile layout makes design sense (not stacked desktop columns), no horizontal scroll, navigation collapses, no user-scalable=no.
• Motion & Animation: easing direction (ease-out enter, ease-in exit), duration 50-700ms, purpose per animation, prefers-reduced-motion respected, only transform and opacity animated.
• Content & Microcopy: specific button labels, no lorem ipsum, truncation handled, active voice, loading states end with the ellipsis character, destructive actions confirmed, happy-talk and over-long-instructions detection.
• AI Slop Detection: purple/violet/indigo gradients, the 3-column icon-in-circle feature grid, centered everything, uniform bubbly radius, decorative blobs, emoji as design elements, colored left-border cards, generic hero copy, cookie-cutter section rhythm, system-ui as primary font.
• Performance as Design: LCP under 2.0s (apps) or 1.5s (informational), CLS under 0.1, lazy images with dimensions, font-display swap, no visible font-swap flash.

**Done when:** every page's findings are recorded, each with id, impact, category, screenshot, and specific suggestion; a defect-free page records zero findings with its screenshots as evidence.

7. Walk 2-3 key user flows and evaluate feel as well as function: response, transition quality, feedback clarity, form polish. Maintain a Goodwill Reservoir starting at 70/100. Subtract for hidden information (-15), format punishment (-10