Design Audit

---
name: design-audit
description: Look at a UI the way a person would and report what is visibly wrong, then measure it to get numbers and selectors. Starts from a screenshot (the user's, or one taken in a real browser), then runs a CSS probe for the defects the eye cannot resolve (contrast ratios, near-duplicate token drift, sub-pixel seams, off-scale spacing, mismatched nested radii, invisible surfaces and borders, missing focus rings). Use whenever UI was just built or changed, before a PR that touches UI, when the user pastes a screenshot of something that looks off, or says "design audit", "audit this page", "does this look right", "check the UI", "why does this look off", "review the design", or "polish this page". Prefer this over reviewing UI from source, because source review cannot see rendered output.
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---

# Design Audit

Most bad UI is caught by looking at it for five seconds. Nobody looked.

So: **look first, measure second.** In that order, always. The measurement pass exists to put numbers on what you already saw, to find the selector that causes it, and to catch the narrow set of defects the eye genuinely cannot resolve. It does not exist to discover the problem for you. If you find yourself grepping class names before you have looked at a picture, stop.

## Rule 1: if there is a screenshot, that is the audit

When the user pastes an image, **the image is the target**. Read it and report what you see, immediately, before any tooling. Do not go find the repo. Do not go find the URL. Do not start a dev server. The user is showing you a rendering because the rendering is the evidence, and they can already see the problem, so the slow path adds nothing but a chance to audit the wrong thing.

Only reach for the browser after you have given the visual read, and only for what the picture cannot answer: exact values, the selector to change, other states, other pages.

## Rule 2: audit the thing the user is looking at

A screenshot carries a page, a viewport width, and a **scroll position**. All three change what renders. A sticky header at `scrollY=0` is a different component than the same header scrolled. If you open a browser, reproduce the state in the picture and confirm it matches before you believe any number.

Check that you are even on the right page. Compare nav items, headings, and visible copy against the screenshot. Two pages that share a component are not the same page, and a finding from the wrong one is worthless even when it happens to be true.

## Step 0: prerequisite

`audit.sh` needs [agent-browser](https://github.com/vercel-labs/agent-browser) on PATH:

```bash
npm install -g agent-browser && agent-browser install
```

It falls back to `npx -y agent-browser` when there is no global install, and honours `AGENT_BROWSER` to point at a specific binary. Nothing else is required. Every capture comes out of the browser, so there is no ImageMagick or `sips` dependency, and it behaves identically on macOS, Linux and WSL.

Then find the URL: check for a running dev server (`lsof -iTCP -sTCP:LISTEN -P -n | grep -E '3000|5173|4000|8080'`), otherwise start one, otherwise use a `file://` path. Ask the user only if you cannot find it.

Output lands in `.design-audit/` **relative to wherever you invoke the script**, so run it from the project root. Add `.design-audit/` to that repo's `.gitignore`. Override the location with `DA_OUT` if you want it elsewhere.

## Step 1: look, at three scales

If the user gave you an image, read it. Otherwise take your own.

**Stay in the project you are auditing and call the script by its path.** Output goes to `.design-audit/` in the current directory, so the audit lands with the code it describes. Set `SKILL` once: