名称: 网页设计指南 描述: 审查UI代码以符合网页界面指南。当被要求“审查我的UI”、“检查可访问性”、“审核设计”、“审查UX”或“检查我的网站是否符合最佳实践”时使用。 元数据: 作者: vercel 版本: “1.0.0”
网页界面指南
审查文件以确保符合网页界面指南。
工作原理
- 从以下源URL获取最新指南
- 读取指定文件（或提示用户提供文件/模式）
- 对照获取的指南中的所有规则进行检查
- 以简洁的
文件:行格式输出发现
使用方式
当用户提供文件或模式参数时：
- 从上述源URL获取指南
- 读取指定文件
- 应用获取的指南中的所有规则
- 使用指南中指定的格式输出发现
如果未指定文件，询问用户要审查哪些文件。
核心指南
审查这些文件以符合：$ARGUMENTS
读取文件，对照以下规则检查。输出简洁但全面——牺牲语法以求简洁。高信噪比。
规则
可访问性
- 仅图标按钮需要
aria-label - 表单控件需要
<label>或aria-label - 交互元素需要键盘处理程序（
onKeyDown/onKeyUp） - 动作使用
<button>，导航使用<a>/<Link>（而不是<div onClick>） - 图像需要
alt（或如果装饰性则alt=""） - 装饰性图标需要
aria-hidden="true" - 异步更新（如toasts、验证）需要
aria-live="polite" - 使用语义HTML（
<button>、<a>、<label>、<table>）而非ARIA - 标题层级
<h1>–<h6>；为主内容包含跳过链接 - 标题锚点上使用
scroll-margin-top
焦点状态
- 交互元素需要可见焦点：
focus-visible:ring-*或等效 - 永远不要使用
outline-none/outline: none而没有焦点替代 - 使用
:focus-visible而非:focus（避免点击时的焦点环） - 复合控件使用
:focus-within分组焦点
表单
- 输入框需要
autocomplete和有意义的name - 使用正确的
type（email、tel、url、number）和inputmode - 永远不要阻止粘贴（
onPaste+preventDefault） - 标签可点击（
htmlFor或包裹控件） - 在电子邮件、代码、用户名上禁用拼写检查（
spellCheck={false}） - 复选框/单选按钮：标签+控件共享单个点击目标（无死区）
- 提交按钮在请求开始前保持启用；请求期间显示旋转器
- 错误信息内联在字段旁；提交时聚焦第一个错误
- 占位符以
…结尾并显示示例模式 - 非认证字段上使用
autocomplete="off"以避免密码管理器触发 - 导航前警告未保存更改（
beforeunload或路由守卫）
动画
- 尊重
prefers-reduced-motion（提供减少变体或禁用） - 仅动画
transform/opacity（合成器友好） - 永远不要使用
transition: all——明确列出属性 - 设置正确的
transform-origin - SVG：在
<g>包装器上使用变换，设置transform-box: fill-box; transform-origin: center - 动画可中断——在动画中响应用户输入
排版
- 使用
…而非... - 使用花引号
""而非直引号" - 不间断空格：
10 MB、⌘ K、品牌名称 - 加载状态以
…结尾："加载中…"、"保存中…" - 数字列/比较使用
font-variant-numeric: tabular-nums - 标题上使用
text-wrap: balance或text-pretty（防止孤行）
内容处理
- 文本容器处理长内容：
truncate、line-clamp-*或break-words - Flex子项需要
min-w-0以允许文本截断 - 处理空状态——不为空字符串/数组渲染破损UI
- 用户生成内容：预期短、平均和非常长的输入
图像
<img>需要显式的width和height（防止CLS）- 折叠下图像：
loading="lazy" - 折叠上关键图像：
priority或fetchpriority="high"
性能
- 大列表（>50项）：虚拟化（
virtua、content-visibility: auto） - 渲染中无布局读取（
getBoundingClientRect、offsetHeight、offsetWidth、scrollTop） - 批处理DOM读取/写入；避免交错
- 首选非受控输入；受控输入必须每次击键廉价
- 为CDN/资产域添加
<link rel="preconnect"> - 关键字体：
<link rel="preload" as="font">配合font-display: swap
导航与状态
- URL反映状态——过滤器、标签、分页、扩展面板在查询参数中
- 链接使用
<a>/<Link>（支持Cmd/Ctrl+点击、中键点击） - 深度链接所有有状态UI（如果使用
useState，考虑通过nuqs或类似同步URL） - 破坏性操作需要确认模态或撤销窗口——从不立即执行
触摸与交互
touch-action: manipulation（防止双击缩放延迟）- 有意识设置
-webkit-tap-highlight-color - 模态/抽屉/侧边栏中使用
overscroll-behavior: contain - 拖拽期间：禁用文本选择，设置
inert于被拖拽元素 - 谨慎使用
autoFocus——仅桌面，单一主要输入；避免移动端
安全区域与布局
- 全出血布局需要
env(safe-area-inset-*)以应对缺口 - 避免不需要的滚动条：容器上使用
overflow-x-hidden，修复内容溢出 - 使用flex/grid而非JS测量进行布局
深色模式与主题
- 深色主题中
<html>上使用color-scheme: dark（修复滚动条、输入框） <meta name="theme-color">匹配页面背景- 原生
<select>：显式设置background-color和color（Windows深色模式）
本地化与国际化
- 日期/时间：使用
Intl.DateTimeFormat而非硬编码格式 - 数字/货币：使用
Intl.NumberFormat而非硬编码格式 - 通过
Accept-Language/navigator.languages检测语言，而非IP
水合安全
- 带有
value的输入框需要onChange（或使用defaultValue用于非受控） - 日期/时间渲染：防止水合不匹配（服务器 vs 客户端）
- 仅在真正需要时使用
suppressHydrationWarning
悬停与交互状态
- 按钮/链接需要
hover:状态（视觉反馈） - 交互状态增加对比度：悬停/激活/焦点比其余更突出
内容与文案
- 主动语态：“安装CLI”而非“CLI将被安装”
- 标题/按钮使用标题大小写（芝加哥风格）
- 计数使用数字：“8个部署”而非“八个”
- 具体按钮标签：“保存API密钥”而非“继续”
- 错误消息包括修复/下一步，不仅仅是问题
- 第二人称；避免第一人称
- 空间受限时使用
&而非“and”
反模式（标记这些）
user-scalable=no或maximum-scale=1禁用缩放onPaste配合preventDefaulttransition: alloutline-none而没有焦点可见替代- 内联
onClick导航而没有<a> - 带有点击处理程序的
<div>或<span>（应为<button>） - 图像没有尺寸
- 大数组
.map()而没有虚拟化 - 表单输入没有标签
- 图标按钮没有
aria-label - 硬编码日期/数字格式（使用
Intl.*） autoFocus没有明确理由
输出格式
按文件分组。使用文件:行格式（VS Code可点击）。简洁发现。
## src/Button.tsx
src/Button.tsx:42 - 图标按钮缺少aria-label
src/Button.tsx:18 - 输入框缺少标签
src/Button.tsx:55 - 动画缺少prefers-reduced-motion
src/Button.tsx:67 - transition: all → 列出属性
## src/Modal.tsx
src/Modal.tsx:12 - 缺少overscroll-behavior: contain
src/Modal.tsx:34 - "..." → "…"
## src/Card.tsx
✓ 通过
陈述问题 + 位置。除非修复不明显，否则跳过解释。无前言。