web-design-guidelines

⚠️ Performance Tip: This Skill contains the complete WCAG 2.2 checklist. For a quick review, you can use only the "Quick Checklist"; for a full audit, use the "Detailed Checklist".

Web Interface Guidelines & Accessibility Checker

Overview

This Skill provides two review modes:

Quick Review: An instant check based on the Vercel Web Interface Guidelines
Full Audit: A comprehensive compliance check based on the WCAG 2.2 AA standards

Quick Review (Web Interface Guidelines)

Workflow

Fetch the latest guidelines from the source URL:

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

Read the specified file (or prompt the user to provide a file/pattern)
Check against the fetched rules
Output results using the concise file:line format

Usage

When the user provides a file or pattern parameter:

Fetch the guidelines from the above URL
Read the specified file
Apply all rules
Output results in the format specified in the guidelines

If no file is specified, ask the user which files to review.

Full Audit (WCAG 2.2 AA)

New WCAG 2.2 Success Criteria

WCAG 2.2 adds 9 new success criteria on top of 2.1:

2.4.11 Focus Appearance (Minimum) - AA

Requirements: The focus indicator must meet all of the following conditions:

Contrast: at least 3:1 (focus vs. adjacent colors)
Area: the indicator area is at least equal to the area of a 1 CSS pixel ring
Not obscured by other content

Checkpoints：

All interactive elements (links, buttons, input fields) have a visible focus state
Focus indicator contrast ≥ 3:1
Focus styles are not obscured by other content

/* ✅ 合规的焦点样式 */
:focus {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

/* ✅ 高对比度焦点 */
:focus {
  outline: 3px solid #000000;
  background: #ffff00;
}

2.4.12 Focus Not Obscured (Minimum) - AA

Requirements: The focus indicator must not be completely obscured by other content

Checkpoints：

Fixed elements (header, nav) do not obscure focus
The focused element is visible when a modal is open
The focused element stays within the viewport when scrolling

2.5.7 Dragging Movements - AA

Requirements: All functionality that uses a dragging operation should provide a single-pointer alternative

Checkpoints：

Sliders have +/- buttons as an alternative to dragging
Drag-and-drop lists have up/down buttons as an alternative to dragging
Dragging operations have clear visual feedback

// ❌ 不合规：只有拖动
<SortableList items={items} />

// ✅ 合规：提供替代方案
<SortableList items={items} />
<SortableList items={items} mode="buttons" />

2.5.8 Target Size (Minimum) - AA

Requirements: Touch targets are at least 24x24 CSS pixels

Checkpoints：

Buttons are at least 24x24px
Mobile touch targets ≥ 44x44px (WCAG 2.2 AAA)
Sufficient spacing between targets

/* ✅ 合规的触摸目标 */
button {
  min-height: 44px;
  min-width: 44px;
  padding: 12px 16px;
}

Detailed WCAG 2.2 AA Checklist

1. Perceivable

1.1.1 Non-text Content - All text

All images have alt text
Complex images have long descriptions
Icon buttons have aria-label
Forms have visible labels

<!-- ✅ 合规 -->
<img src="chart.png" alt="2024年用户增长图表，显示同比增长25%" />

<!-- ❌ 不合规 -->
<img src="chart.png" />

1.3.1 Info and Relationships

Semantic HTML structure
Correct heading hierarchy (h1 → h2 → h3)
Forms are associated with correct labels
Lists use ul/ol

<!-- ✅ 合规 -->
<label for="email">邮箱地址</label>
<input type="email" id="email" name="email" />

<!-- ❌ 不合规 -->
<span>邮箱地址</span>
<input type="email" aria-label="邮箱" />

1.4.3 Contrast (Minimum)

Text contrast requirements：

Normal text: 4.5:1
Large text (18px+ or 14px bold): 3:1
UI components and graphical objects: 3:1

Inspection tools：

Chrome DevTools > Lighthouse
WebAIM Contrast Checker -axe DevTools

/* ✅ 合规 */
.text-primary {
  color: #1a1a1a; /* 对比度 16:1 on #ffffff */
}

.text-secondary {
  color: #5c5c5c; /* 对比度 7:1 on #ffffff */
}

1.4.4 Resize Text

Text can be enlarged to 200% without loss of information
Use relative units (rem, em) rather than fixed units (px)
Avoid text-size-adjust restrictions

/* ✅ 合规 */
body {
  font-size: 1rem; /* = 16px default */
  line-height: 1.5;
}

h1 {
  font-size: 2rem; /* = 32px */
}

1.4.11 Non-text Contrast

UI component contrast requirements：

Borders: 3:1
Focus indicators: 3:1
Filled areas: 3:1

/* ✅ 合规 */
.input {
  border: 1px solid #767676; /* 对比度 4.5:1 */
  background: #ffffff;
}

.input:focus {
  border-color: #005fcc; /* 对比度 4.7:1 */
}

1.4.12 Text Spacing

No loss of information when content is enlarged to 200%:

Letter spacing ≥ 0.12em
Word spacing ≥ 0.16em
Line height ≥ 1.5

/* ✅ 合规 */
p {
  letter-spacing: 0.12em;
  word-spacing: 0.16em;
  line-height: 1.5;
}

1.4.13 Content Hover on Hover

Hoverable content can be dismissed
Hover content is visible without precise pointing
Hover state can be triggered by the user

2. Operable

2.1.1 Keyboard

All functionality is operable through a keyboard：

All interactive elements are accessible via Tab
Focus order is logical
Custom components have keyboard support

Testing methods：

Unplug the mouse
Operate using only Tab, Enter, Space, and arrow keys
Ensure all functionality is available

// ✅ 合规的键盘支持
<div
  role="button"
  tabIndex={0}
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault();
      handleClick();
    }
  }}
>
  点击我
</div>

2.1.2 No Keyboard Trap

The Tab key can move freely through all areas
The Escape key can close modals/dropdown menus
No unexpected focus loops

2.4.1 Bypass Blocks

Provide a "Skip to main content" link
The skip link is visible when focused

<!-- ✅ 合规 -->
<a href="#main-content" class="skip-link">
  跳转到主要内容
</a>

<main id="main-content">
  <!-- 主要内容 -->
</main>

<style>
.skip-link {
  position: absolute;
  top: -100px;
}
.skip-link:focus {
  top: 0;
}
</style>

2.4.3 Focus Order

Focus order follows visual and logical order
DOM order matches visual order
Pay attention to order when adjusting with tabindex

2.4.4 Link Purpose (In Context)

Link text describes the purpose
Avoid "click here", "read more"
Multiple links to the same destination on the same page have the same text

<!-- ✅ 合规 -->
<a href="/pricing">查看定价方案</a>

<!-- ❌ 不合规 -->
<a href="/pricing">点击这里</a>

2.4.6 Headings and Labels

Headings describe the topic or purpose
Labels describe the input purpose
Do not use placeholders instead of labels

<!-- ✅ 合规 -->
<label for="search">搜索产品</label>
<input type="search" id="search" placeholder="输入关键词..." />

<!-- ❌ 不合规 -->
<input type="search" placeholder="搜索产品" />

2.4.7 Focus Visible

Focus indicators are always visible
Do not use outline: none unless there is an alternative

2.5.3 Label in Name

The accessible name contains the visible text
Icon buttons have visible labels

<!-- ✅ 合规 -->
<button>
  <svg aria-hidden="true"><!-- ... --></svg>
  <span>提交</span>
</button>

<!-- ❌ 不合规 -->
<button aria-label="提交"></button>

2.5.4 Motion Actuation

Functionality does not depend on specific gestures
Provide alternative operation methods

3. Understandable

3.1.1 Page Language

HTML has a lang attribute
lang attribute value is correct

<!-- ✅ 合规 -->
<html lang="zh-CN">

3.2.1 On Focus

Focus changes do not automatically trigger context changes
User-initiated rather than automatic transfer

<!-- ❌ 不合规 -->
<select onchange="this.form.submit()">

<!-- ✅ 合规 -->
<select onchange="confirm('确认选择？') && this.form.submit()">

3.2.2 On Input

Input changes do not automatically submit
User-initiated submission

3.3.1 Error Identification

Errors are identified on form submission
Errors have text descriptions
Errors point to specific fields

<!-- ✅ 合规 -->
<label for="email">邮箱</label>
<input type="email" id="email" aria-describedby="email-error" />
<span id="email-error" role="alert">
  请输入有效的邮箱地址
</span>

<!-- ❌ 不合规 -->
<input type="email" aria-invalid="true" />

3.3.2 Labels or Instructions

Input instructions are associated with the input
Use aria-describedby

<!-- ✅ 合规 -->
<label for="username">用户名</label>
<p id="username-hint">4-20个字符，可包含字母数字下划线</p>
<input id="username" aria-describedby="username-hint" />

4. Robust

4.1.1 Parsing

HTML is valid and has no duplicate IDs
Check with validation tools

4.1.2 Name, Role, Value

UI components have correct name, role, and value
Use native HTML elements instead of custom ARIA

<!-- ✅ 合规 -->
<button>提交</button>

<!-- ❌ 不合规 -->
<div onclick="submit()">提交</div>

4.1.3 Status Messages

Status changes have text notifications
Use aria-live regions

<!-- ✅ 合规 -->
<div aria-live="polite" aria-atomic="true">
  {statusMessage}
</div>

Quick Checklist (Daily Use)

Required Items (Must Pass)

All images have alt text
All form inputs have labels
Color contrast ratio >= 4.5:1
All functionality is keyboard accessible
Focus indicators are visible
Link text describes the purpose

Recommended Testing Tools

Automated Tools

axe DevTools: Browser extension for real-time detection of accessibility issues
Lighthouse: Built into Chrome DevTools, generates audit reports
WAVE: Developed by WebAIM, visualizes issues
Accessibility Insights: Developed by Microsoft, in-depth detection

Manual Testing

Keyboard testing: Unplug the mouse and operate using only the keyboard
Screen reader testing：NVDA (Windows)、VoiceOver (macOS)
Zoom testing: Zoom to 200% to check the layout

Fix Priority

P0 - Fix Immediately

Key functionality is unavailable via keyboard
Main content has no alt text
Severely insufficient contrast
Form errors cannot be identified

P1 - Fix As Soon As Possible

Focus indicators are not obvious
Link text is unclear
Heading hierarchy is confusing
Target size is too small

P2 - Plan to Fix

Enhance color blindness support
Optimize the mobile experience
Add more explanatory text
Optimize the animation experience

Report Template

# 可访问性审计报告

## 概述
- **审计日期**: YYYY-MM-DD
- **审计范围**: [页面/组件/功能]
- **符合标准**: WCAG 2.2 AA

## 发现问题

### P0 - 立即修复
| 问题 | 位置 | 影响 | 建议修复 |
|------|------|------|---------|
| ... | ... | ... | ... |

### P1 - 尽快修复
| 问题 | 位置 | 影响 | 建议修复 |
|------|------|------|---------|
| ... | ... | ... | ... |

### P2 - 计划修复
| 问题 | 位置 | 影响 | 建议修复 |
|------|------|------|---------|
| ... | ... | ... | ... |

## 通过项目
- [ ] 列表
- [ ] 通过
- [ ] 的项目

## 建议
1. ...
2. ...
3. ...

## 参考资料
- [WCAG 2.2 官方文档](https://www.w3.org/TR/WCAG22/)
- [WebAIM 对比度检查](https://webaim.org/resources/contrastchecker/)
- [axe DevTools](https://www.deque.com/axe/)

Related Skills

FrontendImplementation: Avoid accessibility issues during design
ReactBestPractices: Accessible implementation of React components
Security Specialist: Includes security-related accessibility requirements

About this skill

Overview

Quick Review (Web Interface Guidelines)

Workflow

Usage

Full Audit (WCAG 2.2 AA)

New WCAG 2.2 Success Criteria

2.4.11 Focus Appearance (Minimum) - AA

2.4.12 Focus Not Obscured (Minimum) - AA

2.5.7 Dragging Movements - AA

2.5.8 Target Size (Minimum) - AA

Detailed WCAG 2.2 AA Checklist

1. Perceivable

1.1.1 Non-text Content - All text

1.3.1 Info and Relationships

1.4.3 Contrast (Minimum)

1.4.4 Resize Text

1.4.11 Non-text Contrast

1.4.12 Text Spacing

1.4.13 Content Hover on Hover

2. Operable

2.1.1 Keyboard

2.1.2 No Keyboard Trap

2.4.1 Bypass Blocks

2.4.3 Focus Order

2.4.4 Link Purpose (In Context)

2.4.6 Headings and Labels

2.4.7 Focus Visible

2.5.3 Label in Name

2.5.4 Motion Actuation

3. Understandable

3.1.1 Page Language

3.2.1 On Focus

3.2.2 On Input

3.3.1 Error Identification

3.3.2 Labels or Instructions

4. Robust

4.1.1 Parsing

4.1.2 Name, Role, Value

4.1.3 Status Messages

Quick Checklist (Daily Use)

Required Items (Must Pass)

Recommended Items (Strongly Recommended)

Recommended Testing Tools

Automated Tools

Manual Testing

Fix Priority

P0 - Fix Immediately

P1 - Fix As Soon As Possible

P2 - Plan to Fix

Report Template

Related Skills