起点课堂会员权益
职业体系课特权
线下行业大会特权
个人IP打造特权
30+门专项技能课
1300+专题课程
12场职场软技能直播
12场求职辅导直播
12场专业技能直播
会员专属社群
荣耀标识YAML契约格式：理解了语义规范体系后怎么写语义规则
当AI开始接管界面生成，设计师的角色正从规范制定者转变为语义翻译者。本文揭秘如何用YAML契约将设计意图转化为机器可读的Schema-As-Code，通过7个核心字段精准定义错误状态分级、视觉映射规则和AI强制约束，为AI生成内容设置不可逾越的语义边界。
本文是阶段二《设计师作为”语义翻译者”》的实操专题，回答一份 YAML 契约从空白文档到完整文件的写作过程。
阶段二的核心判断是：传统设计规范面向”人”阅读，机器无法消费，AI 生成内容时不受语义约束。Schema-As-Code 的解法是将设计意图形式化为 YAML 语义契约，在生成前预置边界与规则。
本文回答 YAML 语义契约怎么写。传统规范人读机器不读，Schema-As-Code 将其形式化为 YAML，预置生成边界。YAML 不是色值或文案，是语义令牌。
阶段一：[组件语义快照与模式诊断：AI 生成界面的第一道检查]
方法论总纲与开源仓库：[把设计规范写成代码格式，是所有 AI 工具的上游约束方法论]
一、YAML 契约的整体结构
一份 YAML 契约由 6 个顶层字段组成。你可以把它理解成一份”设计意图的身份证”——每个字段回答一个特定的问题。
intent_id: “我是谁？”
description: “我解决什么问题？”
version: “我是哪个版本？”
applicable_products: “我在哪些产品里生效？”
semantic_tokens: “我定义了什么语义？”
immutable_boundaries: “我画了什么红线？”
llm_constraints: “我对 AI 有什么强制要求？”
下面逐个拆解。
二、字段 1：intent_id —— 契约的身份证号
设计意图
每个契约都需要一个唯一标识，就像设计稿的编号一样。当你和前端、AI 工程师沟通时，说”ERR-001″比说”那个错误状态分级的东西”要精确得多。
命名规范
intent_id: “ERR-001”
# 格式：[领域缩写]-[三位序号]
# ERR = Error（错误状态）
# PRO = Process（过程状态）
# BND = Boundary（边界动作）
# ACT = Action（操作按钮）
# ALR = Alert（告警状态）
常见错误
❌ 用自然语言命名：intent_id: “错误状态分级”——不方便引用和版本管理
✅ 用结构化编号：intent_id: “ERR-001″——精确、可排序、可检索
三、字段 2：description —— 一句话说清契约解决什么问题
设计意图
description 是给人类看的摘要。当你打开一份契约文件，第一眼就要知道”这份契约是干嘛的”。
写法
description: “错误状态后果差异未分级：系统无法区分致命错误、网络抖动、限流提示和降级错误，导致用户无法判断后果严重程度。”
好 description 的标准
- 包含问题现象（用户看到什么）
- 包含根因（系统缺了什么）
- 包含后果（用户因此遇到什么困扰）
❌ 不好的写法：description: “错误状态规范”——太笼统，不知道解决什么问题
✅ 好的写法：见上方示例——现象 + 根因 + 后果，一目了然
四、字段 3：version —— 语义版本号
设计意图
设计规范会迭代，YAML 契约也会迭代。version 字段让你知道”这份契约是第几版”，和代码的版本管理一样重要。
语义化版本规范
version: “1.0.0”
# 格式：主版本.次版本.修订号
# 主版本：破坏性变更（如删除某个 severity 级别）
# 次版本：功能新增（如增加新的 visual_mapping）
# 修订号：bug 修复（如文案微调）
版本变更示例
# v1.0.0：初始版本，包含 fatal/transient/retryable 三级
# v1.1.0：新增 degraded 级别（次版本升级）
# v1.1.1：修正 fatal 的文案描述（修订号升级）
# v2.0.0：删除 retryable 级别，合并到 transient（主版本升级，破坏性变更）
五、字段 4：applicable_products —— 契约在哪些产品里生效
设计意图
不同产品可能有不同的设计规范。applicable_products 定义了这份契约的生效范围，避免”一刀切”。
写法
applicable_products:
– “ChatGPT”
– “文心一言”
– “通义千问”
– “Kimi”
– “豆包”
– “DeepSeek”
# 不生效的产品：Claude（因为 Claude 的错误状态设计不同）
作用域控制
# 全局生效（所有产品）
applicable_products:
– “*”
# 特定产品生效
applicable_products:
– “ChatGPT”
– “Kimi”
# 排除特定产品
applicable_products:
– “*”
excluded_products:
– “Claude” # Claude 有自己的错误状态规范
六、字段 5：semantic_tokens —— 契约的核心：语义令牌定义
设计意图
这是 YAML 契约最重要的字段。semantic_tokens 定义了”这个场景下有哪些语义级别，每个级别映射到什么视觉、文案和行动”。
结构拆解
semantic_tokens:
[语义令牌组名]: # 如 error_severity、process_phase
[级别名]: # 如 fatal、transient、retryable
description: “…” # 这个级别的含义
visual_mapping: {…} # 视觉映射（颜色、动效、图标）
user_action: […] # 用户行动（按钮、操作）
llm_constraints: […] # 针对这个级别的 LLM 强制约束
ERR-001 完整示例
semantic_tokens:
error_severity: # 语义令牌组：错误严重程度
fatal: # 级别 1：致命错误
description: “系统级故障，对话上下文可能丢失”
visual_mapping: # 视觉映射
color_token: “status.critical” # 颜色令牌：致命状态
motion_token: “pulse.red.urgent” # 动效令牌：红色脉冲
icon_token: “alert.octagon” # 图标令牌：八边形警告
background: “red.500/10” # 背景：10% 透明度红色
user_action: # 用户行动
– label: “刷新页面” # 主行动：刷新
action: “refresh”
priority: 1 # 优先级：1（最高）
– label: “导出历史” # 次行动：导出
action: “export_history”
priority: 2
llm_constraints: # LLM 强制约束
– “必须明确告知用户对话上下文可能已丢失”
– “禁止仅显示’出错了’等模糊文案”
– “必须提供恢复路径（刷新或导出）”
transient: # 级别 2：网络抖动
description: “网络层故障，系统可自动恢复”
visual_mapping:
color_token: “status.neutral” # 颜色令牌：中性状态
motion_token: “spinner” # 动效令牌：加载动画
icon_token: “loader” # 图标令牌：加载图标
background: “neutral.800” # 背景：深灰色
user_action:
– label: “等待自动恢复” # 主行动：等待
action: “wait”
priority: 1
– label: “手动重试” # 次行动：重试
action: “retry”
priority: 2
llm_constraints:
– “必须显示自动重试进度”
– “禁止使用红色背景（避免情绪过载）”
– “必须说明预计恢复时间”
retryable: # 级别 3：限流/流控
description: “请求频率已达上限，用户可自助恢复”
visual_mapping:
color_token: “status.warning” # 颜色令牌：警告状态
motion_token: “none” # 动效：无（不需要紧急感）
icon_token: “clock” # 图标令牌：时钟
background: “amber.500/10” # 背景：10% 透明度黄色
user_action:
– label: “等待倒计时” # 主行动：等待
action: “wait_countdown”
countdown_field: “retry_after” # 倒计时字段名
priority: 1
– label: “升级套餐” # 次行动：升级
action: “upgrade”
priority: 2
llm_constraints:
– “必须显示剩余等待时间（秒/分钟）”
– “必须提供升级/扩容路径”
– “禁止使用红色（避免用户恐慌）”
degraded: # 级别 4：部分可用
description: “部分功能可用，可继续生成”
visual_mapping:
color_token: “status.info” # 颜色令牌：信息状态
motion_token: “none” # 动效：无
icon_token: “info.circle” # 图标令牌：信息圆圈
background: “blue.500/10” # 背景：10% 透明度蓝色
user_action:
– label: “继续生成” # 主行动：继续
action: “continue”
priority: 1
– label: “简化问题重试” # 次行动：简化重试
action: “retry_simplified”
priority: 2
llm_constraints:
– “必须说明哪些功能仍然可用”
– “必须提供替代方案（如简化问题）”
– “禁止显示纯技术错误码（如 500 Internal Error）”
关键设计原则
七、字段 6：immutable_boundaries —— 不可突破的红线
设计意图
有些规则是”绝对不能违反”的，比如高危操作必须二次确认。immutable_boundaries 定义了这些红线，一旦违反，系统直接阻断。
结构
immutable_boundaries:
– boundary_type: “safety” # 边界类型：安全
constraint_rule_ref: “rules/destructive-action.yaml” # 引用的规则文件
violation_action: “block” # 违反时的动作：阻断
– boundary_type: “compliance” # 边界类型：合规
constraint_rule_ref: “rules/data-retention.yaml”
violation_action: “escalate” # 违反时的动作：升级人工审核
ERR-001 示例
immutable_boundaries:
– boundary_type: “safety”
rule: “禁止直接执行删除操作而不显示二次确认”
violation_action: “block”
# 如果 AI 生成的代码里没有二次确认，直接阻断，不允许进入生产环境
– boundary_type: “semantic”
rule: “禁止将 fatal 错误显示为静态灰色（必须用红色脉冲）”
violation_action: “block”
# 如果 fatal 错误用了灰色静态背景，直接阻断
与 semantic_tokens 的区别
八、字段 7：llm_constraints —— 对 AI 的强制要求
设计意图
LLM 在生成内容时可能会”自由发挥”，比如把 Critical 写成”严重”，或者漏掉二次确认。llm_constraints 是给 AI 的”强制指令”——不是建议，是必须遵守。
写法
llm_constraints:
– “必须明确告知用户对话上下文可能已丢失” # 信息完整性约束
– “禁止仅显示’出错了’等模糊文案” # 文案精度约束
– “必须提供恢复路径（刷新或导出）” # 行动完整性约束
– “禁止将 fatal 错误显示为静态灰色” # 视觉映射约束
– “禁止在 retryable 场景使用红色背景” # 场景匹配约束
约束的三种类型
九、完整契约示例：ERR-001（从头到尾）
# 契约文件：intent/err-001.yaml
# 作者：设计师 [姓名]
# 创建日期：2026-06-30
# 最后更新：2026-06-30
# 变更记录：v1.0.0 初始版本，包含 fatal/transient/retryable/degraded 四级
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”
background: “red.500/10”
user_action:
– label: “刷新页面”
action: “refresh”
priority: 1
– label: “导出历史”
action: “export_history”
priority: 2
llm_constraints:
– “必须明确告知用户对话上下文可能已丢失”
– “禁止仅显示’出错了’等模糊文案”
– “必须提供恢复路径”
transient:
description: “网络抖动，系统可自动恢复”
visual_mapping:
color_token: “status.neutral”
motion_token: “spinner”
icon_token: “loader”
background: “neutral.800”
user_action:
– label: “等待自动恢复”
action: “wait”
priority: 1
– label: “手动重试”
action: “retry”
priority: 2
llm_constraints:
– “必须显示自动重试进度”
– “禁止使用红色背景”
– “必须说明预计恢复时间”
retryable:
description: “请求频率已达上限”
visual_mapping:
color_token: “status.warning”
motion_token: “none”
icon_token: “clock”
background: “amber.500/10”
user_action:
– label: “等待倒计时”
action: “wait_countdown”
countdown_field: “retry_after”
priority: 1
– label: “升级套餐”
action: “upgrade”
priority: 2
llm_constraints:
– “必须显示剩余等待时间”
– “必须提供升级路径”
– “禁止使用红色”
degraded:
description: “部分功能可用”
visual_mapping:
color_token: “status.info”
motion_token: “none”
icon_token: “info.circle”
background: “blue.500/10”
user_action:
– label: “继续生成”
action: “continue”
priority: 1
– label: “简化问题重试”
action: “retry_simplified”
priority: 2
llm_constraints:
– “必须说明哪些功能仍然可用”
– “必须提供替代方案”
– “禁止显示纯技术错误码”
immutable_boundaries:
– boundary_type: “safety”
rule: “禁止直接执行删除操作而不显示二次确认”
violation_action: “block”
– boundary_type: “semantic”
rule: “禁止将 fatal 错误显示为静态灰色”
violation_action: “block”
十、写作检查清单：写完一份契约后对照
– [ ] intent_id 是否符合命名规范（领域缩写-三位序号）？
– [ ] description 是否包含现象 + 根因 + 后果？
– [ ] version 是否使用语义化版本（主.次.修）？
– [ ] applicable_products 是否明确了生效范围？
– [ ] semantic_tokens 是否每个级别都有 visual_mapping + user_action + llm_constraints？
– [ ] visual_mapping 是否使用了语义令牌（color_token）而非写死色值（color: #EF4444）？
– [ ] user_action 是否与后果严重程度匹配（fatal→刷新/导出，transient→等待/重试）？
– [ ] llm_constraints 是否每条都可被机器校验（有明确的”必须/禁止/只能”）？
– [ ] immutable_boundaries 是否定义了不可突破的红线？
– [ ] 是否包含变更记录和作者信息？
十一、常见错误与修正
错误 1：写死色值，不用语义令牌
❌ 错误写法：
visual_mapping:
color: “#EF4444” # 写死色值，设计系统更新时契约失效
✅ 正确写法：
visual_mapping:
color_token: “status.critical” # 语义令牌，设计系统更新时映射关系自动同步
错误 2：用户行动与后果不匹配
❌ 错误写法：
# fatal 错误（对话已丢）只给”重试”按钮
user_action:
– label: “重试”
action: “retry”
✅ 正确写法：
# fatal 错误需要”刷新”或”导出”，因为对话已丢，重试无效
user_action:
– label: “刷新页面”
action: “refresh”
– label: “导出历史”
action: “export_history”
错误 3：LLM 约束不可执行
❌ 错误写法：
llm_constraints:
– “文案要友好一点” # 无法机器校验，什么叫”友好”？
✅ 正确写法：
llm_constraints:
– “禁止仅显示’出错了’等模糊文案” # 可机器校验：检查文案是否包含”出错了”
– “必须包含后果说明” # 可机器校验：检查文案是否包含”可能已丢失”等后果词
十二、下一步：写完后怎么编译
写完 YAML 契约后，下一步是编译为消费格式。详见下一章《从契约到消费格式：编译》。
一份 ERR-001.yaml 会编译为：
- Prompt 前缀：供 Claude Code / Cursor 使用
- JSON Schema：供结构校验使用
- Checklist：供设计师人工走查使用
- CI 规则：供自动化流水线使用
本文由 @阿基拉de_Akir 原创发布于人人都是产品经理。未经作者许可，禁止转载
题图来自Unsplash，基于CC0协议
- 目前还没评论，等你发挥！
