AI 生成的页面看起来可能已经完成，但键盘无法操作导航，表单出错后也可能丢失资料。这些问题通常要等到有人实际使用时才会显现。
AI 网站设计指南技能为编码代理提供检查界面代码的指令。它可以协助发现缺陷，但团队仍需核实结果并测试修改。
本指南说明如何安装 Vercel 的 web-design-guidelines 技能、设定有效的审查范围并检查结果。命令已对照官方文件核对。本文中的代码仅作说明用途，未在浏览器中测试。
要点
- 明确审查范围，并提供项目的设计规则。
- 确认代理已载入技能及其指南来源。
- 修改代码前先核实发现的问题，并区分缺陷与设计偏好。
- 先做小幅修复，再在浏览器中测试受影响的操作。
- 记录检查内容、修改项目和未解决事项。
本指南内容
什么是 AI 网站设计指南技能？
AI 代理技能与人工设计能力、提示词和网站制作工具的分别
代理技能是一套可重复使用的指令，有时也会附上参考资料或脚本。
| 资源 | 用途 |
|---|---|
| 人工设计能力 | 了解用户、评估选项并作出设计决定 |
| 提示词 | 说明当前任务和限制 |
| 代理技能 | 为某类任务提供可重复使用的指导 |
| 网站制作工具 | 组装、管理和发布页面 |
审查技能需要项目背景。单靠组件文件，它无法判断您的受众、品牌规则或审批流程。
web-design-guidelines 技能的功能及其无法保证的事项
Vercel 的web-design-guidelines 官方技能说明会指示代理取得界面指南、检查指定文件，并附上文件和行数报告结果。技能本身与外部指南来源是两项不同的资源。
源码审查可以发现代码问题，却无法证明已部署的网站能够在不同浏览器、内容状态和辅助技术中正常运作。
适用对象：前端开发人员、设计师和审查 AI 生成界面的团队
开发人员可以先用它检查，再请同事审阅。设计师可以用审查结果讨论实施问题。
网站负责人也可以要求进行同类审查，并由开发人员负责评估建议的代码修改。
快速开始：安装并运行第一次界面审查
前置条件：受支持的代理、项目访问权限和用于 CLI 安装的 Node.js
您需要：
- Node.js 和 npm，包括
npx。 - 受支持的编码代理。
- 相关项目文件的访问权限。
- 下载套件和指南所需的网络连接。
检查本机工具：
node --version
npm --version如果安装出现兼容性错误，先检查套件目前的要求，再考虑更改 Node.js 版本。
核实官方仓库、技能名称和最新安装说明
安装之前先核实来源：
| 项目 | 标识 |
|---|---|
| 仓库 | vercel-labs/agent-skills |
| 技能 | web-design-guidelines |
| 安装器 | skills CLI |
查看官方仓库和最新安装说明。
从 vercel-labs/agent-skills 安装并选择 web-design-guidelines
在目标项目目录中运行：
npx skills add vercel-labs/agent-skills \
--skill web-design-guidelines若要指定 Claude Code：
npx skills add vercel-labs/agent-skills \
--skill web-design-guidelines \
--agent claude-codeSkills CLI 文档说明，该工具支持项目级和全局安装。检查建议的安装位置。
在 Claude Code 或其他受支持的编码代理中启用技能
确认该技能出现在代理可用的技能清单中。也可以查看已安装项目：
npx skills list如果代理无法识别该技能，请按代理说明重新载入或开启新会话。
运行第一次审查并确认代理已载入指南
先检查一个文件：
使用 web-design-guidelines 审查
src/components/Header.tsx。不要修改文件。指出您载入的技能和指南来源。报告时附上文件和行数。说明哪些内容无法检查或取得。
如代理提供工具活动记录，请检查记录，并确认它已打开文件及取得指南。
为网站设计任务选择合适的 AI 技能
Web Design Guidelines、Frontend Design、UI Skills 和 React Best Practices 对照
| 技能或集合 | 主要用途 |
|---|---|
| Vercel Web Design Guidelines | 审查现有界面代码 |
| Anthropic Frontend Design | 制定或调整视觉方向和实施方式 |
| UI Skills | 使用一组专门界面技能中的指导 |
| Vercel React Best Practices | 检查 React 和 Next.js 性能模式 |
UI Skills 是一个技能集合。评估覆盖范围前，先说明要用哪一项技能。
先比较Vercel agent skills、Anthropic Frontend Design和UI Skills，再选择套件并阅读相应说明。
何时用界面审查技能，而不是网站制作工具或 SEO 审查
用界面审查评估用户如何理解和操作页面。
用网站制作工具创建和发布页面。用 SEO 审查调查抓取、索引和搜索意图等问题。
界面正常运作之后，还需要让用户找得到。请把技术 SEO视为网站需求中的独立部分。
组合互补技能，避免产生相互冲突的指令
按阶段使用不同技能：
- 确定受众、任务和已批准的设计。
- 建立或调整界面。
- 检查交互和无障碍体验。
- 调查相关性能问题。
- 测试结果。
修改实现之前，要求代理指出与项目指令相冲突的地方。
AI 应检查的核心网站设计指南
以下项目构成较完整的审查要求。其中一些检查需要浏览器访问权或其他工具。
语义化 HTML、无障碍名称和适当使用 ARIA
按原本用途使用 HTML 原生元素，并确认每个控件都有明确、可供辅助技术识别的名称。
ARIA 是 Accessible Rich Internet Applications 的简称，用于补充辅助技术会读取的语义。需要时才使用，并以 HTML 原生元素为基础。
键盘导航、可见焦点和焦点管理
尝试只用键盘完成任务。
检查焦点顺序、可见状态，以及面板打开或关闭时焦点如何移动。隐藏的导航不应让看不见的链接继续出现在 Tab 顺序中。
颜色对比、字体排版和易读内容
根据实际背景颜色测量对比度。
WCAG 2.2 对比度要求规定普通文字至少为 4.5:1，符合条件的大号文字至少为 3:1，特定情况可例外。也要检查间距、行长和说明文字。
响应式布局、缩放支持和触控目标
测试窄屏、放大文字和浏览器缩放，检查控件被裁切或内容重叠的情况。
WCAG 2.2 的目标尺寸最低标准要求 AA 级触控目标至少为 24 × 24 CSS 像素，部分情况可例外。检查目标尺寸和间距。
表单、标签、验证和可执行的错误提示
检查标签、预期输入、验证和错误恢复方式。
用户需要知道哪里出错以及如何修正。发生可恢复的错误后，应保留已填写的资料。
按钮、链接、导航和可预测的交互
按钮用于执行操作，链接用于前往目的地。
检查标签、浏览器导航，以及用户如何从不可逆操作中恢复。
加载、空白、错误和成功状态
逐一检查不同状态。界面应说明目前正在发生什么、已经发生什么，或用户接下来可以怎么做。
动画、减少动态效果和呈现性能
检查界面是否尊重减少动态效果的设定，以及动画是否拖慢操作。
对于服务器渲染应用，也要测试 hydration，也就是客户端代码连接并启用页面功能的阶段。控件应保留用户输入和当前状态。
图片、布局稳定性和 Core Web Vitals
为媒体预留空间，并检查图片加载时是否推动附近内容移动。
Web Vitals 文档说明如何测量加载、响应和视觉稳定性。只有代码改动，无法证明性能已经改善。
设计变量、视觉层次和品牌一致性
将颜色、字体、间距和组件状态与已批准的设计系统比较。
要求审查者说明偏差会造成什么影响。不同的间距可能是刻意安排。
如何把 AI 审查结果转化为可靠修复
设定审查范围：组件、页面、用户流程和排除项目
说明文件、用户流程和允许采取的行动：
检查手机导航和咨询提交流程。包括无效输入和服务器错误。排除结账和账号页面。不要修改文件。
对于 WordPress，要区分主题代码、自定义组件、页面构建器输出和最终呈现页面。主题文件可能不包含储存在数据库中的内容和设定。
提供品牌规则、设计变量和项目限制
提供已批准的设计参考、共用组件、受支持的浏览器和依赖限制。
说明哪些内容和功能必须保留。这些限制也属于网站开发范围的一部分。
要求附上文件位置、规则依据、严重程度和修复建议
要求开发人员能够评估每项发现：
| 项目 | 所需资料 |
|---|---|
| 位置 | 文件、行数和受影响状态 |
| 依据 | 代码或可重现的行为 |
| 标准 | 指南、标准或项目要求 |
| 影响 | 谁受到影响，以及哪里无法使用 |
| 优先级 | 紧急程度和原因 |
| 修复 | 实际可行的最小改动 |
| 验证 | 检查改动的方法 |
将已确认缺陷与主观设计建议分开
把结果标记为：
- 已确认： 有依据支持。
- 疑似： 需要进一步检查。
- 可选： 设计建议。
不要把个人偏好混进缺陷严重程度。键盘焦点被困住，与建议更换颜色，需要不同处理方式。
优先处理阻碍，实施小幅修改并复查回归问题
先修复会阻碍用户完成任务的问题。
缩小改动范围。重新测试受影响的流程和相邻状态，尤其是修改共用组件之后。
可复制并使用的 AI 界面审查提示词
审查页面，但不修改任何代码
使用 web-design-guidelines 审查[文件]和[网址]，如有浏览器权限也请检查页面。不要修改任何内容。指出检查过的来源和文件。报告可执行的发现，并附上依据、位置、用户影响、优先级和修复建议。将已确认缺陷、疑似问题和可选建议分开。说明测试限制。
保留现有设计并修复无障碍问题
检查[组件或用户流程]。保留已批准的设计、内容和功能。只对已确认的无障碍缺陷作最小修复。重用现有组件和设计变量。测试受影响的键盘、焦点和错误状态。指出需要设计或产品人员决定的事项。
审查 Pull Request，只报告新引入的问题
将 diff 与[基准分支]比较。在适用时使用 web-design-guidelines。只报告此次改动引入、并且可以采取行动的问题，附上改动行数和失败情境。阅读周边代码以了解背景。排除现有问题和样式偏好。
用符合品牌的决定取代通用 AI 样式
根据[品牌指南]、[设计变量]和[参考组件]检查[页面]。找出不符合受众、内容或已批准品牌的设计选择。编辑前先说明建议和理由。保留内容和功能，并评估手机、桌面、焦点和减少动态效果状态。
前后示例：发现、代码修改和验证
以下示例说明可能的修复方式，并非来自已测试项目的报告。
示例一：为图标按钮补上无障碍名称和焦点状态
发现： 关闭按钮没有无障碍名称。
修改前：
<button>
<span aria-hidden="true">×</span>
</button>修改后：
<button
type="button"
class="close-button"
aria-label="关闭咨询面板"
>
<span aria-hidden="true">×</span>
</button>.close-button:focus-visible {
outline: 3px solid var(--focus-ring);
outline-offset: 3px;
}根据项目颜色设定合适的 --focus-ring。
检查： 查看无障碍名称，用键盘启动按钮，并确认面板关闭后焦点移到哪里。
示例二：改善表单标签、验证和错误恢复
发现： 字段用 placeholder 代替标签。
修改前：
<input placeholder="电子邮件">
<p>输入无效</p>修改后，显示无效状态：
<label for="email">电子邮件地址</label>
<input
id="email"
name="email"
type="email"
autocomplete="email"
required
aria-invalid="true"
aria-describedby="email-error"
>
<p id="email-error">
请输入电子邮件地址，例如 name@example.com。
</p>通过应用逻辑更新无效状态和错误关联。公告或焦点处理方式也要经过测试。
检查： 分别提交空白、格式错误和有效资料。测试服务器拒绝输入时是否保留已填写内容。服务器端验证仍须保留。
示例三：让导航菜单在手机和键盘操作中正常运作
发现： 可点击图标没有说明菜单是否展开。
修改前：
<span onclick="toggleNavigation()">☰</span>修改后，显示收起状态：
<button
type="button"
aria-expanded="false"
aria-controls="primary-navigation"
>
菜单
</button>
<nav id="primary-navigation" aria-label="主导航" hidden>
<a href="/zh-cn/services/">服务</a>
<a href="/zh-cn/contact/">联系我们</a>
</nav>在交互逻辑中同步 hidden 和 aria-expanded，并明确处理视口尺寸变化。
检查： 用 Enter 和 Space 打开导航、跟随链接、关闭菜单并调整视口。隐藏链接不应获得键盘焦点。
WAI disclosure 导航示例展示了一种无需 ARIA menu 角色的导航模式。模态抽屉则需要额外处理焦点。
示例四：改善大型清单，同时维持无障碍体验
发现： 结果页面一次呈现所有记录，导致更新成本高。
修改前：
<ul>
{filteredItems.map((item) => (
<li key={item.id}>{item.name}</li>
))}
</ul>分页可以减少一次呈现的记录数量：
const start = (page - 1) * pageSize;
const visibleItems = filteredItems.slice(start, start + pageSize);
<ul>
{visibleItems.map((item) => (
<li key={item.id}>{item.name}</li>
))}
</ul>完整实现还需要分页控制、结果摘要、空状态处理和合适的焦点行为。筛选结果数量改变时，要重置页数或限制页数上限。
这样可以减少呈现工作，但无法解决耗时的筛选算法。
React useMemo 参考说明，依赖项变化时会重新计算，因此搜索查询变化时，它无法避免重新筛选。
检查： 使用具代表性的数据，分别测量筛选和呈现时间。用键盘和屏幕阅读器测试分页。
如果使用虚拟化，也就是只呈现部分项目，还要测试焦点能否保留，以及用户是否能访问尚未呈现的结果。
结合自动化和人工测试验证 AI 建议
使用 ESLint、axe、Lighthouse 和浏览器测试进行互补检查
| 工具 | 检查内容 |
|---|---|
| ESLint 和相关插件 | 已配置的源码规则 |
| axe | 可自动检测的无障碍问题 |
| Lighthouse | 在已记录条件下进行的页面审查 |
| 浏览器测试 | 指定的互动和预期结果 |
检查覆盖范围取决于配置和测试状态。Lighthouse 无障碍评分不包含人工审核。可查看ESLint 文档、axe-core和Lighthouse 评分说明，了解各工具的覆盖范围。
测试键盘操作、屏幕阅读器、缩放和真实设备
测试完整任务，包括失败和恢复流程。
以咨询表单为例，找到页面、提交不完整资料、修正错误并确认成功提交。再用键盘、屏幕阅读器、放大内容和具代表性的设备重复相关步骤。
区分指南检查与完整 WCAG 符合性评估
记录已检查的页面、状态和要求。不要把有限审查称为完整无障碍评估。
请参考W3C 评估指南和 Ulement 的WCAG 2.2 无障碍指南了解更多背景。
以问题数量、任务完成情况和性能数据衡量进展
追踪已确认缺陷、已解决发现和回归问题。
只有在审查范围一致时，才比较问题数量。适用时也要记录任务完成情况和性能数据。
在团队中安全使用网站设计指南技能
安装前检查技能指令、外部来源和权限
阅读套件说明，并了解它需要什么访问权限。
外部指南来源包含的编辑与实施偏好可能和你的项目要求不同。使用 web-design-guidelines 时，应同时检查技能和这些规则。
保护私人代码、凭证和客户资料
遵循组织批准的数据处理安排。
条件允许时使用测试账号和模拟资料。只向代理开放完成审查所需的内容。
记录技能版本和指南来源，确保审查可以重现
记录以下内容：
- 项目 commit 和审查日期。
- 代理和模型。
- 技能版本。
- 指南来源和版本。
- 已检查的文件、网址和状态。
- 测试环境和限制。
只记录技能版本，无法识别不断变化的外部规则。
在 Pull Request 检查中明确人工审批界线
明确 AI 发现只是建议，还是可以阻止合并。
指定人员评估有争议的发现并批准例外。对于可可靠测试的缺陷，使用可重复执行的自动检查。
排查安装、启用和审查质量问题
已安装技能，但代理没有使用
检查目标代理和安装范围。按技能名称提出要求，并指出要检查的文件。
必要时，按照代理说明重新载入技能。
安装失败，或代理无法取得指南
找出失败步骤：安装、访问仓库，还是取得指南。
更改配置前先检查错误。如果使用本地指南副本，请记录其版本。
建议与框架、设计系统或其他技能冲突
要求说明依据和预期结果。
选择符合项目情况的实施方式，并记录合理例外。
审查漏掉问题或出现误报
提供受影响的状态和重现步骤。
要求根据周边代码或浏览器行为核实结果，并记录拒绝无依据发现的原因。
可重复使用的 AI 网站设计审查清单
审查前：范围、来源、权限和基准状态
- 确定文件、网址、任务和排除项目。
- 说明是否允许修改。
- 提供项目规则和限制。
- 核实技能和指南来源。
- 记录项目版本。
- 准备具代表性的内容和测试资料。
合并前：无障碍、响应式行为、性能和人工审批
- 核实发现并检查修复。
- 测试键盘操作、焦点和错误恢复。
- 检查手机布局和放大内容。
- 检查加载、空白、错误和成功状态。
- 运行相关自动检查。
- 测量受影响的性能。
- 记录限制和审查者审批。
常见问题
Web Design Guidelines 技能免费吗？
Vercel 的agent-skills 官方仓库采用 MIT 许可证。代理订阅和模型使用可能另有费用。
这些技能只能用于 Claude Code 吗？
不是。Skills CLI 文档列出了多个受支持的代理，包括 Claude Code、Codex 和 Cursor。具体安装和启用方式取决于代理。
可以用于 React、Next.js、Tailwind CSS 或纯 HTML 项目吗？
可以，前提是代理能够检查相关源码。请按项目实际情况调整框架专属建议。
对于 WordPress 和视觉页面构建器，还要检查最终呈现的页面。
AI 设计技能可以取代设计师或无障碍审查吗？
它可以找出待评估的问题，但无法确认用户需求、批准设计决定或证明完全符合无障碍标准。
没有技术背景的网站负责人也能使用这些技能吗？
可以。请用清楚的语言说明受影响页面、用户影响、建议行动和依据。发布之前，仍应由开发人员评估代码修改。
应多久更新技能并重新审查？
Skills CLI 文档介绍了 skills check 和 skills update 命令。每轮审查前检查更新，并先查看改动再采用。
导航、表单、共用组件、依赖套件或重要内容改变后，应重复相关检查。
为每项接受的发现指定负责人、修复方式和测试。这样，负责网站的团队才能实际使用审查结果。
如果您需要评估现有网站或确定所需工作，欢迎与 Ulement 讨论需求。
文档核对日期：2026 年 10 月 18 日。请参阅上方链接的官方仓库和 Skills CLI 文档。