web-design-guidelines

web-design-guidelines 快速入门

3 步让 AI 帮你审完 100+ 条 UI/UX 规则——可访问性、表单、动画、暗色模式一次过。

这是什么?解决什么问题?

web-design-guidelines 是 Anthropic 在 anthropics/skills 生态中整合的 UI/UX 审查 Skill(底层由 Vercel Labs 的 vercel-labs/agent-skills 维护),收录了 100+ 条前端设计规范,覆盖 8 个核心维度:

• 可访问性 (a11y):WCAG 2.1 AA / AAA、屏幕阅读器、键盘导航、对比度;
• 焦点管理:tab order、focus trap、skip link、focus-visible;
• 表单:label 关联、错误提示、aria-describedby、实时校验;
• 动画:prefers-reduced-motion、动画时长、easing、性能影响;
• 排版:行高、字距、断字、CJK 处理、字号尺度;
• 图像:alt 文本、loading="lazy"、decoding="async"、srcset;
• 暗色模式:prefers-color-scheme、系统级切换、对比度退化;
• 响应式:断点、触摸目标 ≥ 44px、滚动行为、视口单位。 普通开发者让 AI 写 UI 时,常常只关注“看起来对不对”,而忽略“用键盘能不能操作”、“色盲用户能不能看清”、“动晕症用户能不能用”。这个 Skill 把资深前端工程师脑子里的规范清单沉淀成 Agent 提示词,让 AI 写完代码后主动跑一次审查。 适合前端工程师、UI 设计师、Tech Lead、QA 工程师,以及任何想让产品达到“商业级可用性”的人。

准备工作

1. AI 编程 Agent:Claude Code / Cursor / Cline。
2. 一个 Web 项目:HTML / React / Vue / Svelte 都行。
3. 可选:axe-core / Lighthouse:本地自动化检查工具,Skill 强调 AI 审查和工具审查互补。
4. 可选:屏幕阅读器(VoiceOver / NVDA):做最终人工验收时用。
5. 基础 HTML / CSS 知识:能看懂标签和样式即可。

3 步快速上手

第 1 步:克隆 Skills 仓库

git clone https://github.com/anthropics/skills.git
cd skills/skills/web-design-guidelines
ls

或定位到 Vercel Labs 维护的版本:

git clone https://github.com/vercel-labs/agent-skills.git
cd agent-skills/skills/web-design-guidelines

第 2 步:让 Agent 加载 Skill

CLAUDE.md:

# CLAUDE.md
After any UI change, run the web-design-guidelines skill against the
diff. Report findings as: A11y / Focus / Form / Animation / Typography
/ Image / Dark mode / Responsive. Cite WCAG SC when applicable.

第 3 步:用 Skill 跑一次审查

请用 web-design-guidelines Skill 审查 src/components/SignupForm.tsx,输出结构化报告。

Agent 会按 8 个维度逐项检查,例如:

## A11y

- SignupForm.tsx:42 密码输入缺 aria-describedby

关联到错误提示元素,屏幕阅读器读不到错误信息。

WCAG SC: 1.3.1 (Info and Relationships)

Fix: <input aria-describedby="pwd-error" />

<p id="pwd-error" role="alert">密码至少 8 位</p>

## Form

- SignupForm.tsx:18 Submit 按钮在网络错误时无失败提示

失败时按钮立即恢复可点击,用户不知道发生了什么。

Fix: 失败后用 aria-live="assertive" 区域宣告错误。

## Animation

- SignupForm.tsx:88 用 transition: all 0.3s 触发大范围重排

性能 + 动晕症风险。

Fix: 显式 transition: transform 0.2s ease-out;

并加 @media (prefers-reduced-motion: reduce) { transition: none; }

## Dark mode

- SignupForm.tsx:30 用了 #f5f5f5 作为背景

暗色模式下文字是 #999,对比度仅 2.8:1,过不了 WCAG AA (4.5:1)。

Fix: 用 CSS 变量配合 prefers-color-scheme。

常见踩坑

1. 只检查 aria-label,忽略语义化标签:Skill 强调优先用 <button> <nav> <main> 这样的语义元素,而不是 div + aria。

2. 对比度算错:普通开发者手算 HEX 差值很费劲,Skill 提示 Agent 用 WCAG 公式 relative luminance。

3. prefers-reduced-motion 没处理:动效是动晕症用户的噩梦,Skill 强制要求每个 animation 都有 fallback。

4. 触摸目标 < 44px:移动端按钮太密集,Skill 提示在审查里点出。

5. 图像 alt 写 “image1.jpg”:没用信息,Skill 提示改写为场景描述。

6. 暗色模式只换背景色:文字颜色没改,Skill 强调两套 token 必须同步。

初级用法

1. 审查一个组件

请审查 components/Button.tsx,关注 a11y、focus、dark mode。

2. 审查整个页面

请审查 pages/checkout.tsx,8 个维度全过一遍。

3. 自动改文案

帮我把所有 aria-label="icon" 这种没意义的标签改成具体描述。

高级玩法

1. 集成 axe-core / Lighthouse

npx @axe-core/cli http://localhost:3000

把输出 JSON 给 Agent 做二次人工审查,互补。

2. 与 Storybook 联动

把 Skill 模板做成 Storybook addon,每个 story 自动跑 a11y 评分。

3. 设计 token 库

把 8 个维度的合规 token 抽到 tokens/a11y.json,CI 时校验每个组件。

4. 多语言 / RTL 适配

Skill 提示 dir="rtl"、CJK 字体、双向括号等本地化检查项。

小技巧

• 先看 Lighthouse 再看 AI:Lighthouse 抓机器能抓的,AI 抓语义和体验的。

• a11y 不是“残疾用户专属”:键盘用户、低视力用户、动晕症用户都是真实用户。

• 颜色对比度用工具测:https://webaim.org/resources/contrastchecker/ 一次性解决。

• 暗色模式先做:设计阶段就建两套 token,后期补很痛苦。

• 动画 ≤ 200ms:长动画让用户感觉“卡”,Skill 默认上限 200ms。

常见问题 FAQ

Q1: 这个 Skill 跟 web-design-guidelines 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: web-design-guidelines 来自 Anthropic,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 web-design-guidelines 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

参考链接

• Anthropic Skills 总仓库:https://github.com/anthropics/skills

• web-design-guidelines 子目录:https://github.com/anthropics/skills/tree/main/skills/web-design-guidelines

• Vercel Labs 版本:https://github.com/vercel-labs/agent-skills

• WCAG 2.1 规范:https://www.w3.org/TR/WCAG21/

• WebAIM 对比度检查:https://webaim.org/resources/contrastchecker/

• axe-core:https://github.com/dequelabs/axe-core

• Lighthouse:https://developer.chrome.com/docs/lighthouse/overview

• prefers-reduced-motion:https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion

• Inclusive Components 手册:https://inclusive-components.design/

• MDN ARIA 参考:https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA