Preface

When using AI coding tools like Cursor, Claude Code, or Codex to write frontend code, the speed is fast, but common issues on the page often come along too: icon buttons without aria-label, interactive elements with focus rings removed, animations without considering prefers-reduced-motion, forms missing labels, images without explicit width and height causing layout shifts. Many “seemingly usable” interfaces have obvious gaps when checked against accessibility, touch, and performance rules.

The web-design-guidelines maintained by Vercel Labs is exactly the Agent Skill for this problem. It does not teach you how to design interfaces, but when you say “help me review the UI / check accessibility”, it will audit the code according to Vercel’s Web Interface Guidelines and provide directly jumpable file:line results. The guidelines themselves are stored in a remote repository and pulled again before each audit, so the rules are always up to date with the upstream.

This article explains what it is, what checks it covers, how to install and enable it, and how to use it in daily work.

What It Is

web-design-guidelines is part of the official vercel-labs/agent-skills skill set, credited to Vercel, with a current metadata version of 1.0.0. It follows the universal Agent Skills (SKILL.md) format and can be installed via the skills CLI into AI coding tools that support this standard, such as Cursor, Claude Code, or Codex.

One-sentence positioning: Conduct compliance checks related to accessibility, UX, and performance on specified UI code according to the Vercel Web Interface Guidelines.

The official repository describes it as: Review UI code against web interface best practices, covering over 100 rules. Trigger scenarios include:

  • Review my UI
  • Check accessibility
  • Audit design
  • Review UX
  • Check my site against best practices

The full guideline text is not hardcoded in the Skill directory, but the latest content is pulled from the following address before each audit:

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

Core Features and Check Scope

The Skill’s workflow is straightforward, as written in the official SKILL.md in four steps:

  1. Pull the latest guidelines from the above URL
  2. Read user-specified files (or path patterns); if not specified, confirm with the user first
  3. Check all rules in the guidelines one by one
  4. Output findings in the concise format required by the guidelines

The guidelines are grouped by theme, with the main categories aligned to the repository README including:

  • Accessibility: aria-label for icon buttons, form labels, keyboard handling, semantic HTML, aria-live, etc.
  • Focus States: Visible focus, :focus-visible, prohibiting removal of outline without a replacement
  • Forms: autocomplete / name, correct type and inputmode, clickable labels, error prompts and submission states
  • Animation: Respect prefers-reduced-motion, prefer animating transform / opacity, avoid transition: all
  • Typography: Ellipsis, curly quotes, tabular numerals (equal width for numbers) and other typographic details
  • Images: Explicit width and height, above-the-fold and lazy loading strategies, alt text
  • Performance: Virtualization for long lists, avoiding reading layout during the render phase, fonts and preconnections, etc.
  • Navigation & State: URL reflecting state, using links for navigation, dangerous operations requiring confirmation or undoability
  • Touch & Interaction / Safe Areas / Dark Mode / Locale / Hydration and other rules related to mobile, theme, internationalization, and hydration safety

The output requires high signal-to-noise ratio: group by file, use editor-clickable file:line formats, point out the problem and its location, and avoid long explanations unless necessary. The official example format is roughly as follows:

## src/Button.tsx

src/Button.tsx:42 - icon button missing aria-label
src/Button.tsx:18 - input lacks label
src/Button.tsx:55 - animation missing prefers-reduced-motion
src/Button.tsx:67 - transition: all → list properties

## src/Card.tsx

✓ pass

This format is ideal for a “mine sweep” before a PR or after AI bulk UI changes, turning vague “design intuition” into actionable code locations.

Installation and Enablement

This Skill is released as part of vercel-labs/agent-skills. When installing only this single skill, you can use the skills CLI (official documentation and the skills.sh page both provide similar commands):

npx skills add vercel-labs/agent-skills --skill web-design-guidelines

You can also use the full GitHub address:

npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines

Or directly point to the Skill directory:

npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines

If you want to install all skills in this repository at once:

npx skills add vercel-labs/agent-skills

Common options (refer to the skills CLI documentation):

  • -g / --global: Install to the user directory, available across projects
  • -y: Skip confirmation, suitable for CI
  • --list: Only list the available Skills in the repository without installing

After installation, the Agent will automatically select it when the task matches the Skill description. Vercel’s documentation states that the skills CLI can connect to multiple Agents including Claude Code, GitHub Copilot, Cursor, Cline, etc.; the specific installation directory varies by tool (for example, project-level common paths include .cursor/skills/, .claude/skills/, .agents/skills/, etc.), please refer to the current tool’s documentation and CLI prompts.

Typical Usage

After installation, you don’t need to memorize the command name, just trigger it with natural language. The official recommended phrases include:

Review my UI

Check accessibility

Audit design for src/components/**

Review UX on the settings page components

Check my site against best practices

A more reliable approach is to include a file or directory to reduce the need for the Agent to ask follow-up questions:

Use web-design-guidelines to review the button and form components under app/components, list issues in file:line format

Check src/Modal.tsx against the Web Interface Guidelines, focusing on focus, scroll locking, and reduced-motion

According to the Skill convention, the Agent should first pull the latest command.md, then read the files you specified, and finally output according to the specifications. If you do not provide a path, it will first ask which files to audit.

After the audit is completed, it is recommended to treat the results as a checklist: prioritize fixing high-impact items such as accessibility and focus, forms, and dangerous operation confirmations, then handle typography and copy details. You can run the audit again after modifying the same component to confirm if it turns to ✓ pass.

Applicable Scenarios and Notes

It is particularly suitable for these scenarios:

  • A batch of UI code just generated or heavily modified by AI, needing a quick screening for common compliance issues
  • Conducting accessibility and UX self-checks, but not yet having a complete design system / lint rules in place
  • Letting the Agent scan files according to a unified checklist before Code Review, so humans can focus on business logic
  • Aligning the team’s review caliber with Vercel’s publicly available Web Interface Guidelines

A few notes when using it:

  1. Depends on internet access to pull the specification. Each audit requires access to the raw content of web-interface-guidelines; when offline or with limited network access, the rules may not be obtained or may not be the latest version.
  2. It is an audit process, not a magic tool that fixes all problems automatically. The output focuses on “pointing out problems”, and the specific modification methods still need to be combined with the component library and product constraints.
  3. The rules are focused on web frontend interfaces. The coverage is wide, but it will not replace complete security audits, visual design reviews, or business acceptance tests.
  4. Refer to the official source materials. The Skill’s behavior is subject to the SKILL.md in the repository and the remote command.md; if third-party reprints conflict with the official version, please refer to the original GitHub text.

Summary

web-design-guidelines turns Vercel’s Web Interface Guidelines into an automatically triggerable Agent audit workflow: pull the latest rules first, then output high-signal-to-noise file:line findings grouped by file. For teams that often use AI to write UI code and worry about accessibility and interaction details being overlooked, it is a low-cost, clear-alignment supplementary process.

Official links:

  • Skill directory: https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
  • Skill set repository: https://github.com/vercel-labs/agent-skills
  • Directory page: https://skills.sh/vercel-labs/agent-skills/web-design-guidelines
  • Specification source: https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md