# web-design-guidelines

> A Claude Code skill from Vercel Labs that audits UI code against 100+ best practices spanning accessibility, performance, responsive design, and user experience — produces a prioritized findings list ordered by user impact.

**Use case**: Audit UI code against modern web design and accessibility standards

**Canonical URL**: https://agentcookbooks.com/skills/web-design-guidelines/

**Topics**: claude-code, skills, design, accessibility, performance

**Trigger phrases**: "audit this UI", "check web design guidelines", "run a design audit on this page"

**Source**: [Vercel Labs](https://github.com/vercel-labs/agent-skills/tree/main/web-design-guidelines)

**License**: MIT

---

## What it does

`web-design-guidelines` is the broadest of Vercel Labs' code-audit skills. Where [`react-best-practices`](/skills/react-best-practices/) is React-specific, this one covers any web UI: HTML, CSS, accessibility, performance, responsive design, dark-mode handling, and UX patterns.

100+ rules, organized into themes, prioritized by which ones actually affect users. The output is a structured audit report you can act on, not a wall of lint warnings.

## When to use it

- Pre-launch audit of a landing page, checkout flow, or marketing site
- Reviewing a PR that touches UI in any framework (works on plain HTML too — useful when `react-best-practices` doesn't apply)
- Onboarding into a UI codebase you've never seen
- Compliance pass — accessibility audit before a regulated launch

When *not* to reach for it:

- Pure logic or backend code — the rules don't apply
- Component-level work where you want React-specific feedback — use `react-best-practices` instead
- A page where you've already done a recent audit; running again on same surface produces noise

## Install

From the [Vercel Labs agent-skills repo](https://github.com/vercel-labs/agent-skills). Follow the SKILL.md install pattern documented there.

Stack-agnostic — works on React, Vue, Svelte, plain HTML, server-rendered templates.

## What a session looks like

1. **You point the skill at a UI file, component, or page.**
2. **It runs 100+ checks** spanning accessibility (semantic HTML, ARIA, keyboard nav, contrast), performance (image strategies, font loading, layout shift), responsive design (breakpoints, fluid typography), UX (loading states, error handling, empty states).
3. **Findings are grouped by theme** (a11y / perf / responsive / UX) and prioritized inside each by *user impact*.
4. **Each finding includes the why and a fix pattern.**

The discipline: framework-agnostic. The skill doesn't care whether it's looking at a Server Component or a `<div>` — it cares whether a user with a screen reader can use it.

## Receipts

**Where it works well:**
- Catches accessibility regressions reliably — the area where most teams skip review
- Surfaces image-loading mistakes (missing dimensions, no priority hints) that hurt LCP
- The "any framework" coverage means you can use it on a project where `react-best-practices` doesn't apply

**Where it backfires:**
- 100+ rules means more noise than `react-best-practices`. Filter ruthlessly to the prioritized top items
- On a heavily-customized design system, some rules flag intentional choices as violations. Treat findings as signal, not law
- Doesn't replace a real accessibility audit by an actual user with a screen reader. Catches patterns; doesn't catch lived experience

**Pattern that works:** run it before launch on the critical-path pages (landing, checkout, signup, dashboard) — the surfaces where regressions cost the most. Skip on internal admin tools.

## Source and attribution

From the [Vercel Labs agent-skills repository](https://github.com/vercel-labs/agent-skills/tree/main/web-design-guidelines). Maintained by Vercel Labs.

License: MIT. Install, adapt, redistribute with attribution.