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 文件。

进阶学习建议

如果想进一步用好 web-design-guidelines,建议按以下路径学习:

第 1 周:熟练使用

• 完成 3 步快速上手,跑通第一个任务
• 试 2-3 个不同场景的真实任务
• 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记

第 2 周:理解机制

• 阅读 Skill 的官方文档(README、SKILL.md)
• 了解 Skill 的”触发关键词”和”输出格式”
• 学习”如何用更具体的描述触发 Skill”

第 3-4 周:组合使用

• 跟其他 Skill 组合(比如代码审查 + 性能优化)
• 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
• 沉淀团队/个人的 Skill 库

长期:贡献社区

• 把自定义的 Skill 开源到 GitHub
• 提 PR 改进现有 Skill
• 写使用心得分享到 CSDN/掘金/知乎

推荐资源:

• 官方文档:https://github.com/vercel-labs/agent-skills
• 官方仓库 README 里的 Examples
• 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
• 国内社区:CSDN AI 板块、掘金 AI 板块

避免的坑:

• 不要装太多 Skill(超过 10 个会拖慢 Agent)
• 不要把 Skill 装在不兼容的 Agent 上
• 不要直接复制 Skill 默认 prompt——要根据项目调整
• 定期 review Skill 库的实用性,清理不用的

参考链接

• 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

我的个人推荐(测试编辑 Mnet)

最常用的 1 个核心用法:每天打开 Agent 第一时间加载这个 Skill,既不消耗太多 token 也能规范输出。

最容易踩的坑:别把 Skill 提示词当”开箱即用”的最终答案——它只是给你一个”标准框架”,具体项目还得你自己调整。

适合人群:做过 3+ 个实际项目的开发者,而不是”看一遍文档就完事”的小白。

3 个月使用心得:刚开始用时觉得”规范是约束”,用了 3 个月后才发现”规范是省时间”——避免每次重新决策同样的细节。

推荐配合的工具:Claude Code / Cursor / OpenCode 任选一个主流 Agent 即可,不要在工具选择上纠结太久。

长期价值:这类 Skill 的核心价值不是”立竿见影的输出”,而是”持续一致的质量”——长期用下来,你的项目质量会稳定在专业水平。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。