Web Design Guidelines

tl;dr: this skill is a two-step fetch-and-audit: pull the rule set from a raw GitHub URL every run (so the rules are never stale), then walk the user’s files against all of them. Output is the rule set’s own terse file:line format, not a custom report. ~100 rules across 11 categories — accessibility, focus, forms, animation, typography, images, performance, navigation, theming, touch, i18n.

What it actually does

SKILL.md (version 1.0.0, author vercel, 2026-09-09) is short on purpose. The rules live in a separate repo and get fetched fresh on every invocation:

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

The skill’s own job is to:

1. WebFetch that URL.
2. Read the files or pattern the user passed (or ask which files to review if none was given).
3. Apply all rules from the fetched guidelines.
4. Output findings in the format the fetched guidelines specify (the skill does not define its own — command.md does).

The fetched command.md is the source of truth for both the rules and the output shape. If SKILL.md and command.md ever drift, the live fetch wins. The skill never embeds the rules locally — that’s the point.

Rule categories (from the upstream README)

The 100+ rules split into 11 areas:

• Accessibility — aria-labels, semantic HTML, keyboard handlers
• Focus States — visible focus, focus-visible patterns
• Forms — autocomplete, validation, error handling
• Animation — prefers-reduced-motion, compositor-friendly transforms
• Typography — curly quotes, ellipsis, tabular-nums
• Images — dimensions, lazy loading, alt text
• Performance — virtualization, layout thrashing, preconnect
• Navigation & State — URL reflects state, deep-linking
• Dark Mode & Theming — color-scheme, theme-color meta
• Touch & Interaction — touch-action, tap-highlight
• Locale & i18n — Intl.DateTimeFormat, Intl.NumberFormat

This list is the README summary. The actual rules — including the output format — come from the live fetch.

Usage contract

When a user provides a file or pattern as the skill argument:

1. Fetch guidelines from https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md.
2. Read the specified files.
3. Apply all rules from the fetched guidelines.
4. Output findings using the format specified in the guidelines.

If no files are specified, ask the user which files to review. The skill does not auto-discover or auto-expand scope.

Install

# installs the whole vercel-labs/agent-skills pack (includes this skill)
npx skills add vercel-labs/agent-skills

The README documents npx skills add vercel-labs/agent-skills as the install command. To install this skill alone:

git clone https://github.com/vercel-labs/agent-skills
# Claude Code / Cursor pick up SKILL.md from:
#   ~/.claude/skills/web-design-guidelines/SKILL.md
#   .claude/skills/web-design-guidelines/SKILL.md

Unlike the heavier skills in the same pack (e.g. vercel-optimize, vercel-deploy-to-vercel), this one ships only SKILL.md — no scripts/, no references/. The rules live in the upstream repo and are pulled at audit time.

Gotchas

• The rules live outside the skill. If vercel-labs/web-interface-guidelines is unreachable, the skill has nothing to audit against. Don’t try to substitute the README summary above — it’s a category index, not the rule set.
• Output format comes from command.md, not from SKILL.md. The skill is explicit: “Output findings using the format specified in the guidelines.” Agents that invent their own report shape (markdown headings, severity buckets) are not following the contract.
• Network on every run. The skill fetches fresh guidelines every invocation. That is by design — it means the rule set is never stale, but it also means the host needs outbound network access at audit time. A sandboxed host without it cannot run this skill.
• No file argument = ask. The skill does not auto-pick files. Agents that try to “helpfully” expand a directory glob against the whole repo violate the contract.
• Sibling skill: writing-guidelines. Same author, same repo. Different domain — writing-guidelines audits prose and docs against the Vercel writing handbook (80+ rules). Don’t conflate the two; one is UI, one is copy.
• Not a generator. Like refactoring-ui-audit, this skill critiques an existing surface. If the user wants net-new UI, route to frontend-design or vercel-composition-patterns instead.
• sandbox_test.verdict: untested — we read SKILL.md and the README; we did not run an audit against real files.

Related: Refactoring UI Audit — same shelf, also a UI audit; pair them when you want both a Refactoring UI pass and a Web Interface Guidelines pass on the same component; Vercel Composition Patterns — same shelf, design-before-audit workflow pair; frontend-design — same shelf, for net-new UI generation rather than review; UI Skills catalog — broader routing index for UI jobs.