Design Review

---
name: design-review
description: Audit an existing website or page for accessibility, responsive behaviour, performance and visual hierarchy, and return a score with ranked fixes. Use when asked to review a website, audit a page, check accessibility or WCAG issues, find out why a site looks wrong or feels slow, do a UX or design review, check if a site is mobile friendly, check Core Web Vitals, or someone says 'the site feels off but I can't say why'. For fixing the copy, see landing-page-copy. For the standards being audited against, see design-system-spec.
metadata:
  version: 1.0.0
---

# Design review

A review that lists forty problems gets ignored. This produces a **score, the
critical fixes, and the quick wins** — in that order — so the reader knows what to do
on Monday morning.

Two rules shape the whole thing. **Report, never fix**: the reviewer's job is to find
and rank, and applying changes without approval is how a review loses trust. And
**every finding names the element**, so nobody has to hunt for what you meant.

## Before you start

| Input | Why |
| --- | --- |
| The URL, or the HTML file | Step 1 needs something to parse |
| Which pages matter most | A whole-site audit nobody reads is worth less than three pages fixed |
| The brand's design system, if one exists | Lets you check consistency, not just correctness |
| Who the audience is | A dashboard for staff and a public landing page get judged differently |

If you only have a screenshot, say so. You can review hierarchy and layout from an
image, but not markup, contrast values, or performance — do not imply otherwise.

## Step 1 — Run the static audit

```bash
python3 scripts/audit_html.py page.html
python3 scripts/audit_html.py page.html --json
```

This catches the machine-checkable problems — missing `lang`, absent `alt`, skipped
heading levels, unlabelled inputs, blocked pinch-zoom, positive `tabindex`. Let the
script find those so your attention goes where judgement is needed.

**It reads markup only.** It cannot see rendered colour, layout, or speed. The
remaining steps are the parts it cannot do.

## Step 2 — Check contrast

Pull the actual text and background colours and check each pair. Do not judge by eye —
contrast is a computed ratio.

| Requirement | Ratio | WCAG |
| --- | --- | --- |
| Body text | 4.5:1 | SC 1.4.3, Level AA |
| Large text (24px+, or 18.5px+ bold) | 3:1 | SC 1.4.3, Level AA |
| Icons, borders, focus rings | 3:1 | SC 1.4.11, Level AA |

The usual offenders: grey placeholder text, light-grey captions, brand colour used
for body copy, and white text on a mid-tone brand background.

## Step 3 — Check responsive behaviour

Look at the page at **360px**, **768px** and **1280px** wide.

| Check | Failure looks like |
| --- | --- |
| Horizontal scroll at 360px | A fixed-width element, usually a table or image |
| Text reflows | Content cut off rather than wrapped |
| Touch targets ≥ 24×24 CSS px | Buttons and links too small or too close together |
| Tap targets not crowded | Two links so close a thumb hits both |
| Images scale | Overflow, or squashed aspect ratio |

360px is the important one. It is where most real phones sit, and where fixed widths
show up.

## Step 4 — Check performance against Core Web Vitals

Measured at the **75th percentile** of real page loads, not on your laptop.

| Metric | Good | Needs work | Poor |
| --- | --- | --- | --- |
| **LCP** — largest element painted | ≤ 2.5s | 2.5–4.0s | > 4.0s |
| **INP** — interaction to next paint | ≤ 200ms | 200–500ms | > 500ms |
| **CLS** — layout shift | ≤ 0.1 | 0.1–0.25 | > 0.25 |

INP replaced First Input Delay in 2024. If a report still quotes FID, it is out of
date.

The usual causes: an unoptimised hero image (LCP), heavy third-party scripts (INP),
and images or ads with no reserved dimensions (CLS).

If you cannot measure these, **say they were not measured**. Do not estimate them.

## Step 5 — Judge hierarchy and consistency

This is the part no script can do.

- **Squint test.** Blur the page. What stands out first? Is that what should?
- **One primary action per screen.** Three buttons of equal weight means no primary.
- **Consistency.** Do headings, buttons and spacing repeat, or is each section
  invented fresh? If a design system exists, check against it.
- **Line length.** 45–75 characters. Full-width body text on desktop is the common
  failure.
- **Spacing rhythm.** Related things close together, unrelated things apart.

## Step 6 — Score and rank

Sort by **what hurts most users first**, not by how easy it is to fix. Split into
critical (under 70 means it needs attention before anything else) and quick wins.

## Output

```
# Design review: <page>

## Score
<n>/100 — one sentence on the single biggest problem.

## Critical
Ranked. Each: what's wrong, the element, why it matters, the fix.
1. [contrast] Body text #999 on #fff is 2.85:1, needs 4.5:1
   Where: .card p
   Why:   unreadable for low-vision users; fails WCAG AA
   Fix:   darken to #595959 (7.0:1)

## Quick wins
Same shape, lower impact.

## Not measured
<Anything you could not check, and what it would need.>
```

## When it breaks

| What you see | What it means | The fix |
| --- | --- | --- |
| Script reports 100/100 but the page looks wrong | It checks markup, not rendered design | Steps 2–5 are the real review. The score is a floor, not a verdict |
| Everything is "critical" | Severity assigned by ease of fix, not user impact | Re-rank by how many users are blocked |
| Contrast passes but text is still hard to read | Ratio is fine; size, weight or line length is not | Check 16px minimum, line length 45–75 characters |
| Cannot measure Core Web Vitals | No field data, or only a local load | Report them as not measured. Never estimate |
| Only a screenshot available | No markup, no computed colour, no timing | Review hierarchy and layout only; state the limit explicitly |
| Client disputes a finding | The finding named a symptom, not the element | Every finding names the selector and the measured value |
| Review lists 40 issues, nothing changes | No ranking, so no starting point | Cut to the critical few; keep the rest as an appendix |
| Page passes every check but converts badly | Accessibility and design are not conversion | This skill audits build quality. Copy and offer are a separate job |

Never apply fixes as part of a review. Report, get approval, then change — a reviewer
who edits is a reviewer nobody asks back.

## Rules

- **Report, never auto-fix.** Findings and approval come before changes.
- **Name the element and the measured value** in every finding. "Contrast is bad" is
  not actionable; "`.card p` is 2.85:1, needs 4.5:1" is.
- **Rank by user impact, not by effort.** The easiest fix is rarely the most important.
- **Never estimate a metric you did not measure.** Say it was not measured.
- **Do not review what you cannot see.** From a screenshot, say so.
- **Under 70 is the critical threshold.** Below that, fix before adding anything new.
- A clean score is not a conformance claim. This audits common failures; it does not
  replace an audit by a qualified accessibility professional. Standards are external —
  see `SOURCES.md`.

## Related skills

- **design-system-spec** — the standards this audit measures against; build it first
  where none exists.
- **landing-page-copy** — when the page passes the build audit but converts badly.
- **answer-engine-optimisation** — the AEO pass for pages engines should quote.
- **ai-content-qc** — the content-truth gate; this skill audits the build.