web-design-guidelines

Web 界面指南

何时加载

• 触发条件：UI 审核、无障碍检查、响应式设计审查、UX 最佳实践评估
• 跳过：不涉及 UI 组件的纯后端工作

用于审查 Web 界面的独立指南。审核 UI 代码时请遵循这些规则。

输出格式

按以下格式报告问题：file:line — [RULE_ID] description

示例：src/Button.tsx:12 — [A11Y-01] 图标按钮缺少 aria-label

1. 无障碍（A11Y）

A11Y-01：语义化 HTML

• 操作使用 <button>，导航使用 <a>，数据输入使用 <input>
• 交互元素不得使用 <div onClick> 或 <span onClick>
• 地标区域使用 <nav>、<main>、<aside>、<header>、<footer>

A11Y-02：ARIA 标签

• 所有交互元素都需要无障碍名称
• 只有图标的按钮必须设置 aria-label
• 表单输入必须关联 <label> 或 aria-label
• 图片需要 alt 文本（装饰性图片：alt=""）

A11Y-03：键盘导航

• 所有交互元素都必须可通过 Tab 键访问
• 自定义组件需要正确设置 role、tabIndex 和按键处理程序
• 焦点必须清晰可见（不得在没有替代方案的情况下设置 outline: none）
• 模态框/对话框必须限制焦点范围，并在关闭时将焦点还原

A11Y-04：颜色与对比度

• 文本对比度至少为 4.5:1（大号文本为 3:1）
• 不得仅靠颜色传达含义（应添加图标、文本或图案）
• 确保 UI 在 200% 缩放时仍可使用

A11Y-05：屏幕阅读器

• 动态内容变更需要使用 aria-live 区域
• 加载状态需要设置 aria-busy="true"
• 错误消息需通过 aria-describedby 与输入项关联

2. 性能（PERF）

PERF-01：图像优化

• 使用 next/image 或带有 srcset 的响应式图片
• 指定 width 和 height，避免布局偏移
• 延迟加载首屏以下的图片：loading="lazy"
• 使用 WebP/AVIF，并提供回退方案

PERF-02：包体积

• 不要使用聚合导入：使用 import Button from 'lib/Button'，而不是 import { Button } from 'lib'（或启用 optimizePackageImports）
• 对 CSS 进行树摇：使用 CSS modules 或 Tailwind content 配置（v3）/自动检测（v4）
• 延迟加载路由和大型组件：使用 React.lazy() 或动态导入

PERF-03：渲染

• 避免布局抖动：不要在循环中先读取再写入 DOM
• 谨慎使用 will-change（仅用于已知动画）
• 优先使用 CSS 动画，而不是 JS 动画
• 使用 transform 和 opacity 实现 60fps 动画（仅由合成器处理）

PERF-04：Core Web Vitals

• LCP < 2.5s：优化最大的图片/文本，预加载关键资源
• INP < 200ms：主线程上不得有长任务，延后非关键 JS
• CLS < 0.1：为图片/嵌入内容设置尺寸，首屏上方不得注入内容

3. 响应式设计（RD）

RD-01：移动优先

• 先设置移动端基础样式，再使用 @media (min-width) 设置较大屏幕的样式
• 触控目标最小为 44x44px
• 任何视口下都不得出现水平滚动

RD-02：流式布局

• 字体排版使用 rem/em，不要使用 px
• 使用 clamp() 实现流式排版：font-size: clamp(1rem, 2.5vw, 2rem)
• 优先使用 Flex/Grid，而不是固定宽度
• 内容最大宽度：为提升可读性，使用 max-width: 65ch

RD-03：断点

• 不要针对设备设置断点，而应针对内容设置断点
• 常用断点：640px（sm）、768px（md）、1024px（lg）、1280px（xl）
• 在 320px、375px、768px、1024px、1440px、1920px 下测试

4. 组件模式（CP）

CP-01：表单

• 在字段旁以内联方式显示验证错误
• 移动键盘使用 type="email"、type="tel"、inputmode="numeric"
• 提交过程中禁用提交按钮（防止重复提交）
• 出错时保留表单状态（不要清空字段）

CP-02：加载状态

• 内容区域优先显示骨架屏，而不是加载动画
• 长时间操作应显示进度（进度条优于加载动画）
• 加载期间禁用交互元素
• 在加载容器上设置 aria-busy="true"

CP-03：错误状态

• 始终显示可采取操作的错误消息（提供“重试”按钮，而不只是显示“错误”）
• 不向用户显示技术错误（在内部记录日志，并向用户显示友好消息）
• 为 React 组件树设置错误边界
• 网络故障时启用重试逻辑

CP-04：空状态

• 切勿显示空白页面——提供有帮助的空状态
• 添加行动号召：“目前没有项目。创建你的第一个项目。”
• 谨慎使用插图（它们会增加打包体积）

CP-05：模态框和对话框

• 使用 <dialog> 元素或适当的 role="dialog"
• 将焦点限制在模态框内
• 按 Escape 键或点击背景时关闭
• 关闭时将焦点返回触发元素
• 打开时禁止 body 滚动

5. CSS 实践（CSS）

CSS-01：优先级

• 优先使用类选择器，而非 ID 或元素选择器
• 避免使用 !important（使用优先级或级联层）
• 使用 CSS 自定义属性进行主题设置
• 间距方向保持一致：优先使用 margin-bottom，而非 margin-top

CSS-02：布局

• 一维布局使用 Flexbox，二维布局使用 Grid
• 避免使用 position: absolute 进行布局（仅用于覆盖层）
• Flex/Grid 子元素之间使用 gap，而非外边距
• 全高度布局使用 min-height: 100dvh（而非 100vh）

CSS-03：深色模式

• 使用 prefers-color-scheme 媒体查询
• 将所有颜色定义为 CSS 自定义属性
• 测试两种模式——检查两种模式下的对比度
• 不要只是反转颜色——应专门为深色模式进行设计

6. 安全性（SEC）

SEC-01：内容安全

• 未经消毒处理，切勿使用 dangerouslySetInnerHTML
• 渲染前对用户生成的内容进行消毒处理
• 对带有 target="_blank" 的外部链接使用 rel="noopener noreferrer"

SEC-02：表单和输入

• 所有表单都要启用 CSRF 防护
• 限制表单提交频率
• 同时在客户端和服务器端进行验证

7. 国际化（I18N）

I18N-01：文本

• 不要硬编码字符串——使用 i18n 库或常量
• 支持 RTL 布局：使用 logical properties（使用 margin-inline-start，而非 margin-left）
• 不要截断文本——设计必须能容纳文本长度增加 40%
• 在 <html> 标签上使用 lang 属性

审查清单

审查文件时，按以下顺序检查（先检查 CRITICAL）：

1. CRITICAL：A11Y-01、A11Y-02、SEC-01——语义化 HTML、ARIA、XSS 防护
2. HIGH：PERF-04、A11Y-03、CP-01——核心 Web 指标、键盘操作、表单
3. MEDIUM：RD-01、CSS-02、CP-02、CP-03——响应式设计、布局、加载和错误
4. LOW：CSS-03、I18N-01、CP-04——深色模式、国际化、空状态