What you can’t see
The app opens, it navigates, in a screenshot it looks finished. Underneath there’s what nobody notices by eye: keyboard focus, contrast, targets big enough for a thumb, image weight, heading order, Core Web Vitals. Accessibility and web performance are two whole crafts of their own — and neither you nor the agent has the whole of either in your head.
Two skills bring that expertise into Claude Code. One is maintained by Vercel Labs; the other is by Addy Osmani, of the Google Chrome team, who packaged what he knows about site quality into it. Once installed, the agent has the measuring stick it was missing.
web-design-guidelines by Vercel Labs The interface rules: visible focus, targets big enough to tap, contrast, loading states, animations that respect people who’ve turned them off.
web-quality-audit by Addy Osmani, Google Chrome team Lighthouse’s measuring stick: performance and Core Web Vitals, accessibility per WCAG, SEO, best practices. Looks at the whole project, not a single screen.
Install the two skills
They install inside the project folder: run the command from there, with Claude Code open on the app.
One single command: it installs both. Once per project.
Run npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines and then npx skills add addyosmani/web-quality-skills The round in three prompts
First: the interface report. It only analyzes, it doesn’t fix.
Use the web-design-guidelines skill on the interface files (src/app and src/components).
Just give me the report, don't change anything:
1. one line per problem, in the format file:line
2. sorted by severity: first the ones that stop the app from being usable, then the rest
3. next to each line, one sentence on what happens to whoever's using the app
What comes back is a list of lines like src/components/swipe-card.tsx:42 with the problem next to it. You don’t need to open those files: the number is for the agent, for when you tell it to fix things.
Second: the quality report. Same deal, different yardstick: weight, speed, accessibility, SEO.
Use the web-quality-audit skill on the whole project.
Just give me the report, don't change anything. For each of the four areas
(performance, accessibility, SEO, best practices) give me five problems at
most: the ones you'd actually notice on a phone with a slow connection.
For each one: file:line, what happens to whoever's using the app, and how
much it costs to fix (small / medium / large).Third: fix it in batches. Never «fix everything»: one batch at a time, with your go-ahead in between.
Take the report and work in batches.
Batch 1: only the highest-severity problems. For each one tell me what
you're about to change BEFORE changing it, then do it, then stop and wait
for my go-ahead before batch 2.
Don't touch anything that isn't on the list, and don't fix anything else
along the way.After each batch, reopen the app and look at it. Two batches are almost always enough. After that all that’s left is putting it online: that’s part 7.