web-design-guidelines 是一个 AI 编程助手专用的 Agent Skill，用于自动审查 UI 代码是否符合 Web Interface Guidelines（Web 界面设计指南）。它的工作方式是：动态获取最新的设计规范，然后对指定的 HTML、CSS 或前端组件代码进行逐条检查，最终输出结构化的审查报告。
这个插件由开源社区维护，在 antfu/skills、tech-leads-club/agent-skills 等多个仓库中均有收录。它不绑定任何特定框架——React、Vue、原生 HTML，只要是前端代码都能审。
一、web-design-guidelines 有哪些核心功能？
web-design-guidelines 的审查覆盖范围相当全面，官方资料显示它审计的规则超过 100 条。
可访问性审查
检查 ARIA 标签是否正确使用、语义化 HTML 是否到位、键盘导航是否完整覆盖。屏幕阅读器用户能不能顺利使用你的页面，这部分说了算。
焦点状态与键盘交互
按钮、链接、表单输入框的焦点状态是否清晰可见？Tab 键顺序是否合理？这些都是审查项。
表单设计
自动补全、输入验证、标签与输入框的关联——表单是用户交互最频繁的地方，也是问题最多的地方。
动画与动效
检查动画是否考虑了 prefers-reduced-motion 用户偏好设置，动画性能是否达标。
排版与文字内容
特殊字符的显示、数字的格式化、文字溢出和空状态的处理。
图片处理
图片尺寸是否合适、懒加载是否配置、alt 文本是否齐全。
性能
DOM 操作是否频繁、长列表是否使用了虚拟滚动。
导航与状态管理
URL 是否与页面状态同步、深链接是否可用。
触摸交互
移动端的触摸延迟、安全区域适配。
深色模式与主题
深色模式下的颜色对比度、主题切换的平滑度。
国际化与本地化
多语言场景下的文本适配。
常见反模式标记
审查报告会标记出代码中的典型反模式，帮助开发者避免踩坑。
每次审查前，插件都会从远程源拉取最新的设计规范，确保检查标准始终是最新的。审查结果采用 file:line 的简洁格式输出，VS Code 里直接点击就能跳转到对应代码行。
二、怎么安装 web-design-guidelines？
安装方式取决于你用的是哪个 AI 编程环境。
方式一：通过 npx skills 命令安装（推荐）
在项目根目录执行以下命令：
npx skills add https://github.com/antfu/skills --skill web-design-guidelines
或者使用其他镜像源：
npx skills add https://github.com/tech-leads-club/agent-skills --skill web-design-guidelines
npx skills add https://github.com/alfredang/skills --skill web-design-guidelines
安装过程中 CLI 会提示你选择目标 AI 编程环境（Claude Code、Cursor、Windsurf、Codex 等），选择你正在用的就行。安装完成后，技能会自动配置到对应的环境中。
方式二：手动安装（Claude Code 专用）
mkdir -p ~/.claude/skills/web-design-guidelines curl -L https://claudskills.com/skills/web-design-guidelines/SKILL.md \ -o ~/.claude/skills/web-design-guidelines/SKILL.md
Claude Code 会在下次启动时自动发现并加载这个技能。
前置条件
使用 web-design-guidelines 之前，确保你的 AI 编程环境（Claude Code、Cursor 或 OpenClaw）已经配置好并能正常运行。Node.js 16+ 也是必须的。
三、web-design-guidelines 适合谁用？用在什么场景？
场景一：前端开发者的代码自检
写完一个页面或组件后，让 AI 助手帮你过一遍设计规范的合规性。不用等 Code Review 时被同事指出问题，提交前自己就能发现并修复。适合个人开发者、独立项目以及快速迭代的创业团队。
场景二：设计系统的质量门禁
团队维护着统一的设计系统和组件库，每次新增或修改组件都需要确保符合设计规范。把 web-design-guidelines 集成到 CI/CD 流程中，每次 PR 自动触发审查，不符合规范的代码无法合入。
场景三：可访问性专项审计
WCAG 2.2 合规是很多项目的硬性要求。web-design-guidelines 内置了可访问性审查能力，可以快速扫描整个项目，找出所有不符合无障碍标准的代码位置。
场景四：接手遗留项目的快速诊断
新加入一个团队，面对几千行前端代码不知道从哪看起。用 web-design-guidelines 扫一遍，所有设计规范相关的问题一目了然，优先修哪些心里有数。
场景五：AI 生成代码的质量把关
用 AI 生成前端代码越来越普遍，但 AI 产出的代码在可访问性、语义化等方面经常有疏漏。把 web-design-guidelines 作为 AI 生成代码后的必经环节，自动审查、自动修复，能省不少人工检查的功夫。
四、实战案例：用 web-design-guidelines 审查一个登录表单
假设你刚写完一个登录页面的 HTML 代码，想让 AI 助手帮你检查一下是否符合设计规范。
第一步，唤起 AI 助手审查
在 Claude Code 或 Cursor 的 Composer 中输入：
请用 web-design-guidelines 审查我的登录页面代码
AI 助手会自动识别这个请求并调用对应的 skill。
第二步，指定要审查的文件
如果 AI 助手询问要审查哪些文件，告诉它文件路径或匹配模式，比如：
审查 src/components/LoginForm.tsx 和 src/styles/login.css
第三步，获取审查报告
web-design-guidelines 会读取最新的设计规范，逐条检查你的代码，然后输出类似这样的报告：
src/components/LoginForm.tsx:23 - 缺少 ARIA label，表单输入框未关联 label src/components/LoginForm.tsx:45 - 提交按钮缺少键盘事件支持 src/styles/login.css:12 - 颜色对比度不足，不符合 WCAG AA 标准 src/components/LoginForm.tsx:67 - 密码输入框未设置 autocomplete="current-password"
第四步，按报告修复问题
每条报告都带有精确的文件名和行号，VS Code 里直接点击就能跳转。逐条修复后，可以再次运行审查，直到所有问题清零。
整个过程从请求审查到拿到报告，通常不到一分钟。如果手动对照设计规范逐条检查，同样的工作量至少需要十五到二十分钟。
五、注意事项
web-design-guidelines 聚焦于视觉设计、交互模式和可访问性。它不负责性能审计（那是 core-web-vitals 的事）、不负责 SEO 检查（那是 seo 的事）、也不做全面的站点质量审计（那是 web-quality-audit 的事）。
另外，审查结果的质量取决于你提供的代码是否完整——如果只给了片段，审查的覆盖面自然有限。建议在审查时提供完整的组件代码或页面代码。
六、写在最后
web-design-guidelines 把 Web 设计规范的审查工作从人工对照变成了自动化流程。对于前端开发者、设计系统维护者和需要确保可访问性合规的团队来说，这是一个降低门槛、提升效率的实用工具。
安装只需一条 npx 命令，上手几乎没有学习成本。无论你是想规范自己的代码质量，还是想在团队层面建立设计规范的门禁机制，都值得试一试。
◯ 评论 0