语义规范体系：YAML里写的不是颜色值是语义令牌

本文是阶段二《设计师作为"语义翻译者"》的语义规范体系专题。阶段二论证了设计规范从文档转向代码的必要性：传统规范给"人"看，机器无法读取，AI生成内容时不受约束。核心方案是Schema-As-Code——将设计意图翻译成YAML语义契约，让机器在生成前读取并执行约束。

需要首先澄清：YAML里写的不是颜色值，不是文案，是语义令牌。这不是"技术实现"，是"语义翻译"。

本文在此基础上回答"代码格式的规范体系长什么样"：YAML格式标准、语义令牌命名空间、语义域分类、契约库管理，以及到Prompt前缀/Checklist/CI规则的编译输出机制。

阶段一：组件语义快照与模式诊断：AI 生成界面的第一道检查

方法论总纲与开源仓库：把设计规范写成代码格式，是所有 AI 工具的上游约束方法论

一、引言：YAML 里到底写的是什么？

我第一次给别人看我的 YAML 契约时，对方看了一眼说："这不就是 Design Token 吗？把颜色、字体写成代码格式。"

我说不是。他反问："那你写的 color_token: status.critical 和 Design Token 的 color: #EF4444 有什么区别？"

这个问题让我意识到：如果我不先讲清楚"语义令牌"和"Design Token"的区别，所有人都会把 Schema-As-Code 理解成"另一种 Design Token 写法"，然后整个方法论就被矮化了。

所以这篇文章必须放在 YAML 格式之前——先理解语义规范体系，再看 YAML 怎么写，顺序不能反。

二、Design Token vs 语义令牌：两个完全不同的东西

Design Token 解决什么问题？

Design Token 管的是"视觉层的一致性"：

# Design Token（Figma / Tokens Studio / Style Dictionary）
color:
  primary: "#1677FF"
  danger: "#EF4444"
  warning: "#F59E0B"
font:
  family: "Inter"
  size: 14px

Design Token 回答的问题："这个按钮用什么颜色、什么字体？"

它的作用是：让设计稿和代码里的颜色值保持一致，设计系统更新时，改一处全局生效。

语义令牌解决什么问题？

语义令牌管的是"语义层的一致性"：

# 语义令牌（Schema-As-Code）
semantic_tokens:
  error_severity:
    fatal:
      visual_mapping:
        color_token: "status.critical"      # ← 不是 #EF4444，是 "致命状态"
        motion_token: "pulse.red.urgent"     # ← 不是 pulse 2s，是 "紧急脉冲"
        icon_token: "alert.octagon"         # ← 不是 warning.svg，是 "八边形警告"

语义令牌回答的问题："这个错误在这个场景下代表什么后果？用户应该怎么理解？"

核心区别：一层 vs 两层

关键洞察：Design Token 是"视觉字典"，语义令牌是"语义字典"。两者互补，不是替代。

用户看到的界面
    ↓
Design Token（管颜色、字体、间距）
    ↓
语义令牌（管颜色代表什么、文案传递什么）
    ↓
机器理解的规则

没有语义令牌，AI 知道"用红色"，但不知道"红色代表致命"。

三、语义令牌的四大命名空间

我设计语义令牌时，把常见的语义场景归纳为四大类，每类一个命名空间：

1. status.* —— 状态级别

回答的问题："这件事有多严重？"

为什么不是直接写颜色？

因为同一个 status.critical 在不同设计系统里可以映射到不同的色值：

• 设计系统 A：#EF4444（Tailwind 红）
• 设计系统 B：#F5222D（Ant Design 红）
• 设计系统 C：#FF4D4F（DevUI 红）

语义令牌不关心具体色值，只关心语义映射关系。 设计系统更新时，改映射表，语义令牌不变。

2. phase.* —— 认知阶段

回答的问题："AI 现在处于什么阶段？用户在等什么？"

为什么需要阶段令牌？

Perplexity 的 "Searching..." "Reading..." "Wrapping up..." 让用户困惑——不知道 AI 是在查资料还是开始编答案。

有了 phase.*，系统可以显化认知阶段："现在处于检索阶段，已找到 5 个来源，其中 4 个一致。"用户知道"这是查出来的，不是猜出来的"。

3. boundary.* —— 边界强度

回答的问题："系统拒绝用户时，权利边界在哪里？"

为什么需要边界令牌？

Claude 的 "I can't help with that" 和 "Claude has ended this chat" 在界面上都是"拒绝"——用户不知道对话还在不在、数据丢没丢。

有了 boundary.*，系统区分：软性拒绝（继续聊）vs 强制终止（开新会话）。用户明确知道自己的权利状态。

4. action.* —— 操作性质

回答的问题："用户点击这个按钮后，后果是什么？"

为什么需要操作令牌？

AI 生成"删除账户"按钮时，默认给蓝色实心"确认"——因为 Prompt 里只说"生成一个删除按钮"，没有说"这是不可逆操作"。

有了 action.destructive，系统知道：这个按钮后果是破坏性的，必须红色空心、必须二次确认、必须输入账户名验证。

四、语义域：组件在什么场景下？

语义令牌定义了"是什么"，但同一个组件在不同场景下，语义可能完全不同。

我设计了三个语义域（Semantic Domain）：

observational —— 观察型

特征：用户被动接收信息，不需要操作。

典型组件：错误提示、状态通知、告警卡片。

约束：

• 禁止要求用户输入
• 必须提供明确的退出路径
• 文案必须说明后果（不能只说"出错了"）

transactional —— 交易型

特征：用户主动触发操作，系统必须反馈结果。

典型组件：提交按钮、表单、确认弹窗。

约束：

• 必须提供操作结果反馈
• 成功/失败状态必须明确
• 不可逆操作必须有二次确认

conversational —— 对话型

特征：用户和系统双向对话，上下文持续累积。

典型组件：聊天界面、问答系统、AI 助手。

约束：

• 必须保留对话上下文
• 边界动作必须说明会话状态
• 拒绝时必须提供替代建议

为什么需要语义域？

同一个 Alert 组件：

• 在 observational 域（系统故障）→ 用户被动看，不能要求输入
• 在 transactional 域（表单验证）→ 用户主动填，必须给反馈
• 在 conversational 域（对话中断）→ 上下文要保留，不能说断就断

没有语义域，系统不知道"这个组件在用户流程中扮演什么角色"，约束就会错位。

五、不可变边界：红线

语义令牌定义"应该是什么"，不可变边界定义"绝对不能是什么"。

我把它理解为"语义红线"——一旦触碰，系统必须阻断。

示例：ERR-001 的不可变边界

immutable_boundaries:
  - boundary_type: "safety"
    rule: "禁止直接执行删除操作而不显示二次确认"
    violation_action: "block"

  - boundary_type: "clarity"
    rule: "禁止在错误状态文案中使用模糊词汇（如'出错了'、'Something went wrong'）"
    violation_action: "block"

  - boundary_type: "consistency"
    rule: "禁止将不同严重级别的错误使用相同视觉表达"
    violation_action: "block"

为什么叫"不可变"？

这些边界不是"建议"，是"强制规则"：

• block：一旦触发，直接阻断生成，返回修改建议
• warn：触发后警告，但允许人工确认后放行
• escalate：触发后升级人工审核

与语义令牌的区别：

• 语义令牌 = " fatal 应该用什么颜色"（推荐性映射）
• 不可变边界 = "fatal 绝对不能和 retryable 用同一种颜色"（强制性约束）

六、完整示例：ERR-001 的语义规范拆解

把上面的概念串起来，看 ERR-001 是怎么从"语义规范"翻译成"YAML 契约"的：

语义规范层（设计师的意图）

设计意图：
- 错误状态必须按后果严重程度分级
- 用户必须知道"多严重"和"该做什么"
- 系统绝对不能让不同级别的错误长得一样

语义规范：
- 状态级别：fatal / transient / retryable / degraded（status.*）
- 语义域：observational（用户被动接收）
- 不可变边界：不同级别不能用相同颜色

语义令牌层（机器可读的标识）

# 语义令牌映射
status.critical    → 致命错误 → 红色脉冲
status.neutral     → 可恢复错误 → 灰色加载
status.warning     → 限流提示 → 黄色倒计时
status.info        → 部分可用 → 蓝色提示

YAML 契约层（可执行的规则）

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:
        - "禁止红色背景（避免情绪过载）"

immutable_boundaries:
  - boundary_type: "consistency"
    rule: "禁止将不同严重级别的错误使用相同视觉表达"
    violation_action: "block"

三层关系：

• 语义规范层 = 设计师的意图（人话）
• 语义令牌层 = 机器可读的标识（机器话）
• YAML 契约层 = 可执行的规则（代码话）

七、语义规范与 YAML 契约的关系

不是先有 YAML 格式，再往里填内容。

是先有语义规范体系，再选择 YAML 作为载体。

语义规范（理论层）
    ├── 语义令牌命名空间（status / phase / boundary / action）
    ├── 语义域分类（observational / transactional / conversational）
    └── 不可变边界原则（安全 / 清晰 / 一致）
        ↓
YAML 契约（实现层）
    ├── semantic_tokens 字段（填语义令牌）
    ├── context 字段（填语义域）
    └── immutable_boundaries 字段（填红线）

理解了这个关系，就不会把 Schema-As-Code 当成"另一种 Design Token"，而是"设计意图的语义翻译层"。

八、Before/After：加了语义规范后，YAML 契约长什么样？

Before（没有语义规范，YAML 只写视觉值）

# 错误状态规范（没有语义层）
error:
  color: "#EF4444"
  bg: "solid"
  icon: "warning.svg"
  text: "Something went wrong"
  button: "重试"

问题：

• 前端看了知道"用红色"，但不知道"红色代表什么"
• AI 看了知道"生成红色按钮"，但不知道"什么场景下该用什么红色"
• 设计系统更新红色色值时，YAML 要全部改一遍

After（有了语义规范，YAML 写语义令牌）

# 错误状态规范（有语义层）
semantic_tokens:
  error_severity:
    fatal:
      visual_mapping:
        color_token: "status.critical"      # ← 语义令牌，不是色值
        motion_token: "pulse.red.urgent"
        icon_token: "alert.octagon"
      user_action: ["刷新页面", "导出历史"]

    transient:
      visual_mapping:
        color_token: "status.neutral"       # ← 同一组件，不同语义，不同令牌
        motion_token: "spinner"
        icon_token: "loader"
      user_action: ["等待自动恢复"]

改变：

• 前端看了知道"fatal 用 status.critical"，去映射表查具体色值
• AI 看了知道"fatal 必须红色脉冲 + 刷新/导出按钮"
• 设计系统更新色值时，改映射表，YAML 完全不变

九、总结

Schema-As-Code 的 YAML 契约里写的不是颜色值、不是文案、不是 Design Token。

写的是语义令牌——机器可读的语义标识，定义"这个界面元素在这个场景下代表什么"。

四大命名空间：

• status.* —— 状态级别（多严重）
• phase.* —— 认知阶段（在干什么）
• boundary.* —— 边界强度（权利在哪）
• action.* —— 操作性质（后果是什么）

三层语义域：

• observational —— 用户被动看
• transactional —— 用户主动点
• conversational —— 用户和系统聊

一条红线：

• immutable_boundaries —— 绝对不能做什么

理解了这个语义规范体系，再看 YAML 格式，就知道每个字段填的不是视觉值，是语义映射。

640.png