sAIgnals 新文：如何保持 AI 生成的 UI 一致：面向编码代理的实用设计系统 让 AI 生成的 UI 与现有页面保持一致：真实的 Newsletter 重设计、设计系统规则、浏览器检查，以及一个免费的 Markdown 模板。https://saignals.buzz/articles/consistent-ai-generated-ui-design-system…

保持 AI 生成的 UI 一致：面向编码代理的实用设计系统 | sAIgnals

来源：https://saignals.buzz/articles/consistent-ai-generated-ui-design-system 内含免费模板 · 跳转到下载 ↓ (https://saignals.buzz/articles/consistent-ai-generated-ui-design-system#practical-resource)

如何保持 AI 生成的 UI 一致：面向编码代理的实用设计系统

新页面能用。表单能提交。排版看起来是经过斟酌的。然而把它放到产品其余部分旁边，感觉就像是另一个网站的页面。

这就是我们在 sAIgnals newsletter 页面上遇到的问题。第一版沿用了网站的深色配色和字体，但它过大的 hero、宽松的间距以及独立的收益卡片，让它与 News 和 Articles 页面呈现出不同的节奏。要求一个“更精致“的页面，得到的是局部合理的结果，却并没有让产品更连贯。

本指南展示了我们在 2026 年 11 月 1 日所做的修正：识别现有模式，将其记录在一份小型设计文档中，把该文档接入仓库指令，然后在浏览器中验证结果。这是一个关于单次界面变更的案例研究，不是模型对比，也不是重设计提升了注册量的证据。

文末提供可复用的设计系统文档与 UI 审查清单。该工作流面向在现有仓库中工作的编码代理，无论你使用哪款助手。

从相邻页面开始

在让代理实现某个屏幕之前，先挑选两三个能代表产品现有样式的视图。命名它们的源文件，并检查其渲染输出。一个组件可能类名都正确，但在特定宽度下仍会产生别扭的布局。

对 sAIgnals 来说，有用的参考是 News 和 Articles 页面、共享的导航以及全局样式表。它们确立了紧凑的页面标题、克制的表面、细边框、技术性标签，以及按行或有意为之的面板来组织内容的布局。

newsletter 已经共享了配色。不匹配之处在于层级与构图：高达 54 像素的标题、带内边距的推广 hero，以及分散在多个区块中的重复说明。换一个强调色解决不了这个问题。

早期的 sAIgnals newsletter 页面有一个大的推广标题，以及 signup hero 下方一个独立的预览面板 修改前：newsletter 使用了网站的配色，但它大的 hero 和独立的预览面板营造出不同的节奏。截图：sAIgnals，2026 年 11 月 1 日。 在动手修改之前，先给代理一个有边界的调查任务：

`` 检查目标页面和两个有代表性的相邻页面。 阅读共享样式表以及这些视图使用的组件。

列出：

• 现有的 token 和可复用组件；
• 层级、间距和交互上的差异；
• 让这个页面融入所需的最小改动。

引用相关文件和选择器。将现有的无障碍问题视为需要修复的缺陷， 而不是值得照搬的模式。 ``

这会产出一份扎根于仓库的实现简报。关于选择任务上下文的更通用方法，可参见我们的上下文工程指南 (https://saignals.buzz/articles/context-engineering-claude-code-codex)。

让代码、设计规则和任务指令各司其职

设计文档最有用的时候，是它解释了样式表本身无法表达的决策。

我们的文档位于 docs/design-system.md。确切的文件名是一种项目约定；创建这个文件名的文件并不会自动让每个助手去读它。请在你的环境所使用的指令机制中放入明确的指引，并验证代理确实查阅了它。

在我们的仓库中，我们把这条规则加入了 AGENTS.md：

对于网站 UI 变更，请阅读并遵循 docs/design-system.md。 复用现有的样式 token 和共享页面模式。当有意修改共享设计规则时， 更新该文档，并验证桌面端和移动端布局。

指引要保持简短。在多个指令文件中重复整份文档，会制造出规则产生分歧的更多地方。各工具有自己的加载和作用域规则；例如，Claude Code 文档说明了项目指令与导入是如何加载的 (https://code.claude.com/docs/en/memory)。请检查你的环境，而不是假设一个文件名在所有地方表现一致。我们的仓库指令指南 (https://saignals.buzz/articles/agents-md-codex-claude-code-copilot) 对这一区别有更详细的说明。

写出能解决真实取舍的规则

“让它现代而一致“几乎把每一个实现决策都留白了。一条有用的规则要指明一个取舍点，并给代理一种解决它的办法。

对本站而言，文档记录了：

• 页面层级： 普通视图以现有的 .view-heading 模式开头。大型 hero 需要一个与页面角色相关联的理由。
• 表面： 复用深色面板和边框 token。默认保持直角；避免为单个视图新增一套发光或阴影体系。
• 排版： 正文使用现有的无衬线字体族，短标签、元数据和技术标记使用等宽字体。
• 构图： 一系列内容使用分隔的行；将一项独立的任务或对象归入面板。
• 交互： 保留可见标签、键盘焦点、原生输入行为，以及加载、成功和错误消息。
• 响应式行为： 考虑侧边栏的宽度，并在决定列于何处折叠之前测试真实内容。

这些是 sAIgnals 的决策，不是放之四海皆准的好设计规则。面向消费者的商店或轻松有趣的游戏可能需要不同的视觉语言。规则要从你正在扩展的产品中提取。

让 token 值在代码中保持权威

设计文档可以解释 cyan 表示主操作或激活选择。而实际的颜色值应始终以样式表为来源。CSS 自定义属性 (https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties) 让声明可以通过 var() 引用共享值；它们并不决定一个颜色何时合适。

例如，这些是现有的 sAIgnals 值：

:root { --panel: #10141b; --line-strong: #394252; --text: #edf2f7; --muted: #9aa7b7; --cyan: #67e8f9; }

不要把第二套略有不同的配色粘贴进页面组件。如果文档为了可读性包含了一张 token 表，那么在底层 token 被有意修改时也要更新它。指向源文件的引用，比维护一份罗列每条 CSS 声明的重复目录更容易。

一张四步示意图串联起：检查现有屏幕、记录设计规则、实施一次有边界的改动、检查浏览器结果 该文档把现有的产品决策与实现和审查连接起来。它不能替代可复用组件或浏览器检查。示意图：sAIgnals。

Newsletter 改动：我们实际做了什么

我们用普通内容视图所使用的同一种页面标题模式，替换了推广 hero。在宽屏上，signup 和预览现在并排而列；空间受限时则变为单列布局。

signup 面板将一项任务归为一组：选择频率、输入地址、请求简报。月度和周度选项保留了原生 radio 输入，并有更明显的选中状态。表单默认仍为月度。

预览是一个编号序列：值得了解的变更、一个值得尝试的工作流、一个值得探索的仓库。每一行都配有相关链接。投递与订阅管理的细节放在一个紧凑的页脚中，而不是再来一组收益卡片。

功能组件被复用了。这次修改改变了页面构图和样式；它没有替换订阅接口、确认流程或分析事件。页面专属的表单样式被限定在 .newsletter-page 之下，因此首页的 signup 不会继承更大的频率控件。

修改后的 sAIgnals newsletter 使用了紧凑的页面标题、左侧的 signup 面板，以及右侧三行编号的预览 修改后：共享的标题、一个 signup 任务和紧凑的预览，使 newsletter 与其他内容视图对齐。截图：sAIgnals，2026 年 11 月 1 日。 两张截图均显示 1280 像素的视口宽度；修改前的图片是较短的截取。改进体现在共享的层级和模式上，而不是转化结果。要评估注册量，我们需要一个明确的观察周期、可比的流量以及已确认订阅的数据。仅凭一小段前后对比，不足以证明设计导致了转化的变化。

把规则变成一次有边界的实现请求

在方向达成一致后，给代理一个具体的目标以及你期望它回报的证据：

`` 更新 newsletter 页面，使其遵循 docs/design-system.md。 先阅读该文件、共享样式，以及 Articles/News 的页头。

复用共享的页面标题和现有的 signup 组件。 把 signup 归为一个任务，预览内容组织为编号行。 保留提交、校验、确认和分析行为。 限定页面专属样式，使其不影响其他 signup 位置。

检查宽屏与窄屏布局，包括 320 px。用键盘输入验证频率选择， 检查可见焦点和表单标签。 运行相关的现有测试和构建。

报告变更的文件、已验证的状态，以及未执行的检查。 不要根据截图或测试通过就声称转化提升或完全符合无障碍标准。 ``

这个提示词给了解决布局细节的空间，同时让产品行为和审查证据保持明确。请补上你项目的真实约束：本地化字符串、受支持的浏览器矩阵、组件库，或截图比对流程。不要包含不适用的要求。

分别验证外观与行为

对我们的 newsletter 改动，我们在 1280 像素检查桌面端，在 390 和 320 像素检查窄屏布局。在这两个窄宽度下，文档没有出现横向溢出。我们用键盘切换频率，确认选中项与同意文案同步变化，运行了构建，并通过了 30 个现有的 newsletter 测试。

这些检查有其局限。newsletter 测试覆盖的是现有的后端行为；它们不能证明新布局是可访问的。截图无法确立读屏软件的可用性或对比度合规性。这次改动我们没有做完整的无障碍审计，也没有做转化实验。

在你自己的 UI 审查中，请包含：

• 布局： 与参考页面对比；检查长标签、真实内容、缩放和窄屏。
• 键盘： 跟随焦点顺序，操作控件，并确认焦点保持可见。
• 状态： 使用受控的 fixture 或测试环境，检查加载、成功、失败和校验状态。
• 对比度： 测量前景/背景组合，而不是相信 token 名称。WCAG 的文本对比度指南 (https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) 规定普通文本为 4.5:1，大文本为 3:1，并有明确的例外情形。
• 点击目标： 使用舒适的控件尺寸。我们的文档为主按钮和输入框设定了 44 像素的本地高度目标。这是项目约定，并非声称 WCAG 2.2 AA 普遍要求 44 像素：其最小目标尺寸条款 (https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) 采用 24 乘 24 CSS 像素，并有例外，包括间距目标和行内目标。
• 回归： 部署前检查共享位置、保留的行为及相关测试。

当共享样式发生变化时，去检查该样式的另一个使用方。当改动是页面专属时，让选择器保持局部化。这能减少“打磨一个表单，却改动了产品中另一个表单“的可能。

把文档控制在够用的大小

设计文档应随着经过评审的产品决策而演进。当团队有意修改共享规则时更新它。不要把每一个一次性例外都加进去，变成未来屏幕的永久指令。

如果文档与某个组件不一致，先弄清楚哪一个反映了当前决策。然后修正过时的引用或实现。默默遵循最后读到的那个文件，会让漂移更难被察觉。

你不需要先建一个组件库才能改进一个页面。从已经存在的 token 和模式开始。当重复的实现让抽取共享组件变得有价值时再抽取；文档不应该成为投机性重构的借口。

把这套工作流带进你的仓库

下载下面的入门模板，用真实文件和决策替换其中的占位符，然后应用到目前感觉格格不入的那一个页面。该文件包含文档骨架、指令文件指引和审查清单。第一次改动要足够小，以便与相邻视图进行比较。

目标是实现可重复的审查：代理能解释它遵循了哪些现有规则，审查者能检查结果，下一个页面能复用同样的决策。

把这份指南用起来 · 免费 Markdown 资源

给你的代理一份设计参考

一份设计系统入门模板、一个指令文件指引，以及一份 UI 审查清单。用真实的项目文件和决策替换占位符。

无需邮箱。将模板适配到你的项目。

预览模板``

[产品名称] — 设计规则

使用本文件前，请替换所有方括号占位符。将文档保存在你的仓库中 （例如 docs/design-system.md）。文件名本身并不会自动把这些规则 加载到助手中。

产品与参考视图

• 受众与主要任务：[谁在使用本产品，用来做什么]
• 视觉性格：[产品中已存在的三个具体特质]
• 参考页面：[两三个路由及其组件文件]
• 权威 token：[样式表、主题或 token 文件]
• 可复用组件：[实际的页头、按钮、输入框、列表和面板组件]

颜色与表面

使用现有的语义 token。在此记录它们的角色；实际值保留在代码中。 如果你包含一张值表，请在 token 变更时更新它。

• 主表面：[token 及预期用途]
• 抬升表面：[token 及预期用途]
• 主/辅助文本：[token；在实际背景上验证对比度]
• 强调/选中/焦点：[token 及预期用途]
• 成功/警告/错误：[token 加上文本或形状信号]
• 边框、圆角、阴影：[现有惯例及有理由的例外]

除非设计明确要求，否则不要创建页面局部的配色。

排版与层级

• 正文字体族：[现有的字体栈]
• 元数据字体族：[现有的字体栈，如不同]
• 普通页面页头：[组件或选择器]
• 标题/正文/元数据字号：[现有的字号与行高]
• 大写/字距：[已在何处使用]
• 标题结构：一个具描述性的 h1 和有意义的章节层级。

布局