当AI开始参与界面设计，语义断层问题成为新的设计瓶颈。本文揭秘如何通过Schema-As-Code将设计规范转化为机器可读的YAML契约，建立语义令牌体系与不可变边界，从根源解决AI生成界面中的认知混乱问题。这套方法已在ChatGPT、文心一言等主流AI产品中验证其价值。

阶段一通过语义快照诊断，发现了AI生成界面中的系统性语义断层：同一组件在不同场景下被混用同一套视觉规则，导致用户认知混乱。诊断报告指明了”缺什么规则”，但发现规则缺失不等于解决问题。

阶段二的核心任务是将设计意图转化为机器可读的语义契约，不是让设计师写代码而是建立一套”语义翻译层”，让AI在生成内容前就知道什么不能说、什么不能做，从源头锁住语义漂移。

1. 为什么设计规范总是传不到位

2024-2025 年，设计团队全面进入AI辅助生产时代。但一个老问题始终没解决：

设计规范更新了，前端没同步；AI更没看，还是按老样子生成。

我经历过这样的场景：

• 设计师把“错误状态分四级”的规范更新了，发在语雀文档里，@ 全员通知
• 2周后走查，发现3个产品的AI生成界面还是全红
• 问前端：“规范更新了，你知道吗？” 答：“啊，我没看到那条消息。”
• 问 AI：“你知道错误状态要分四级吗？” AI：“我的训练数据里没有这条。”

问题根因：设计规范写在文档里，是给“人”看的，不是给“机器”读的。

人可能看漏、看错、看过时版本。机器根本看不到。

2. 把设计规范写成代码格式

我的解法是 Schema-As-Code 把设计意图翻译成YAML格式的语义规则，让机器能读、能校验、能自动同步。

2.1 翻译的本质

设计师的核心能力不是”画界面”，而是”理解场景语义”：

• 这个按钮是“删除账户”，不可逆，必须让用户知道后果
• 这个错误是“系统级故障”，对话可能丢了，必须给恢复路径
• 这个提示是“限流”，等一等就好，不需要恐慌

以前，这些意图写在文档里，靠人传人的方式传递，层层失真。

现在，我把这些意图写成YAML契约，机器直接读取，零失真传递。

2.2 翻译前后的对比

关键变化：设计意图从“人传人的方言”变成“机器可读的普通话”。

3. 语义规范体系 YAML里写的是什么

在展示YAML格式之前，必须先理解YAML里写的是什么，

不是颜色值，不是文案，是语义令牌。

3.1 什么是语义令牌（Semantic Tokens）

传统 Design Token 管的是”颜色是什么”：

color: #EF4444 → 这是红色

语义令牌管的是“颜色代表什么”：

color_token: “status.critical” → 这个红色代表”致命状态”

同一个红色，在不同场景下语义完全不同：

• 在系统故障场景下 = 致命（status.critical）
• 在促销场景下 = 优惠（status.promotion）
• 在高危操作场景下 = 危险（action.destructive）

语义令牌是 Design Token 的上一层——它不关心具体色值，只关心语义映射。

3.2 语义令牌命名空间

命名空间的价值：让语义有标准字典，不凭感觉。

以前设计师说”用红色”，前端可能理解为”#EF4444″、”#FF0000″或”#FF4D4F”。

现在设计师说”用 status.critical”，所有人都知道这是”致命状态的标准红色”，色值由设计系统映射表定义。

3.3 语义域（Semantic Domain）

语义域定义”用户与系统的交互关系类型”：

语义域的价值：同一个组件，在不同域下约束不同。

例如 Alert 组件：

在 observational 域（错误提示）→ 用户被动看，不能要求输入

在 transactional 域（确认弹窗）→ 用户主动点，必须给反馈

3.4 不可变边界（Immutable Boundaries）

定义”绝对不能做什么”的红线：

immutable_boundaries:

– boundary_type: “safety”

rule: “禁止直接执行删除操作而不显示二次确认”

violation_action: “block”

– boundary_type: “compliance”

rule: “禁止在提示场景使用 status.critical”

violation_action: “warn”

不可变边界的价值：给 AI 画红线，不是建议，是禁止。

3.5 语义规范 vs Design Token：关键区别

关系：Design Token 是“底层词汇”，语义规范是“上层语法”。

四、YAML 契约格式：怎么写语义规则

理解了语义规范体系后，来看 YAML 契约的具体格式。

4.1 基础结构

intent_id: “ERR-001” # 规则唯一标识

description: “错误状态后果差异未分级” # 规则描述

version: “1.0.0” # 语义版本号

applicable_products: # 适用产品范围

– “ChatGPT”

– “文心一言”

– “通义千问”

– “Kimi”

– “豆包”

– “DeepSeek”

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”

countdown_field: “retry_after”

– 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”

llm_constraints:

– “必须说明哪些功能仍然可用”

– “禁止显示纯技术错误码（如 500 Internal Error）”

immutable_boundaries: # 不可变边界（不能做什么）

– boundary_type: “safety”

constraint_rule_ref: “rules/error-severity.yaml”

violation_action: “block”

4.2 关键字段说明

4.3 与阶段一的衔接

阶段一诊断出：”该组件缺少 error_severity 语义令牌，违反 ERR-001 模式。”

阶段二生成 YAML：直接定义 error_severity 语义令牌，包含 fatal/transient/retryable/degraded 四级。

从诊断到契约，是同一个语义缺失问题的“发现→修复”闭环。

五、从契约到消费格式：编译

一份 YAML 契约，自动编译为 4 种消费格式：

5.1 编译为 Prompt 前缀（给 AI 编程工具）

在生成错误状态界面时，必须遵守以下语义分级：

– Fatal（系统级故障）：红色脉冲 + 八边形警告 + 必须提供恢复路径

– Transient（网络抖动）：灰色加载 + 旋转图标 + 禁止红色背景

– Retryable（限流）：黄色提示 + 时钟图标 + 必须显示倒计时

– Degraded（部分可用）：蓝色提示 + 信息图标 + 必须说明可用功能

禁止：所有错误状态共用同一种红色视觉表达。

5.2 编译为 Checklist（给设计师走查）

错误状态走查清单：

– [ ] 是否区分了 Fatal/Transient/Retryable/Degraded 四级？

– [ ] 每级是否有不同的颜色（红/灰/黄/蓝）？

– [ ] 每级是否有明确的用户行动指引？

– [ ] Fatal 是否有恢复路径（刷新/导出）？

– [ ] Retryable 是否有倒计时或升级入口？

– [ ] 是否引用了意图契约 ERR-001？

5.3 编译为 JSON Schema（给结构校验）

{

“properties”: {

“error_severity”: {

“enum”: [“fatal”, “transient”, “retryable”, “degraded”]

},

“color_token”: {

“enum”: [“status.critical”, “status.neutral”, “status.warning”, “status.info”]

}

},

“required”: [“error_severity”, “color_token”, “user_action”]

}

5.4 编译为 CI 规则（给自动化流水线）

rules:

error-severity-color:

selector: “[data-severity]”

mapping:

fatal: { color: “#cf1322”, bg: “rgba(207,19,34,0.15)” }

transient: { color: “#a0a0a0”, bg: “#1e1e22” }

retryable: { color: “#f5a623”, bg: “rgba(212,136,6,0.15)” }

degraded: { color: “#4a9eff”, bg: “rgba(22,119,255,0.15)” }

forbidden: { same_color_for_all: true }

编译的价值：设计师写一次，四端自动消费，零遗漏。

六、契约库：让设计规范像代码一样管理

6.1 目录结构

contracts/ # 契约文件

├── err-001.yaml # 错误状态语义分级

├── pro-001.yaml # 过程状态认知显化

├── bnd-001.yaml # 边界动作权利区分

├── act-001.yaml # 高危操作风险约束

└── alr-001.yaml # 告警文案语义降级

schema/ # 结构校验规则

├── intent-schema.json # YAML 结构定义

└── semantic-token-schema.json # 语义令牌校验

snapshots/ # 版本快照

├── v1.0.0/ # 版本 1.0.0 快照

└── v1.1.0/ # 版本 1.1.0 快照

changesets/ # 变更记录

├── 2026-06-01-add-err001.md

└── 2026-06-20-add-degraded.md

compiled/ # 编译输出

├── prompt/ # Prompt 前缀

├── checklist/ # 走查清单

├── json-schema/ # JSON Schema

└── ci-rules/ # CI 规则

6.2 版本管理

# 版本 1.0.0 → 1.1.0 的变更

version: “1.1.0”

changes:

– “增加 degraded 级别（部分功能可用）”

– “优化同义词防火墙匹配逻辑”

– “修复 retryable 倒计时字段缺失问题”

Git Diff 自动触发影响面分析： 当 err-001.yaml 变更时，自动通知所有消费该契约的 AI 工具重编译。

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

7.1 为什么设计师不需要会写代码

YAML 契约不是代码，是设计意图的翻译层。

# 设计师写的：语义约束

destructive_action:

description: “不可逆的数据销毁操作”

visual_mapping:

color_token: “status.critical”

button_style: “outline_danger”

llm_constraints:

– “必须包含二次确认弹窗”

– “文案必须明确说明’此操作不可恢复'”

这段 YAML 里：

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

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

前端工程师拿到这份 YAML，可以翻译成 Tailwind、Material UI、DevUI 或任何框架。契约是跨框架的。

7.2 组织经济价值

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

八、快速开始：三步写第一份契约

步骤 1：诊断语义缺失（从阶段一组件语义快照与模式诊断导入）

诊断报告：”ChatGPT 错误状态缺少 error_severity 语义令牌，违反 ERR-001 模式。”

步骤 2：定义语义令牌（写 YAML）

intent_id: “ERR-001”

semantic_tokens:

error_severity:

fatal:

visual_mapping:

color_token: “status.critical”

user_action:

– label: “刷新页面”

步骤 3：编译并验证

# 编译为 4 种格式

schema-compiler compile intent/err-001.yaml –output compiled/

# 验证输出

schema-compiler validate compiled/prompt/err-001.md

schema-compiler validate compiled/checklist/err-001.md

九、下一步：阶段三验证闭环

阶段二产出 YAML 契约后，阶段三回答：”怎么证明契约真的防住了语义漂移？”

三层验证工具：

• 语义分级器：输入错误文案，1 秒返回语义分级
• JSON 语义校验器：粘贴组件快照，自动匹配模式
• 四层推演引擎：语法 → 语义 → 安全 → 美感

验证指标目标：

• 语义返工率
• 规范同步时间
• 走查覆盖率

十、仓库与资源

• GitHub 仓库：https://github.com/2436041978-ops/semantic-pipeline
• 在线体验：https://2436041978-ops.github.io/semantic-pipeline/
• 完整文档：语雀 Schema-As-Code 知识库

本文是阶段二的核心：把设计意图翻译成机器可读的语义规则。

快速阅读：

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

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