设计检查清单

一页检查清单，写给构建 Web 产品界面的人和编码 agent。开工前、开发中、交付前都可以对照。它默认产品已经有自己的令牌和组件，讲的是怎么用好它们。

MUST 只用于用户能察觉的缺陷，此外没有别的 MUST。SHOULD 是起点，不是限制：只要作品因此更好，就可以偏离，说明理由即可。标了 （已检查） 的条目由本仓库的测试自动保证，末尾的表格写明是哪个测试。其余条目要你在真实浏览器里亲眼确认。

ranui 的实现适配层把这些条目对应到 ranui 的令牌、层叠层级和组件细节上。

开工前

改动页面呈现的内容之前，先回答三个问题；如果是新建或重构一个页面或区域，把答案写下来：

1. 读者一进来需要看到什么？
2. 还有什么必须同时可见，前者才说得通？
3. 他们接下来要做什么？

一个页面只有一个主要模型，每个区域只有一个主要操作。按读者要回答的问题选布局：比较用表格，识别并打开用列表，看一个对象的状态用分区详情，推进阶段用步骤流，回看发生了什么用时间线，连续文本用文档。身份和状态放在最前，主要操作放在标题区，反馈放在触发它的操作旁边。

衡量每一步选择有多难，而不是要点几次：好几步都不用动脑，胜过一个挤满选项、每个都要想一想的界面。

新建页面或区域时，先把两三个方向放在同一处并排比较（一个切换控件、一块画布），再定下其中一个；比较的应当是真正还没定的东西：布局、交互、文案或外观。

先说清这个界面属于哪种模式，它决定页面能花多少表现力。工具（仪表盘、设置、编辑器）和文档（文档站、文章、更新日志）把表现力花在精确和克制上，用读者已经熟悉的模式；用来说服的页面（落地页、定价页）可以亮出鲜明的立场，由一个让人记住的标志性想法来承载，而不是让好几个效果争抢同一处注意力。模式看的是这个界面，不是整个产品：一个工具的落地页属于说服，它的文档属于阅读。

五秒测试

出自 Steve Krug 的《Don't Make Me Think》：把首屏给别人看五秒，然后遮住，问他这是什么页面、给谁用、接下来会做什么。答不上来，就说明层级失败了，细节做得再好也没用。

• 页面名称是首屏上唯一一个可见的标题，320px 和桌面宽度都一样。（已检查）
• 只有一个东西领先。眯眼看：屏幕应该只剩两三块大小分明的色块。
• 主要操作是首屏上的一个真按钮或链接，用它要做的事命名。

后备箱测试（trunk test）

同样出自 Krug：假设读者被塞进汽车后备箱，随便扔到某个页面上。不用滚动，他们 MUST 能回答：

• 这是哪个网站？ 有一个链接回首页的站点标识。（已检查）
• 我在哪一页？ 有一个页面标题，和他们点进来的链接对得上。（已检查：唯一标题）
• 主要栏目有哪些？ 主导航在页头，或在抽屉里点一下就能看到。（已检查）
• 我在栏目里的哪个位置？ 当前栏目和页面有标记，而且不只靠颜色。（已检查：aria-current）
• 怎么搜索？ 网站有搜索时，搜索入口可见，或点一下就能打开。（已检查）

视觉语言

• 强调是一笔预算：颜色、字重、徽标和投影要少用，用了才有意义。
• 先用间距、对齐和字重，再考虑边框、填充或阴影。留下的每条边界都要说得出它的作用。
• 间距取自 4px 尺度，间距越小关系越近：一个控件内部 4px，相关控件之间 8px，分组之间 16px，区域之间 24–32px。隐藏的内容不留空隙。（已检查：不在尺度上的间距）
• 颜色取自令牌，两种主题下都成立；状态从不只靠颜色表达。（已检查：裸颜色值和只适配浅色的回退值）
• MUST：文字在真实组合上、两种主题下都达到 WCAG AA 对比度（4.5:1，大号文字 3:1）。首次绘制就跟随读者的主题，不会先闪一下浅色再变暗。
• 嵌套圆角按 内圆角 = 外圆角 − 内缩 计算。结果不超过 2px 时，给内层形状单独的圆角，或者去掉这层内框。

• 给对齐线命名，让标题、行、操作和空状态都落在线上。顺着页面往下看文字块的左边缘：应该只有两三个位置，而且是有意复用的。

• 字号种类要少，彼此拉开差距。正文每行约 45–75 个字符，行高至少 1.5；读者需要读的文字不小于 12px。（已检查）
• 标题上方的空白要比下方多，这样它才和它引出的内容连在一起。**（已检查）**标题用 text-wrap: balance 折行，段落用 text-wrap: pretty。
• 浏览器自己画的部分同样属于设计：文字选中色、输入光标、焦点环、滚动条，以及表格里的数字（tabular-nums）。都从 token 取值。
• 多种文字混排时，拉丁字体放在前面，中日韩或阿拉伯字体作为后备放在后面；给每段内容标上 lang；中文、日文、韩文的正文行高要比拉丁文更大（约 1.7–1.8）。拉丁衬线字体没有汉字字形，要搭配一个中文衬线字体。
• 装饰是一个决定，不是默认值。当标题上方的小标签、渐变、光晕，或者包住一切的卡片出现时，确认它在这个页面上有作用；如果只是填空，就去掉。

布局

• MUST：320px 下页面不横向滚动；宽表格和代码在各自的容器里滚动。（已检查）
• MUST：加载时、状态变化时、组件晚注册时，都不发生位移。会晚加载或晚出现的东西要预留位置。（已检查：加载时的位移，仅 Chromium）
• MUST：文字、标题、数值和导航在首次绘制时就可读，不依赖脚本，也不依赖动画。（首页已检查）
• 组件的盒子要装下它画出的所有东西。旋转、扇形展开或偏移的部分都留在盒子里。
• MUST：文字和数值不被裁切。确实需要截断时，完整内容仍然拿得到（提示框、展开行或详情页）。
• 操作不靠悬停也能触达，在任何宽度下都能触达。能点的东西静止时就该看起来能点：触屏上没有悬停来提示它。

交互

• MUST：每个操作都能用键盘、触摸和指针完成。焦点始终可见，顺序与阅读顺序一致，浮层关闭后焦点回到触发它的元素。（已检查：重点页面前几个 Tab 位置的焦点可见）
• MUST：触摸和指针目标至少 24×24px，或者间隔足够，使每个目标周围 24px 的圆不碰到相邻目标（WCAG 2.5.8）。正文里的行内链接不受此限。（已检查）
• MUST：输入永不丢失。草稿、焦点、光标和阅读位置在更新、失败和动画之后都保留。不要替换用户正在输入的输入框。
• 按用户习惯的方式接收输入（电话号码里带空格、粘贴进来的值末尾多一个空格），而不是直接报错；只问任务真正需要的信息。
• 校验结果显示在字段旁；一次操作只提交一次；确认成功后才显示成功；失败时保留全部输入，并说明怎么恢复。
• 每个异步结果都对应发出它的那次请求，晚到的结果绝不覆盖较新的结果，后台更新也绝不移动焦点。
• 模态框只用于简短的确认，或任务缺了它就无法继续的一个回答，不是用来导航的地方；临时的上下文放进弹出层，同一对象的几个平级视图用标签页，另一项任务放到它自己的页面。
• 模态对话框在关闭前把焦点留在框内。输入法还在组字时，按 Enter 不提交。
• 选中和悬停看起来不一样。链接用于跳转，按钮用于改变状态。

动效

• 反馈（悬停、焦点、按下）在 0–100ms 内完成。进入用 250–400ms，减速且不越过目标；离开用 150–200ms，加速。主题切换不加动画。
• 控件和内容停到位时不回弹、不用弹性缓动；用来说服的页面可以留一个表现性的瞬间。
• 优先用 transform 和 opacity；相邻元素用 transform 让位（FLIP）。永远不要对布局属性（height、padding、max-height、top、left）做动画，它会让页面每帧重排；也不要用 transition: all。
• MUST：开启减弱动效时，没有东西移动或持续运行，最多是一次短暂的淡入淡出。（已检查）
• 动效可以被打断，并能干净地反向播放。要看录屏，不要只看静态截图。

文字

还是 Krug 的话：先删掉一半的字，再删掉剩下的一半。

• 先做到不言自明，再考虑如何解释：用读者本来就用的说法给东西起名，沿用惯例，除非新做法明显更好。一个取巧的名字，每次读到都要让人多想一下。
• 操作按它要做的事命名（“发送邀请”，而不是“提交”）。不写欢迎语，也不写复述布局的说明。
• 保留能带来决定、约束或后果的文字：无障碍名称、字段标签、单位、错误和风险提示。
• 错误信息说清发生了什么、接下来怎么做，并放在出错的地方旁边。
• 不要用编造的内容填空：没人要的章节、统计数字、图标或文案。看起来空的地方是布局问题，不是内容问题。
• 说产品自己的话。空泛的营销词（赋能、无缝、下一代）和用来制造节奏的破折号，读起来像没人写过的文案。
• 英文用句首大写。试一试长文本、大数字，以及产品支持的每一种语言。

验证一次改动

• 在真实浏览器里打开改动，两种主题、320px 和桌面宽度都看，并用键盘走一遍。把改动涉及的状态都试一遍：悬停、焦点、禁用、加载、空状态、错误。
• 看截图下结论，不要看自己写的代码：你会把自己的意图读进代码里。
• 页面结构有变化时，跑一遍五秒测试和 trunk test。
• 报告时分清哪些是观察到的、哪些只是推断、哪些没法检查。不要把自己的检查称为验收。
• 看三个人实际试一遍这个任务，比任何评审都更快找到最严重的问题。先修最严重的，用能消除它的最小改动。
• 给发现的问题排优先级，让读者先修对的那个：P0 让人用不了（输入丢失、文字看不清、操作够不着），P1 违反了 MUST，P2 没有理由地偏离了 SHOULD，P3 属于打磨。
• 每条修改写成具体数值，不写形容词：“48px 改为 clamp(40px, 6vw, 72px)”，而不是“再大一点”。

检查覆盖了什么

原文（英文）：design/DESIGN.md。本页是译文，与原文不一致时以原文为准。