web-design-guidelines

Web 设计指南

面向包容性 Web 界面的 WCAG 无障碍访问、语义化 HTML、键盘导航、表单和性能模式。包含 4 个类别中的 23 条规则。支持编码参考和审计模式。

元数据

• 版本： 2.1.0
• 规则数量： 4 个类别中的 23 条规则
• 许可证： MIT

如何进行审计

当用户要求“审计无障碍访问”“检查 WCAG 合规性”或“审查无障碍访问”时，针对其代码库执行以下检查清单。

步骤 1：确定范围

• 如果提供了参数（$ARGUMENTS）：仅审计指定的文件或组件
• 如果未提供参数：审计代码库中的所有 UI 组件和页面

步骤 2：检测技术栈

检查项目中的：

• .tsx/.jsx 文件 → React
• .vue 文件 → Vue
• .blade.php 文件 → Laravel Blade
• .html 文件 → 静态 HTML

步骤 3：执行无障碍访问检查清单

逐项检查以下内容。对每项输出：

• 通过 — 简要确认已验证的内容
• 失败 — 准确的 file:line、问题描述和修复建议
• 不适用 — 如果该检查不适用于此项目

语义化 HTML 与结构

• 页面使用语义化元素（<header>、<main>、<nav>、<footer>、<article>、<section>），而不是充斥着 <div>
• 标题层级按顺序排列（h1 → h2 → h3），没有跳级
• 每个页面只有一个 <h1>
• 存在跳过导航的链接（<a href="#main-content">Skip to content</a>）
• 重复的地标区域均有标签（多个 <nav> 元素上带有 aria-label）

键盘导航

• 所有交互元素都可通过 Tab 键访问
• 焦点顺序与视觉顺序一致（没有正值 tabindex）
• 所有可聚焦元素都有可见的焦点指示器（移除 outline: none 时必须提供替代样式）
• 模态对话框会锁定焦点，并在关闭时将焦点还回
• 自定义组件（下拉菜单、标签页、手风琴组件）支持预期的键盘操作模式（方向键、Escape、Enter）

图片与媒体

• 所有 <img> 元素都有 alt 属性：内容图片使用描述性文本，装饰图片使用空值（alt=""）
• 复杂图片（图表、示意图）提供详细描述
• 视频内容提供字幕或文字稿

颜色与对比度

• 文本符合 WCAG AA 对比度要求（普通文本为 4.5:1，大号文本为 3:1）
• 信息不会仅通过颜色传达（例如，错误状态使用图标和文本，而不只是红色）
• UI 组件和焦点指示器与背景的对比度达到 3:1

表单

• 每个输入框都有对应的 <label>（不能仅使用占位文本）
• 必填字段同时通过视觉提示和 aria-required="true" 标明
• 错误消息通过 aria-describedby 与输入框关联
• 错误消息使用 role="alert" 或 aria-live="assertive"，以便向屏幕阅读器播报
• 输入框使用正确的 type 属性（email、tel、url、number）
• 常见字段（姓名、电子邮件、地址、信用卡）具有 autocomplete 属性

ARIA 与屏幕阅读器

• 仅包含图标的按钮具有 ARIA 标签（aria-label="Close"）
• 动态内容更新使用 aria-live 区域
• 向屏幕阅读器播报加载状态（aria-busy="true"、状态消息）
• 对屏幕阅读器隐藏装饰性元素（aria-hidden="true"）

动效与动画

• 遵循 prefers-reduced-motion 设置 — 禁用或减少动画
• 不播放未经用户控制的自动播放视频或音频
• 不包含每秒闪烁超过 3 次的内容

步骤 4：总结

在审计结束时输出：

## Accessibility Audit Summary
- **PASS**: X checks
- **FAIL**: X checks
- **N/A**: X checks
- **WCAG Level**: AA / Partial AA / Below AA
- **Top Priority Fixes**: (list the 3 most impactful FAIL items)

---

适用场景

在以下情况下参考这些指南：

• 对代码库进行无障碍访问审计
• 审查 UI 代码的无障碍访问情况（WCAG 合规性）
• 实现表单和交互
• 确保键盘导航正常工作
• 添加 ARIA 标签和实时区域
• 优化图片加载和布局稳定性

按优先级划分的规则类别

优先级	类别	影响	前缀
1	无障碍访问	严重	a11y-
2	表单	高	form-
3	动画与动效	严重	motion-
4	性能与用户体验	中	perf-

快速参考

1. 无障碍访问（严重）

• a11y-semantic-html - 使用语义化 HTML 元素
• a11y-heading-hierarchy - 保持正确的标题层级
• a11y-screen-reader - 优化屏幕阅读器兼容性
• a11y-skip-links - 提供导航跳转链接
• a11y-keyboard-nav - 确保全面支持键盘导航
• a11y-focus-management - 妥善管理键盘焦点
• a11y-aria-labels - 为交互元素添加 ARIA 标签
• a11y-color-contrast - 确保足够的颜色对比度（WCAG AA）
• a11y-alt-text - 为图片提供有意义的替代文本
• a11y-error-messages - 确保错误消息易于访问
• a11y-form-labels - 将标签与表单输入框关联
• a11y-live-regions - 向屏幕阅读器播报动态内容

2. 表单（高）

• form-autocomplete - 使用自动完成属性
• form-input-types - 使用正确的输入类型
• form-error-display - 清晰显示表单错误
• form-validation-ux - 设计用户友好的验证体验
• form-inline-validation - 实现智能的内联验证
• form-multi-step - 设计有效的多步骤表单
• form-placeholder-usage - 适当使用占位符
• form-submit-feedback - 提供清晰的提交反馈

3. 动画与动效（严重）

• motion-reduced - 遵循 prefers-reduced-motion（WCAG AAA）

4. 性能与用户体验（中）

• perf-image-loading - 优化图片加载，提升用户体验
• perf-layout-stability - 避免累积布局偏移

基本指南

语义化 HTML

// ❌ Div soup
<div className="header"><div className="nav"><div onClick={handleClick}>Home</div></div></div>

// ✅ Semantic HTML
<header><nav aria-label="Main"><a href="/">Home</a></nav></header>
<main><article><h1>Title</h1><p>Content</p></article></main>

表单无障碍访问

<label htmlFor="email">Email <span aria-hidden="true">*</span></label>
<input id="email" type="email" required aria-required="true" aria-describedby="email-error" autoComplete="email" />
{error && <p id="email-error" role="alert">{error}</p>}

减少动效

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

使用方法

阅读各规则文件，了解详细说明：

rules/a11y-semantic-html.md
rules/form-autocomplete.md
rules/motion-reduced.md
rules/perf-image-loading.md

参考资料

• WCAG 2.2 快速参考
• WAI-ARIA 编写实践
• web.dev 无障碍访问
• MDN 无障碍访问
• A11Y 项目

完整汇编文档

如需查看包含所有规则详细说明的完整指南：AGENTS.md