把设计规范写成代码格式，是所有 AI 工具的上游约束方法论

当 AI 生成界面时，设计意图在偏离。不是 AI 故意做错，而是系统缺少一层"语义约束"。

本文提出 Schema-As-Code：一套让设计师用 YAML 契约锁住设计意图的三阶段流水线。不是替代任何工具，是所有 AI 工具的上游约束。
是 Schema-As-Code 第一阶段 《组件语义快照与模式诊断：AI 生成界面的第一道检查》 的方法论总纲与开源仓库发布。

一、问题：AI 生成界面时，谁在守住设计意图？

• v0 / Framer AI 用一句话生成可交互原型
• Claude Code / Cursor 用自然语言写前端代码
• DevUI HMC / DESIGN.md 让 AI 按组件库规范输出代码

• AI 生成"删除账户"按钮，给了个蓝色实心按钮，用户一点，账户没了
• AI 生成告警卡片，把 Critical 写成 "严重"，值班员觉得不严重，延迟响应
• 设计规范更新了"错误状态分四级"，发在语雀文档里，前端没看，AI 更没看
• 一个产品 500 个页面，人工走查 100 个就累了，剩下 400 个的语义错误上线后才被用户投诉

这不是某个产品的 Bug，而是整个行业在概率性界面时代共同面临的结构性断层。

二、把设计规范写成代码格式的规则文件 是所有工具的上游约束方法论

┌─────────────────────────────────────────┐
│  语义层：Schema-As-Code（你）           │  ← 你在这里
│  "这个场景下必须表达什么语义、不能突破什么边界" │
└─────────────────────────────────────────┘
              ↓ 编译为 Prompt 前缀 / 校验规则
┌─────────────────────────────────────────┐
│  形态层：v0 / Claude Code / DevUI HMC   │  ← 现有工具
│  "长什么样、用什么组件、怎么写代码"       │
└─────────────────────────────────────────┘

关键洞察：

• v0 解决的是"AI 能不能生成界面"
• Claude Code 解决的是"AI 能不能写代码"
• DevUI HMC 解决的是"代码是否符合组件库规范"
• Schema-As-Code 解决的是"AI 生成的内容是否偏离了设计意图"

这四层缺一不可，且互不替代。

三、三阶段流水线：从发现问题到证明有效

【三阶段流水线图】

阶段一：Guard —— 组件语义快照与模式诊断

回答的问题："我的产品有没有语义断层？"

我设计了一套"结构化问诊"流水线：

1. 组件语义快照：用 6 个字段记录一个界面组件的语义特征（组件类型、视觉、文案、交互、上下文、产品来源）
2. 三层判定模型：回答 3 组问题 → 自动匹配语义断层模式
   • 第一层：这是什么组件类型？（错误状态 / 过程状态 / 边界动作 / 操作按钮 / 状态提示）
   • 第二层：用户的核心困惑是什么？（不知道多严重 / 不知道在干什么 / 不知道权利还在不在）
   • 第三层：当前界面的视觉表达有什么特征？（全部红色 / 文案模糊 / 缺少行动指引）
3. 模式匹配：自动输出"这是 ERR-001 类型的断层"，附带同类产品证据

【结构化问诊界面截图】

目前已验证 5 个通用模式：

【模式库卡片截图】

阶段一产出： 诊断报告 + 同类产品证据截图 + 根因分析

阶段二：Contract —— 设计师作为"语义翻译者"

回答的问题："我怎么用规则锁住设计意图？"（本文重点预告，完整内容见下篇）

• 写一份设计规范文档（PDF/语雀）
• @ 全员通知
• 2 周后走查发现 3 个产品没改对

• 把设计意图翻译成 YAML 契约（机器可读的规则文件）
• 放在 Git 仓库里，变更自动同步
• AI 工具自动消费，机器走查覆盖率 100%

YAML 契约示例（ERR-001）：

intent_id: "ERR-001"
semantic_domain: "observational"

semantic_tokens:
  error_severity:
    fatal:
      description: "系统级故障，对话上下文可能丢失"
      visual_mapping:
        color_token: "status.critical"      # 语义令牌：定义这个颜色代表"致命状态"
        motion_token: "pulse.red.urgent"    # 语义令牌：定义这个动效代表"紧急"
        icon_token: "alert.octagon"        # 语义令牌：定义这个图标代表"危险"
      user_action:
        - label: "刷新页面"
          action: "refresh"
        - label: "导出历史"
          action: "export_history"
      llm_constraints:
        - "必须明确告知用户对话上下文可能已丢失"
        - "禁止仅显示'出错了'等模糊文案"

    transient:
      description: "网络抖动，系统可自动恢复"
      visual_mapping:
        color_token: "status.neutral"       # 语义令牌：定义这个颜色代表"中性状态"
        motion_token: "spinner"             # 语义令牌：定义这个动效代表"加载中"
        icon_token: "loader"                # 语义令牌：定义这个图标代表"等待"
      user_action:
        - label: "等待自动恢复"
          action: "wait"
      llm_constraints:
        - "禁止红色背景（避免情绪过载）"
        - "必须显示自动重试进度"

    retryable:
      description: "请求频率已达上限"
      visual_mapping:
        color_token: "status.warning"       # 语义令牌：定义这个颜色代表"警告状态"
        motion_token: "none"               # 语义令牌：定义这个动效代表"静态"
        icon_token: "clock"                 # 语义令牌：定义这个图标代表"限时"
      user_action:
        - label: "等待倒计时"
          action: "wait_countdown"
        - label: "升级套餐"
          action: "upgrade"
      llm_constraints:
        - "必须显示剩余等待时间"
        - "必须提供升级/扩容路径"

    degraded:
      description: "部分功能可用，可继续生成"
      visual_mapping:
        color_token: "status.info"          # 语义令牌：定义这个颜色代表"信息状态"
        motion_token: "none"               # 语义令牌：定义这个动效代表"静态"
        icon_token: "info.circle"           # 语义令牌：定义这个图标代表"提示"
      user_action:
        - label: "继续生成"
          action: "continue"
        - label: "简化问题重试"
          action: "retry_simplified"

status.critical 是语义令牌（Semantic Token），定义"这个颜色在这个场景下代表致命状态"。完整的语义令牌体系（status. / phase. / boundary. / action.）见契约书写规范。

关键设计： 一份 YAML 契约，编译为四种消费格式：

• YAML 本体：供 DesignOps 版本管理
• Prompt 前缀：供 Claude Code / Cursor 注入 AI 指令
• Checklist 走查清单：供设计师人工复核
• CI 校验规则：供自动化流水线拦截

【契约库界面截图】

阶段二产出： YAML 契约文件 + 多格式编译输出

阶段三：Verify —— 验证闭环与工具落地

回答的问题："我怎么证明规则真的防住了语义漂移？"

三层验证工具：

1. 语义分级器：输入任意错误文案，1 秒内返回语义分级建议（Fatal/Transient/Retryable/Degraded）
2. JSON 语义校验器：粘贴组件语义快照，自动匹配已知模式并标记风险
3. 四层推演引擎：语法推演 → 语义推演 → 安全推演 → 美感推演

【语义分级器界面截图】

【A/B 对比截图】

验证指标：

阶段三产出： 验证报告 + 返工率数据 + 可复用的验证工具

四、关键洞察：设计师不需要写代码，但需要写"规矩"

答案是：不仅能，而且正因为不会写代码，你才是最适合写 YAML 契约的人。

为什么？

会写代码的人，看到问题后会直接去写脚本、搭平台——结果卷进了工程实现层，和 DevUI HMC / v0 竞争。

不会写代码的人，站在"意图层"——只关心"这个场景下必须表达什么语义、不能突破什么边界"，而不关心"用什么框架实现"。

YAML 契约的本质是"设计意图的翻译"，不是"代码实现"。

intent_id: "ACT-001"
semantic_domain: "transactional"

semantic_tokens:
  destructive_action:
    description: "不可逆的数据销毁操作"
    # 语义令牌：定义视觉元素的语义含义
    visual_mapping:
      color_token: "status.critical"        # 语义令牌：定义这个颜色代表"致命状态"
      button_style: "outline_danger"          # 语义令牌：定义这个按钮样式代表"危险空心描边"
      icon_token: "alert.triangle"           # 语义令牌：定义这个图标代表"警告"

    # 不可变边界：绝对不能突破的红线
    immutable_boundaries:
      - boundary_type: "safety"
        rule: "禁止直接执行删除操作而不显示二次确认"
        violation_action: "block"
      - boundary_type: "safety"
        rule: "禁止将删除按钮设计为普通主按钮样式"
        violation_action: "block"

    # LLM 约束：AI 生成内容时必须遵守的规则
    llm_constraints:
      - "必须包含二次确认弹窗"
      - "文案必须明确说明'此操作不可恢复'"
      - "必须提供取消选项，且视觉权重不低于确认按钮"
      - "禁止在二次确认弹窗中使用'确认'等模糊文案，必须使用'确认删除'"

    # 用户行动：与后果级别匹配的操作
    user_action:
      primary:
        label: "确认删除账户"
        action: "confirm_delete"
        requires_input: true                # 要求输入账户名确认
        input_field: "account_name"
      secondary:
        label: "取消"
        action: "cancel"
        visual_weight: "equal"             # 视觉权重与主按钮同等

• 没有 CSS 类名
• 没有 React/Vue 组件名
• 没有文件路径

只有设计师的意图："删除按钮必须是红色空心，必须有二次确认。"

传统工作流的隐性成本

总成本 = 设计意图在跨角色传递中不断失真，反复修复。

Schema-As-Code 工作流的经济价值

总收益 = 设计意图从"人传人的方言"变成"机器可读的普通话"。

设计师的新角色："语义翻译者"

"能不能把设计意图翻译成机器可读的规则，让 AI 在生成内容之前就知道什么不能说、什么不能做。"

• 比工程师更懂设计意图的语义
• 比设计师更懂实现的约束
• 是"设计 → 工程"之间的翻译层

而 YAML 契约就是这个翻译层的载体。

六、与其他工具的关系：不是替代，是叠加

Design Token 定义"颜色是什么"（如 #EF4444），语义令牌定义"颜色代表什么"（如 status.critical）。Schema-As-Code 消费 DESIGN.md 的视觉定义，但约束的是语义映射关系。

七、仓库与在线体验

已开源

• GitHub 仓库：https://github.com/2436041978-ops/semantic-pipeline
• 在线体验：https://2436041978-ops.github.io/semantic-pipeline/

八、下一步：阶段二文章

• 从意图到规则：YAML 作为中间翻译层的设计哲学
• 设计师的 YAML 书写规范（不会写代码也能写）
• 契约库：让设计规范像代码一样管理
• 从契约到消费格式：编译
• 真实案例：ERR-001 从诊断到契约的完整过程

如果你也在经历"AI 生成的界面偏离设计意图"的困扰，欢迎关注这个系列。

结语

设计师不需要写代码，但需要写"语义契约"——把设计意图翻译成机器可读的规则，成为 AI 生成界面的上游约束层。

Gap 期局限性声明

当前状态： 架构推演与最小可行原型阶段。YAML 规范、校验逻辑为定义层实现，尚未接入生产级 LLM API 或 CI 流水线。欢迎基于现有思路共建。

关于作者

魏雯，体验架构设计师。

专注于：AI 界面的语义治理。解决的核心问题：让 LLM 生成的界面不偏离设计规范。

10+ 年互联网设计经验。设计系统 / 体验工程 / AI 原生｜广州 / 深圳