实习日志 / 中文 / 界面重构 / 把一本设计书拆成 Agent 能执行的规则：Refactoring UI 的取舍

把一本设计书拆成 Agent 能执行的规则：Refactoring UI 的取舍

8 月底，Northwind 的两个前端已经由好几个 Agent 轮流写过。代码能跑，界面却越来越像拼起来的：颜色和圆角直接写在各个组件里，圆角从 7px 一路写到 15px，按钮有方有圆，开发过程里的占位文案也留在了页面上。每次提意见，只能说"这里不好看"，Agent 改完，下一个功能又是老样子。

问题出在没有规则。人能凭审美做取舍，Agent 只能照着写下来的东西做。于是我把 Adam Wathan 和 Steve Schoger 的《Refactoring UI》从头读了一遍，9 章 42 节逐节过，目标很具体：哪些原则能写成仓库前端规范里的条款，让 Agent 照着做、让 review 能查出来；哪些不能。规范只记原则的提炼，不放原书的文字。

三种去处

每一节最后落到三种去处之一。

写成条款。 能被代码审查或 CI 检查的，写进仓库治理 skill 的前端设计一章。比如"组件样式里禁止出现刻度外的裸值"，看一眼 diff 就知道有没有违反。

一次性设计。 有些原则只在定调的那一刻有用，比如界面的个性、Workbench 要不要做成密集布局、扁平风格怎么做出层次。这些不适合写成每次都要读的条款，在需要的时候和我一起商量、定下来就够了。界面个性后来定成了"燕麦色高领毛衣配一块好表"，规范里只留一条：设计气质之前先商讨调性，已经定了的，Agent 就不必再读这一段。

只留出处。 学习方法论、选照片、给营销页加插画这类内容，和这个仓库的场景无关，只在文末的出处区留名。

最有用的一条：所有取值来自刻度

全书对我们最有用的是第 1 章的"限制选择"。12px 还是 13px 这种争论毫无意义，正确的做法是预先定一套受限的系统，从系统里挑，不从连续的数值里挑。书里列了应该系统化的清单：字号、字重、行高、颜色、margin、padding、宽高、阴影、圆角、边框宽、透明度。

这一节成了前端规范的总则，统摄后面所有视觉取值：

上面清单里的值一律取自预定义的 CSS 变量刻度，组件样式里不许出现刻度外的裸值，不许逐像素手调；
间距刻度以 8px 为基数生成，紧凑处允许 4px，并且相邻两档至少差 25%；
字号用手工刻度（12、14、16、18、20、24、30、36、48），用 px 或 rem 定绝对档位，不用 em 建立元素之间的比例；
新增颜色一律用 HSL 书写，灰阶 8 到 10 档，主色和每种语义色各 5 到 10 档，一次定完，不许用 lighten()、darken() 这类函数临时生成色阶；
全站圆角风格统一，方角和圆角混用视为缺陷。

第 2 条里有一处冲突要调和。仓库原有的条款写的是"8px 间距基数"，书里说的是间距的感知是相对的，小值处差 2px 是巨变，大值处差 2px 无感，所以相邻档要差 25% 以上。两条其实管的是不同的事：8px 基数管"一个值能不能用"，25% 管"刻度怎么生成"。取 4、8、12、16、24、32、48、64，两条同时满足。

第 3 条的道理来自书里的一个例子：大屏上 45px 的标题配 18px 的正文，到小屏上合适的关系可能是 24px 配 14px，比例从 2.5 倍变成了 1.7 倍。比例本身跨断点就不恒定，用 em 把它们绑在一起，只会把错的比例固化下来。

能查的才写成条款

剩下的章节，取舍的标准是同一个：能不能在 review 里指着一行代码说它违反了。

层级靠减法。 主元素不够突出时，优先降级它的竞争者，比如把 inactive 的导航项变灰，去掉次要元素的背景和边框，不再给主元素继续加码。按钮分三级，实心、描边、链接样式，每个视图最多一个实心主按钮；删除这类危险操作不自动变成红色大按钮，只有在确认对话框里，它才是那一步的主动作。

Label 是最后手段。 邮箱、电话、金额这种一望即知的数据不加 label；能合并就合进值里，"12 left in stock" 比 "In stock: 12" 好；必须加 label 时它是配角，字更小、对比更低。但这一条留了一个例外：查阅型的详情页。Workbench 的案件详情就是员工来扫字段值的地方，label 反而要能被扫读。

间距表达归属。 组之间的距离必须大于组内的距离：label 贴近它的输入框，章节标题贴近下文、远离上文，列表项之间的距离大于项内的行距。等距漂浮制造了归属的歧义，再用分隔线去补，就是这条要防的事。

宽度按内容定。 内容需要多宽，就给多宽的 max-width，不为了填满屏幕把表单和正文拉宽；侧栏这类结构元素给固定宽度，主区吃剩下的空间。

语义标签和视觉层级分开。 标签按文档语义、无障碍和 SEO 选，样式按视觉层级定。h1 不必是页面上最大的字。

状态不只靠颜色。 这一条仓库里原来就有，书里补了一句：图表里区分多条线，用同一种颜色的明暗，不用不同色相，色盲用户靠明暗仍然能分辨。语义 tag 默认用浅底深字，同一色相的浅档做背景、深档做文字，对比达标，视觉也更轻。

行高要分情况。 原来的条款是一刀切的"行高 1.4 到 1.6"。书里说行高和行长成正比、和字号成反比，大标题用 1.5 的行高会松散难看。条款于是改成正文 1.4 到 1.6，标题 1.1 到 1.3。

和这个产品贴得最近的一节

全书和 Northwind 的业务最直接相关的，是第 7 章里讲用户上传内容的那一节。报案人会上传事故照片，员工要在 Workbench 里看这些照片，而用户上传的图完全不受我们控制。

条款写成两道防线。第一，固定容器加居中裁剪，用 object-fit: cover，不按原始宽高比直排，否则版式会被撑破。第二，浅色照片贴在浅色背景上会融掉，用一圈极淡的内阴影：

box-shadow: inset 0 0 0 1px hsla(0, 0%, 0%, .1);

不用实线边框，实线会和图片本身的颜色打架，内阴影几乎没人察觉，却有效。

一条防 Agent 的原则

第 1 章还有一条"悲观设计"：界面上不暗示还没准备实现的功能，评论功能还没有附件，就别画附件区，永远先做能发布的最小可用版本。

这条原则原本是讲设计节奏的，放在我们这里有一个书里没想到的用处：它能有效挡住模型把开发过程中的东西写进前端。"即将上线""此功能开发中"这类占位文案，和一个点了没反应的按钮，都在这条的范围里。这一条写成了交互原则里的条款。

留给人的部分

也有几条是我有意留给自己的。重量和对比的平衡，加粗会增加视觉重量，细线条太弱时要加重来补偿对比，这类调整只在明确要优化界面的时候才做，Agent 平时不用管。装饰性的彩色边条、背景的低对比纹理，作为可以用的技巧写进去，算不上约束。元素叠放制造层次这一条，营销页的味道比较重，在一个理赔工作台里用不用，我当时没有定论，留着再讨论。

取舍之后，这些条款并进了仓库治理 skill 的前端设计一章，按"总则、常驻约束、触发式和一次性设计"三层组织：总则统摄所有取值，常驻约束是 review 和 CI 能查的，触发式条款自带触发条件，没触发时不约束日常改动。几天后报案端的视觉规范和前端重构，都是在这套条款上做的。