前端在 AI Coding 中如何保证样式一致性——当 AI 生成的代码散落在项目各处，用着各自不同的颜色、字号和间距时，技术债就开始以指数速度累积。本文分享一套可被 AI 理解和遵循的 UI 规范体系，以及如何通过 Skill 将其编码为可复用的约束契约，让 Agent 写出的代码天然符合设计规范。
一、制定 UI 规范
1.1 变量：全局通用 CSS 变量
前端样式的基础就是各种属性的值，统一色彩、字体、间距、边框、阴影这些直接与视觉相关的属性值能很好的统一视觉效果；
制定变量时应遵循以下原则：
语义化命名：变量名描述"用途"而非"具体值"。例如 --color-primary 而非 --color-blue，--spacing-md 而非 --spacing-16px。这样当设计调整时，修改变量值即可，不需要改动所有引用。
全面覆盖：颜色、字体、间距、圆角、阴影、过渡等视觉维度必须全部定义，不能留空白。任何空白都会被 AI 用"魔法数字"填充。
与框架对齐：如果使用了第三方组件库，自定义变量应与其内部变量一一对应，仅做命名映射或值覆盖。这样 AI 在使用框架组件或自定义样式时，心智模型一致。
有层级：按语义组织，如每种颜色都有主色、多个浅色阶、深色阶、以及 RGB 值。让 AI 在需要 hover 背景、轻提示、重强调时都能直接选择对应的变量。
有兼容层：对于已有但即将废弃的历史变量，保留在兼容层中，同时引导新代码使用新变量。避免存量代码因变量删除而大面积报错。
此外，如果使用了第三方 UI 库，还需要维护一个桥接层，将自定义变量映射到库的内置变量。例如，使用 Element Plus 时，将 --color-primary 映射到 --el-color-primary，让框架组件在不经额外配置的情况下也自动符合品牌规范。
1.2 组件：使用优先级与分层封装
组件的意义不仅能减少反复造轮子也能统一同类视图的效果，第二点在 AI Coding 尤为重要，不要"让 AI 每次都从零写"，而是用已有的封装来减少 LLM 决策。
组件使用优先级：
项目自定义组件 > 第三方组件库组件 > 手写组件
使用这样的策略能最大化组件复用的比例也能保证特殊视觉效果的需求
在项目封装层解决差异，让业务层只管复用。
1.3 页面布局：为典型场景制定规范
由于页面内容千变万化，我们不可能遍历所有场景，但可以最大化统一典型场景；
向 AI 定义如何划分视图并不是一个路由页面就是一个视图，而是一个独立业务场景就是一个 layout，实践中一个 tab 页面、一个弹窗、一个抽屉可以很容易判断为一个视图，但当页面组合了多个组件时 ai 难以区分；可根据项目中的习惯使用标题、分割线区分不同视图；
二、使用 Skill 解决 AI Coding 的风格漂移
以上规范如果停留在文档层面，只能解决人类开发者的问题。AI 不会主动去查文档，它需要被程序化地约束。Skill 就是这个约束机制——它是 AI 的"可加载规范"，在每次生成代码时自动注入到上下文中。
2.1 编写 Skill 要注意的六个要点
要点一：用"禁止 + 必须"代替"建议"
Skill 中的规则必须是命令式的，不能有"可以""建议""最好"这样的模糊词。AI 对模糊词的理解是弹性的，会倾向选择最省力的方案——通常就是硬编码。
给每条规则配一个反面教材（Forbidden）和一个正确示范（Required）。这让 AI 不只是知道"该做什么"，还知道"什么算违规"。
例如：
禁止使用硬编码颜色值。所有颜色必须使用 CSS 变量。
Forbidden: color: #0d8891; color: blue; color: rgb(0,0,0).
Required: var(--color-primary); var(--text-color-regular); var(--border-color).
要点二：提供决策树，而不是列举
当 AI 面对"我该用什么组件"时，它需要的是决策流程，而不是一张罗列。决策树能减少模糊地带。
例如：
需要对话框/模态框？
→ 标准布局（标题 + 底部操作按钮）？→ 使用 BaseDialog
→ 自定义布局（特殊结构、无标准底部）？→ 使用 el-dialog
需要展示状态？
→ 二进制状态（成功/失败）？→ 使用 StatusTag
→ 多状态或简单标签？→ 使用 el-tag
需要展示数值统计？
→ 单值 + 标签 + 可选副标签？→ 使用 StatCard
→ 多值、图表或复杂卡片？→ 使用标准卡片类 + 自定义内容
要点三：Token 表按"使用场景"组织，而不是按字母顺序
AI 查 Token 时不是"我想找某个变量名"，而是"我需要这个场景下的颜色/间距"。因此 Token 表必须按使用场景组织，并在表头注明用途。
例如：
| 变量 | 使用场景 |
|---|---|
| --color-primary | 主操作按钮、品牌标识、关键链接 |
| --color-primary-light-9 | 主色的浅背景，如 hover 状态、提示框背景 |
| --color-success | 成功状态、完成标记、正向指标 |
| --color-success-light-9 | 成功状态标签背景 |
| --spacing-sm | 表单元素间小间隙、按钮内图标与文字间距 |
| --spacing-lg | 卡片内边距、模块间标准间距 |
| --spacing-2xl | 页面区块间距、大卡片内边距 |
要点四：渐进式加载，不要一次性塞满
Skill 的上下文窗口是有限资源。不要把所有 Token 表、所有组件说明都塞进 SKILL.md 主文件。应该分层：
skills/
└── ui-guidelines/
├── SKILL.md ← 第一层：触发规则 + 核心禁令（必须常驻上下文）
└── references/
├── design-tokens.md ← 第二层：完整 Token 表（需要时加载）
├── component-guide.md ← 第二层：组件决策树（需要时加载）
└── layout-templates.md ← 第二层：页面布局模板（需要时加载）
SKILL.md 只保留最核心的禁令（约 10 条以内），确保触发时就能加载。详细的 Token 值、组件接口、布局模板放在 references 中，当 AI 需要查具体色值或组件用法时按需读取。这样可以避免每次对话都浪费大量 token 在"可能用不到"的参考信息上。
要点五：全局默认值必须写入 Skill
很多规范不是通过 Token 体现，而是通过全局配置（如框架默认 props）体现的。AI 必须知道这些全局默认值，否则它会在每次使用时重复添加，或者不知道某些行为已经内置。
例如：
全局默认行为（无需在组件中重复声明）：
- el-table 已全局开启 stripe（斑马纹），不需要在任何表格上加 stripe 属性
- el-form 已全局设置 label-position="top"，不需要在任何表单上加 label-position 属性
- 表单控件标准高度为 44px，通过全局设置或变量控制
如果 AI 不知道这些全局设置，它可能在每次写表格时都加上 stripe，在每次写表单时都加上 label-position="top"，导致代码冗余且破坏全局一致性。
要点六：规则必须可验证，最好有代码对比
Skill 不能只写"该怎么做"，还应该包含有/无 Skill 的代码对比，让 AI 能直观理解规范的实际效果。
例如，展示一段无 Skill 的违规代码（硬编码色值、字号、间距、圆角），然后列出问题清单，再展示一段有 Skill 的规范代码（全部使用变量）。这种对比不仅帮助 AI 学习，也方便人类审查时快速判断 AI 是否遵循了规范。
2.2 Skill 的标准结构
综合以上要点，一个 UI 规范 Skill 的标准结构如下：
**SKILL.md（主文件，常驻上下文）**包含：
- 元数据（触发条件描述）：让 AI 知道何时加载该 Skill
- 核心禁令（约 10 条）：用"禁止/必须"写成的命令式规则，每条配反面教材和正确示范
- 文件索引：告诉 AI 去哪里查更详细的 Token 表、组件决策树和布局模板
references/design-tokens.md：按使用场景组织的完整 Token 速查表（颜色、字体、间距、圆角、阴影、过渡、布局常量）。
references/component-guide.md：组件决策树 + 自定义组件列表 + 第三方组件映射 + 全局工具类索引 + Vue SFC 模板规范。
references/layout-templates.md：典型页面布局模板（列表页、表单页、卡片网格、仪表盘、按钮集合），每个模板包含结构示意、使用的 Token/组件、间距关系、响应式策略。
2.3 迭代与维护
Skill 不是写完就冻结的文档。随着项目演进，它需要持续迭代：
- 从代码审查中收集反模式：每次发现 AI 硬编码了值，就检查是 Token 缺失还是 Skill 规则不足。如果是规则问题，更新 SKILL.md 的 Mandatory Rules。
- 组件新增时同步更新：当项目新增自定义组件时，立即更新 component-guide.md 的决策树。否则 AI 会继续用旧的组件拼凑。
- Token 变更时三方同步：如果新增或修改变量，同步更新源码变量文件、桥接层、以及 design-tokens.md。三者必须一致。
- 定期用 AI 自检：让 AI 审查现有代码，检查是否还有硬编码值。这是 Skill 的反向应用——不仅用于生成规范代码，也用于检查和修复历史代码。
三、总结
一套好的 UI 规范 + Skill 体系应该满足：
- Token 全覆盖：颜色、字体、间距、圆角、阴影、过渡全部定义，不留空白让 AI 自由发挥
- 组件分层：自定义组件优先于第三方库，第三方库优先于手写，每层都有清晰的迁移路径
- 布局模板化：典型页面有标准结构，AI 按模板组装而不是每次自由发挥
- Skill 命令化：用"禁止/必须"代替"建议"，用决策树代替列举，用反面教材让 AI 理解违规
- 渐进式加载：核心禁令常驻上下文，详细参考按需加载，不浪费 token
- 可迭代：从代码审查中收集反模式，从新增组件中更新决策树，从 Token 变更中同步三方文档
规范不是给人类看的文档，而是给 AI 执行的契约。当 AI 在写代码时自动引用规范变量和自定义组件时，契约就生效了。