前言¶
用 Cursor、Claude Code、Codex 這類 AI 編程工具寫前端，速度很快，但頁面上常見的問題也容易一起帶出來：圖標按鈕沒有 aria-label、交互元素去掉了焦點環、動畫沒考慮 prefers-reduced-motion、表單缺標籤、圖片沒寫寬高導致佈局抖動。很多「看起來能用」的界面，放到可訪問性、觸控和性能規則下一查，缺口就很明顯。
Vercel Labs 維護的 web-design-guidelines 正是爲這個問題準備的 Agent Skill。它不教你怎麼畫界面，而是在你說「幫我 review UI / 查一下無障礙」時，按 Vercel 的 Web Interface Guidelines 去審代碼，並給出可直接跳轉的 file:line 結果。規範本身放在遠程倉庫，每次審查前都會重新拉取，規則跟着上游更新。
本文說明它是什麼、覆蓋哪些檢查項、怎麼安裝啓用，以及日常怎麼用。
這是什麼¶
web-design-guidelines 屬於 vercel-labs/agent-skills 官方技能集，作者標註爲 vercel，當前元數據版本爲 1.0.0。它遵循通用的 Agent Skills（SKILL.md）格式，可用 skills CLI 安裝到 Cursor、Claude Code、Codex 等支持該標準的 AI 編程工具中。
一句話定位：按 Vercel Web Interface Guidelines，對指定 UI 代碼做可訪問性、UX 與性能相關合規審查。
官方倉庫對它的描述是：對照 Web 界面最佳實踐審查 UI 代碼，覆蓋 100+ 條規則。觸發場景包括：
- Review my UI
- Check accessibility
- Audit design
- Review UX
- Check my site against best practices
規範正文不在 Skill 目錄裏寫死，而是每次審查前從下面地址拉取最新內容：
https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
核心功能與檢查範圍¶
Skill 的工作流程很直接，官方 SKILL.md 寫明瞭四步：
- 從上述 URL 拉取最新指南
- 讀取用戶指定的文件（或路徑模式）；未指定則先向用戶確認
- 按指南中的全部規則逐項檢查
- 按指南要求的簡潔格式輸出發現項
指南按主題分組，和倉庫 README 對齊的主要類別包括：
- Accessibility：圖標按鈕的
aria-label、表單標籤、鍵盤處理、語義化 HTML、aria-live等 - Focus States：可見焦點、
:focus-visible，禁止無替代方案地去掉outline - Forms：
autocomplete/name、正確的type與inputmode、可點擊標籤、錯誤提示與提交態 - Animation：尊重
prefers-reduced-motion，優先動畫transform/opacity，避免transition: all - Typography：省略號、彎引號、數字等寬（
tabular-nums）等排版細節 - Images：顯式寬高、首屏與懶加載策略、
alt - Performance：長列表虛擬化、避免渲染階段讀佈局、字體與預連接等
- Navigation & State：URL 反映狀態、用鏈接做導航、危險操作需確認或可撤銷
- Touch & Interaction / Safe Areas / Dark Mode / Locale / Hydration 等移動端與主題、國際化、水合安全相關規則
輸出要求高信噪比：按文件分組，使用編輯器可點擊的 file:line，點出問題與位置，非必要不展開長篇解釋。官方示例形態大致如下：
## src/Button.tsx
src/Button.tsx:42 - icon button missing aria-label
src/Button.tsx:18 - input lacks label
src/Button.tsx:55 - animation missing prefers-reduced-motion
src/Button.tsx:67 - transition: all → list properties
## src/Card.tsx
✓ pass
這種形態適合在 PR 前或 AI 批量改 UI 之後做一輪「掃雷」，把模糊的「設計感覺」落成可改的代碼位點。
安裝與啓用¶
該 Skill 隨 vercel-labs/agent-skills 發佈。只裝這一項時，可用 skills CLI（官方文檔與 skills.sh 頁面均提供同類命令）：
npx skills add vercel-labs/agent-skills --skill web-design-guidelines
也可以用完整 GitHub 地址：
npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines
或直接指向 Skill 目錄：
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
若希望一次裝入該倉庫下全部技能：
npx skills add vercel-labs/agent-skills
常用選項（以 skills CLI 文檔爲準）：
-g/--global：裝到用戶目錄，跨項目可用-y：跳過確認，適合 CI--list：只列出倉庫裏有哪些 Skill，不安裝
安裝完成後，Agent 會在任務與 Skill 描述匹配時自動選用。Vercel 文檔說明 skills CLI 可對接包括 Claude Code、GitHub Copilot、Cursor、Cline 等在內的多種 Agent；具體落盤目錄因工具而異（例如項目級常見 .cursor/skills/、.claude/skills/、.agents/skills/ 等），以當前工具文檔與 CLI 提示爲準。
典型用法¶
裝好後，不必背命令名，直接用自然語言觸發即可。官方推薦的說法包括：
Review my UI
Check accessibility
Audit design for src/components/**
Review UX on the settings page components
Check my site against best practices
更穩妥的做法是帶上文件或目錄，減少 Agent 再追問的一輪：
用 web-design-guidelines 審查 app/components 下的按鈕和表單組件，按 file:line 列出問題
對照 Web Interface Guidelines 檢查 src/Modal.tsx，重點看焦點、滾動鎖和 reduced-motion
按 Skill 約定，Agent 應先拉取最新 command.md，再讀你指定的文件，最後按規範輸出。若你沒給路徑，它會先問要審哪些文件。
審查結束後，建議把結果當 checklist：優先修無障礙與焦點、表單、危險操作確認這類高影響項，再處理排版與文案細則。同一組件改完後可以再跑一輪，確認是否變成 ✓ pass。
適用場景與注意事項¶
比較適合這些場景：
- AI 剛生成或大改過一批 UI，需要快速篩一遍常見合規問題
- 做無障礙與 UX 自檢，但暫時沒有完整設計系統 / lint 規則落地
- Code Review 前先讓 Agent 按統一清單掃文件，人再盯業務邏輯
- 希望團隊審查口徑對齊 Vercel 公開的 Web Interface Guidelines
使用時注意幾點：
- 依賴聯網拉取規範。每次審查要能訪問
web-interface-guidelines的 raw 內容；離線或網絡受限時，規則可能拿不到或不是最新版。 - 它是審查流程，不是自動修完所有問題的魔法。輸出偏「指出問題」，具體改法仍要結合組件庫和產品約束。
- 規則偏 Web 前端界面。覆蓋面廣，但不會替代完整的安全審計、視覺設計評審或業務驗收。
- 以一手資料爲準。Skill 行爲以倉庫中的
SKILL.md與遠程command.md爲準；第三方轉載若與官方不一致，以 GitHub 原文爲準。
小結¶
web-design-guidelines 把 Vercel 的 Web Interface Guidelines 變成可自動觸發的 Agent 審查流程：先拉最新規則，再按文件輸出高信噪比的 file:line 發現。對經常用 AI 寫 UI、又擔心無障礙與交互細節被帶偏的團隊，它是一個成本低、口徑清晰的補充環節。
官方地址：
- Skill 目錄：https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
- 技能集倉庫：https://github.com/vercel-labs/agent-skills
- 目錄頁：https://skills.sh/vercel-labs/agent-skills/web-design-guidelines
- 規範源：https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
