Claude Code 统一设计规范：集中式 UI 组件与一致性维护指南

用编码代理写前端代码时，界面风格走样几乎是必然的：同一个应用里出现好几种字号，按钮在不同页面长得不一样，下拉菜单、悬浮浮层各写一套配色和尺寸。问题不在于代理能力不够，而在于代码库里本来就没有可复用的标准——代理是模式识别器，它会照着已有代码的模式继续写，如果既有模式就是「没有模式」，它就会为每个新功能各自发明一套设计。本文讲的是如何用 Claude Code 这类编码代理把 UI 元素收敛到一个集中目录，并通过重构、复查和评审规则把一致性长期维持住。适合已经用代理开发了一段时间、发现界面开始发散的前端或全栈开发者。

准备工作

开始之前先确认几件事，否则重构会做得很痛苦。

一个可运行的代码库：应用能本地启动，页面能正常渲染。重构过程中需要反复对照页面外观，跑不起来就没法验证。
版本控制与分支策略：重构会大面积改动文件，必须能按元素分批提交、分批合并。建议每个元素（字号、按钮、颜色……）单独开一个分支或 PR，出问题可以单独回滚。
代理的规则文件：项目里应当已经有代理会读取的说明文件，例如 CLAUDE.md、agents.md 之类。后面所有「不许自己造组件」的硬性约束都写在这里。
一个代码评审代理：如果你还没有固定的评审流程，建议先建一个。它会在后面承担拦截违规 UI 元素的职责。
截图能力：重构前后需要对比页面外观。让代理生成带截图的 HTML 报告是最省事的做法，前提是本地能跑起页面并截图。

另外要有心理预期：这是一次大范围重构，不是改几个文件就完事。分批推进、每批验证，比一次性全量替换安全得多。

操作步骤

第一步：确定集中目录的位置

先决定共享 UI 目录放在项目结构的哪个位置。原则是让代理在写任何新组件时都能自然看到它，而不是藏在深层嵌套里。常见做法是在源码根目录下建一个语义明确的目录，例如 src/ui/ 或 src/components/ui/，具体路径取决于你现有的目录约定。

这个目录里最终要容纳的东西包括：

字号与字体定义
按钮
下拉菜单
颜色
其他会重复出现的交互元素，例如悬浮浮层、弹窗、标签

第二步：用提示词启动分批重构

不要一次性要求代理「统一整个应用的 UI」，那样它会同时改动几百个文件，你根本无法审查。正确的做法是明确告诉它分批做，并且第一批只处理一个元素。可以用类似下面这样的提示词：

通读我的整个代码库，我要开始统一所有设计元素。

我想为所有 UI 元素建立一个集中目录，包括按钮、下拉菜单、颜色、字体等。
请开始做统一化的工作。

这是一次大范围重构，所以要一步一步来，拆成多个 PR。

先从字号开始，确保我们在共享 UI 目录里定义了一组经过确认的字体和字号。
这一步完成之后，再继续处理按钮、下拉菜单、颜色等等。

共享目录放在应用目录结构中最合适的位置。

同时要向编码代理明确说明：以后实现任何新东西时，都必须从这个目录里挑选 UI 元素，
不允许在正在实现的代码里直接新写一个元素。必须从这个统一目录里选。

在代码库里把这一点写得极其清楚，避免代理犯错、在应用各处自造设计元素。
我们要遵循 DRY 原则，把所有东西统一到一个位置。

提示词里有两个关键点值得单独强调。第一是分批：先字号，再按钮，再下拉，再颜色。第二是禁止自造：代理必须从集中目录里选，不能就地新写。第二点如果写得含糊，代理会理解为「尽量复用」，而不是「必须复用」，结果就是老问题照旧。

第三步：让代理产出前后对比报告

代理开始跑之后，会翻出代码库里大量需要修正的地方。这时候不要直接看 diff——diff 看不出界面到底变好还是变坏。让代理生成一份 HTML 报告，里面放上改动前后的页面截图，逐页对比。

这样做的好处很直接：你只需要滚动浏览报告，判断界面是否可以接受，然后把意见反馈给代理。不需要在几十个文件的改动里逐行推敲样式值。发现哪里不对就让它改，改完再看一遍报告。

第四步：确认后合并，再进入下一个元素

代码和界面都通过之后，可以让代理自主合并到开发环境，然后开始处理下一个元素。整个流程是循环的：

选定一个元素（例如按钮）
让代理重构到集中目录
生成前后对比报告
人工确认界面
合并
换下一个元素

第五步：每个元素合并后做一次独立复查

这一步很容易被跳过，但很重要。每完成一个元素并合并之后，另起一个全新的代理会话，让它专门检查还有没有漏掉的元素。比如按钮全部统一并合并之后，开一个新代理，让它通读代码库，找出所有仍然没有使用集中目录按钮的地方，并修掉。

为什么要另起会话？因为同一个会话里，代理带着前面重构的上下文，容易默认「我已经处理完了」，从而漏掉边角。新会话没有这层预设，检查更彻底。代理在第一轮漏掉元素是常见现象，二次清理能显著提高覆盖率。

第六步：把规则写进代理的说明文件

重构完成只是开始，接下来要防止它重新发散。在代理会读取的说明文件里（例如 CLAUDE.md、agents.md）写死一条规则：永远不允许发明新的设计实现，必须从集中 UI 目录中选取。

这条规则要写得足够绝对，不要用「优先」「尽量」这类词。同时，规则文件本身也要定期检查，确保它没有被后续的改动冲淡。

第七步：在评审代理里加一条 UI 检查

即使规则文件写得很清楚、集中目录也建好了，代理仍然会时不时想自己造一套设计。这是目前代理的固有弱点，只能靠流程兜住。

做法是更新代码评审代理的提示词，让它额外检查：是否存在不来自集中 UI 目录的 UI 元素。发现就标记出来。

这里有一个细节值得注意：评审代理通常会把这类问题归为 P2，也就是「不严重」。但设计一致性属于会累积的问题——今天放过一个自造按钮，明天就是十个，最后整个应用又回到起点。所以要在评审提示词里明确要求把它标为更严重的问题，当场修掉，而不是留到以后。

一个完整示例

下面把整个流程串一遍，以「统一按钮」为例。

起点状态：应用里有若干页面，按钮样式各不相同——有的圆角大、有的直角，有的用主色填充、有的用描边，尺寸也不统一。

第一步，确认目录。假设共享 UI 目录定为 src/ui/，里面已经有字号定义（上一批重构的产物）。

第二步，发起重构。给代理的提示词聚焦在按钮上：

现在处理按钮。

请通读代码库，找出所有按钮实现，把它们统一到 src/ui/ 下的按钮组件。

要求：
- 归纳出当前所有按钮的变体（主要、次要、危险等），在集中目录里定义清楚
- 所有页面改为引用集中目录的按钮组件
- 不允许保留任何就地定义的按钮样式
- 完成后生成一份 HTML 报告，包含改动前后每个相关页面的截图对比

第三步，看报告。代理跑完后产出一份 HTML 报告。滚动浏览，重点看：按钮尺寸是否统一、主次层级是否清晰、危险操作是否有一致的视觉标识、间距是否协调。发现某个页面的按钮被改得过于突兀，直接反馈让它调整。

第四步，合并。界面确认无误后，让代理合并到开发环境。

第五步，独立复查。开一个全新的代理会话：

通读整个代码库，检查是否还有任何按钮实现没有使用 src/ui/ 下的集中按钮组件。

把找到的每一处都列出来，并改为使用集中组件。

不要新增任何按钮样式。

这一步通常会再揪出几处漏网的按钮——可能是某个弹窗里的、某个表格行内的、或者某个较早写的页面里的。

第六步，固化规则。确认 CLAUDE.md 里已经有类似这样的条目：

## UI 规则

- 所有 UI 元素必须来自 src/ui/ 集中目录。
- 严禁在任何其他位置新写按钮、下拉、浮层、颜色或字号。
- 需要新的 UI 元素时，先在 src/ui/ 中实现，再从调用处引用。
- 提交前自查：本次改动是否引入了集中目录之外的 UI 实现？

第七步，评审拦截。在评审代理的提示词里加上：

额外检查：本次改动是否引入了不来自 src/ui/ 集中目录的 UI 元素？

如果有，标记为高优先级问题，不要降级为 P2。
理由：设计不一致会累积，必须当场修复。

之后每加一个新功能，这套机制都会自动生效：代理写代码时受规则文件约束，提交时受评审代理拦截，你只需要偶尔抽查。

注意事项

重构需要时间，但可以压缩。整个代码库的统一化不是几分钟的事。分批推进、让代理连续作业的情况下，视代码库规模，一两天内完成是现实的目标。前提是每一批都验证、都合并，而不是攒到最后一起处理。
代理会漏元素。第一轮重构几乎不可能覆盖全部。每个元素合并后都要另起会话做一次独立复查，这是流程的一部分，不是补救措施。
规则写清楚也不保证遵守。即使说明文件里写得极其明确、集中目录也建好了，代理仍然有自造设计的倾向。所以人工抽查不能完全取消，评审代理的拦截也不能省。
不要低估评审代理的定级倾向。评审代理默认会把自造 UI 元素当成 P2。必须在提示词里明确要求提高定级，否则这类问题会一直被放行。
一致性是持续工作。集中目录建好之后，仍然需要定期重构和检查。代理时代，持续重构不是可选项，而是维持代码库可维护性的常规动作。
新元素要先进目录。确实需要新的 UI 元素时，正确顺序是先在集中目录里实现它，再从调用处引用；而不是在调用处直接写，事后再搬。
涉及具体工具的价格、配额、版本与可用性，请以官网当前信息为准。本文讨论的是工作方法，不涉及具体套餐或额度。