框架定义：当 AI 生成界面时，设计意图在偏离。Schema-As-Code 把设计规范写成代码格式，在语义层建立一套机器可读的约束契约，让 AI 在生成界面之前，先知道"这个场景下必须表达什么语义、不能突破什么边界"。框架不替代任何设计工具或 AI 工具，而是所有 AI 工具的上游约束层——AI 负责生成，规则负责把关。
本文定位：本文是 Schema-As-Code 体系的总纲与预告。核心回答四个问题：AI 生成界面时谁在守住设计意图（问题定义）；为什么约束必须写成代码格式（方法论核心：约束显化）；三阶段流水线如何运转（Guard → Contract → Verify）；以及这套方法论与其他工具的关系（不是替代，是叠加）。读完本文，可以判断这套方法论是否适用于你的团队，再决定是否深入各阶段的专题文章。
当 AI 生成界面时，设计意图在偏离。不是 AI 故意做错，而是系统缺少一层"语义约束"。
本文提出 Schema-As-Code：一套让设计师用 YAML 契约锁住设计意图的三阶段流水线。不是替代任何工具，是所有 AI 工具的上游约束。
一、问题：AI 生成界面时，谁在守住设计意图？
2024-2025 年，设计团队全面进入 AI 辅助生产时代：
- v0 / Framer AI 用一句话生成可交互原型
- Claude Code / Cursor 用自然语言写前端代码
- DevUI HMC / DESIGN.md 让 AI 按组件库规范输出代码
但这些工具都在解决同一个层面的问题：界面长什么样、代码怎么写（形态层）。
没有人解决另一个层面的问题：这个界面在这个场景下表达了什么语义、不能突破什么边界（语义层）。
结果是：
- AI 生成"删除账户"按钮，给了个蓝色实心按钮，用户一点，账户没了
- AI 生成告警卡片，把 Critical 写成"严重"，值班员觉得不严重，延迟响应
- 设计规范更新了"错误状态分四级"，发在语雀文档里，前端没看，AI 更没看
- 一个产品 500 个页面，人工走查 100 个就累了，剩下 400 个的语义错误上线后才被用户投诉
这不是某个产品的 Bug，而是整个行业在概率性界面时代共同面临的结构性断层。
二、把设计规范写成代码格式，是所有工具的上游约束方法论
我提出 Schema-As-Code（把设计规范写成代码格式的规则文件），不是要做另一个 Design-to-Code 工具，而是要建立一层上游约束。
┌─────────────────────────────────────────┐
│ 语义层：Schema-As-Code │ ← 你在这里
│ "这个场景下必须表达什么语义、 │
│ 不能突破什么边界" │
└─────────────────────────────────────────┘
↓ 编译为 Prompt 前缀 / 校验规则
┌─────────────────────────────────────────┐
│ 形态层：v0 / Claude Code / DevUI HMC │ ← 现有工具
│ "长什么样、用什么组件、怎么写代码" │
└─────────────────────────────────────────┘
关键洞察：
- v0 解决的是"AI 能不能生成界面"
- Claude Code 解决的是"AI 能不能写代码"
- DevUI HMC 解决的是"代码是否符合组件库规范"
- Schema-As-Code 解决的是"AI 生成的内容是否偏离了设计意图"
这四层缺一不可，且互不替代。
三、三阶段流水线：从发现问题到证明有效
Schema-As-Code 不是一套理论，是一条可执行的三阶段流水线（Semantic Pipeline）。
阶段一 Guard 结构化诊断（Structured Diagnosis）—— 组件语义快照与模式诊断
回答的问题："我的产品有没有语义断层？"
我设计了一套"结构化问诊"流水线：
- 组件语义快照：用 6 个字段记录一个界面组件的语义证据（snapshot_id / product / component_type / visual_record / user_confusion / context，详见《组件语义快照》）
- 三层判定模型：回答 3 组问题 → 自动匹配语义断层模式
- 第一层：这是什么组件类型？（错误状态 / 过程状态 / 边界动作 / 操作按钮 / 告警状态 / 信息状态）
- 第二层：用户的核心困惑是什么？（不知道多严重 / 不知道在干什么 / 不知道权利还在不在）
- 第三层：当前界面的视觉表达有什么特征？（全部红色 / 文案模糊 / 缺少行动指引）
- 模式匹配：自动输出"这是 ERR-001 类型的断层"，附带同类产品证据
| 模式 ID | 组件类型 | 断层名称 | 典型症状 |
|---|---|---|---|
| ERR-001 | 错误状态 | 后果差异未分级 | 多种错误共用红色 |
| PRO-001 | 过程状态 | 认知阶段未显化 | Searching/Reading 模糊 |
| BND-001 | 边界动作 | 权利差异未区分 | 拒绝 vs 终止混为一谈 |
| ACT-001 | 操作按钮 | 高危操作未约束 | 删除按钮做成蓝色实心 |
| ALR-001 | 告警状态 | 文案语义降级 | Critical 被写成"严重" |
| INF-001 | 信息状态 | 状态权重未对齐 | 通知与警告视觉权重相同 |
阶段一产出：诊断报告 + 同类产品证据 + 根因分析。
阶段二 Contract 语义契约化（Semantic Contractualization）—— 设计师作为"语义翻译者"
回答的问题："我怎么用规则锁住设计意图？"
当设计师发现语义断层后，传统做法是：写一份设计规范文档（PDF/语雀）→ @ 全员通知 → 2 周后走查发现 3 个产品没改对。
Schema-As-Code 的做法是：
- 把设计意图翻译成 YAML 契约（机器可读的规则文件）
- 放在 Git 仓库（契约库）里，变更自动同步
- AI 工具自动消费，机器走查覆盖率 100%
status.critical 是语义令牌（Semantic Token），定义"这个颜色在这个场景下代表致命状态"。完整的语义令牌体系（status.* / phase.* / boundary.* / action.*）见语义规范体系与语义字典。
编译管线的完整机制详见：《编译管线是语义一致性的"机器翻译层"》
关键设计：一份 YAML 契约，由编译管线编译为 4 种消费格式：
- Prompt 前缀：供 Claude Code / Cursor 注入 AI 指令
- JSON Schema：供前端 Props 结构校验
- Checklist 走查清单：供设计师人工复核
- CI 校验规则：供自动化流水线拦截
阶段二的完整展开详见：《语义规范体系》 · 《YAML 契约格式》 · 《编译管线》 · 《契约库》
阶段二产出：YAML 契约文件 + 4 种格式编译输出。
阶段三 Verify 验证闭环（Validation Closure）—— 证明规则有效
回答的问题："我怎么证明规则真的防住了语义漂移？"
三层验证工具：
- 语义分级器：输入任意错误文案，1 秒内返回语义分级建议（Fatal / Transient / Retryable / Degraded）
- JSON 语义校验器：粘贴组件语义快照，自动匹配已知模式并标记风险
- 四层推演引擎：语法推演 → 语义推演 → 安全推演 → 美感推演，逐层校验、逐层短路
验证指标（数据模型推演口径，非实测数据）：
| 指标 | 之前 | 之后 |
|---|---|---|
| 语义返工率 | 30% | 5% |
| 规范同步时间 | 2 周 | 0.5 天 |
| 走查覆盖率 | 20% | 100% |
四、为什么必须是 YAML，而不是 Prompt 或文档
约束写在 Prompt 里：不可审计（改了没人知道）、不可复用（每个项目重写一遍）、不可版本管理（无法 Diff、无法回滚）、不可校验（机器无法判断生成结果是否违反了"那一段话"）。
约束写在文档里：人可能看漏、看错、看过时版本；机器根本看不到。
YAML 契约获得四项能力：可被机器读取（AI 生成前注入）、可被自动校验（CI 阻断）、可被版本管理（Git Diff 追溯）、可被多格式分发（一处修改四处同步）。
五、经济价值：从"人传人的方言"到"机器可读的普通话"
传统工作流的隐性成本：
| 环节 | 现状 | 问题 |
|---|---|---|
| 规范定义 | 设计师写语雀文档 | 机器无法读取 |
| 规范同步 | @全员 + 开会 | 2 周还有人没收到 |
| 规范执行 | 前端凭经验实现 | 每个人理解不同 |
| 规范走查 | 设计师人眼检查 | 500 页面只能看 100 个 |
| 规范修复 | 上线后用户投诉 | 修复成本 ×10 |
总成本 = 设计意图在跨角色传递中不断失真，反复修复。
Schema-As-Code 工作流的经济价值：
| 环节 | 改变 | 节省 |
|---|---|---|
| 规范定义 | 设计师写规则文件 | 意图直接机器可读 |
| 规范同步 | Git 变更自动触发 | 从 2 周 → 0.5 天 |
| 规范执行 | AI 自动读取指令前缀 | 前端不再凭经验猜 |
| 规范走查 | 机器自动校验 100% | 设计师只处理异常 |
| 规范修复 | 生成前拦截 | 上线后零语义事故 |
总收益 = 设计意图从"人传人的方言"变成"机器可读的普通话"。（以上数字为数据模型推演口径，非实测数据。）
设计师角色的完整展开见：《设计师与产品经理》角色专题
设计师的新角色："语义翻译者"
在 AI 生成界面的时代，设计师的核心竞争力不是"会不会写代码"，而是：
"能不能把设计意图翻译成机器可读的规则，让 AI 在生成内容之前就知道什么不能说、什么不能做。"
这个角色：比工程师更懂设计意图的语义，比设计师更懂实现的约束，是"设计 → 工程"之间的翻译层。而 YAML 契约就是这个翻译层的载体。
六、与其他工具的关系：不是替代，是叠加
| 工具类型 | 解决什么问题 | Schema-As-Code 怎么叠加 |
|---|---|---|
| Design-to-Code（Anima/Builder） | 从设计稿到代码 | 在导出前加语义校验，防止代码生成后语义漂移 |
| AI 原型（v0/Framer AI） | 快速验证想法 | 在生成前注入 Prompt 前缀，约束原型语义 |
| AI 编程（Claude Code/Copilot） | 自然语言写代码 | 在 Prompt 上下文注入 YAML 约束，代码生成前已知语义边界 |
| 企业规范（DevUI HMC） | 符合组件库的代码 | 在组件语义映射时叠加语义层，组件用对了但场景语义也要对 |
| 设计系统规范（DESIGN.md） | 视觉规范的机器可读化 | 消费 DESIGN.md 的 Token，但约束的是语义映射关系 |
Design Token 定义"颜色是什么"（如 #EF4444），语义令牌 定义"颜色代表什么"（如 status.critical）。Schema-As-Code 消费 DESIGN.md 的视觉定义，但约束的是语义映射关系。
七、仓库与在线体验
已开源：
- GitHub 仓库：github.com/2436041978-…
- 在线体验：2436041978-ops.github.io/semantic-pi…
结语
AI 时代的设计工作流正在重构。不是"设计师会不会被 AI 替代"的问题，而是"设计师在 AI 工作流中扮演什么新角色"的问题。
Schema-As-Code 给出的答案是：设计师不需要写代码，但需要写"语义契约"——把设计意图翻译成机器可读的规则，成为 AI 生成界面的上游约束层。
这不是一个工具，是一个方法论。不是替代任何现有工具，是所有工具的上游约束。
Gap 期局限性声明：当前状态为架构推演与最小可行原型阶段。YAML 规范、校验逻辑为定义层实现，尚未接入生产级 LLM API 或 CI 流水线。欢迎基于现有思路共建。
关于作者：魏雯，体验架构设计师。专注于 AI 界面的语义治理，解决的核心问题：让 LLM 生成的界面不偏离设计规范。10+ 年互联网设计经验。设计系统 / 体验工程 / AI 原生｜广州 / 深圳
下一步：阶段二深度展开
本文是 Schema-As-Code 体系的总纲与预告。下一篇深度展开阶段二 Contract 语义契约化（Semantic Contractualization）：从意图到规则的翻译哲学、设计师的 YAML 书写规范、契约库管理、编译机制与真实案例。详见下一篇《阶段二 Contract：设计师作为"语义翻译者"——当 AI 生成界面时，我怎么用规则锁住设计意图》。
附录：三阶段流水线速查表
| 阶段 | 统一命名 | 回答的问题 | 核心资产 |
|---|---|---|---|
| 阶段一 | Guard 结构化诊断（Structured Diagnosis） | 我的产品有没有语义断层？ | 6 字段快照 + 三层判定模型 + 模式库 v0.1（6 模式） |
| 阶段二 | Contract 语义契约化（Semantic Contractualization） | 我怎么用规则锁住设计意图？ | YAML 契约（7 字段）+ 契约库 + 4 种编译格式 |
| 阶段三 | Verify 验证闭环（Validation Closure） | 我怎么证明规则真的有效？ | 四层推演引擎 + 用例库 × 12 + 验证报告 |
