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

语义规范体系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 TokenFigma / Tokens Studio / Style Dictionarycolor:primary:#1677FFdanger:#EF4444warning:#F59E0Bfont:family:Intersize:14pxDesign Token 回答的问题“这个按钮用什么颜色、什么字体”它的作用是让设计稿和代码里的颜色值保持一致设计系统更新时改一处全局生效。语义令牌解决什么问题语义令牌管的是语义层的一致性# 语义令牌Schema-As-Codesemantic_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语义令牌Semantic Token管什么视觉层长什么样语义层意味着什么写什么色值、字号、间距状态级别、认知阶段、边界强度谁消费前端CSS/组件库AI / 机器Prompt / 校验规则变更时改色值全局变色改语义映射全局改变理解方式例子color: #EF4444color_token: status.critical关键洞察Design Token 是视觉字典语义令牌是语义字典。两者互补不是替代。用户看到的界面 ↓ Design Token管颜色、字体、间距 ↓ 语义令牌管颜色代表什么、文案传递什么 ↓ 机器理解的规则没有语义令牌AI 知道用红色但不知道红色代表致命。三、语义令牌的四大命名空间我设计语义令牌时把常见的语义场景归纳为四大类每类一个命名空间1.status.*—— 状态级别回答的问题“这件事有多严重”令牌含义典型场景视觉映射示例status.critical致命系统故障、数据丢失红色脉冲 八边形警告status.warning警告限流、降级、可恢复错误黄色提示 时钟图标status.info信息提示、说明、部分可用蓝色静态 信息图标status.success成功保存完成、操作成功绿色静态 对勾图标status.neutral中性加载中、等待中灰色动画 旋转图标为什么不是直接写颜色因为同一个status.critical在不同设计系统里可以映射到不同的色值设计系统 A#EF4444Tailwind 红设计系统 B#F5222DAnt Design 红设计系统 C#FF4D4FDevUI 红语义令牌不关心具体色值只关心语义映射关系。设计系统更新时改映射表语义令牌不变。2.phase.*—— 认知阶段回答的问题“AI 现在处于什么阶段用户在等什么”令牌含义典型场景视觉映射示例phase.research检索搜索信息、查找来源蓝色 放大镜图标 来源计数phase.analysis综合对比多源、识别分歧黄色 大脑图标 共识度phase.check验证核对链接、验证事实绿色 盾牌图标 验证状态phase.output生成生成答案、输出结果紫色 文档图标 引用索引为什么需要阶段令牌Perplexity 的 “Searching…” “Reading…” “Wrapping up…” 让用户困惑——不知道 AI 是在查资料还是开始编答案。有了phase.*系统可以显化认知阶段现在处于检索阶段已找到 5 个来源其中 4 个一致。“用户知道这是查出来的不是猜出来的”。3.boundary.*—— 边界强度回答的问题“系统拒绝用户时权利边界在哪里”令牌含义典型场景视觉映射示例boundary.soft软性拒绝拒绝请求但保留会话黄色提示条 保留输入框boundary.hard强制终止终止会话清空上下文红色退出面板 数据政策说明boundary.review升级审核提交人工审核蓝色提示 预计审核时间为什么需要边界令牌Claude 的 “I can’t help with that” 和 “Claude has ended this chat” 在界面上都是拒绝——用户不知道对话还在不在、数据丢没丢。有了boundary.*系统区分软性拒绝继续聊vs 强制终止开新会话。用户明确知道自己的权利状态。4.action.*—— 操作性质回答的问题“用户点击这个按钮后后果是什么”令牌含义典型场景视觉映射示例action.destructive破坏性删除、清空、不可逆红色空心 二次确认 输入验证action.constructive建设性保存、提交、创建蓝色实心 成功反馈action.neutral中性取消、关闭、返回灰色描边 无后果为什么需要操作令牌AI 生成删除账户按钮时默认给蓝色实心确认——因为 Prompt 里只说生成一个删除按钮没有说这是不可逆操作。有了action.destructive系统知道这个按钮后果是破坏性的必须红色空心、必须二次确认、必须输入账户名验证。四、语义域组件在什么场景下语义令牌定义了是什么但同一个组件在不同场景下语义可能完全不同。我设计了三个语义域Semantic Domainobservational—— 观察型特征用户被动接收信息不需要操作。典型组件错误提示、状态通知、告警卡片。约束禁止要求用户输入必须提供明确的退出路径文案必须说明后果不能只说出错了transactional—— 交易型特征用户主动触发操作系统必须反馈结果。典型组件提交按钮、表单、确认弹窗。约束必须提供操作结果反馈成功/失败状态必须明确不可逆操作必须有二次确认conversational—— 对话型特征用户和系统双向对话上下文持续累积。典型组件聊天界面、问答系统、AI 助手。约束必须保留对话上下文边界动作必须说明会话状态拒绝时必须提供替代建议为什么需要语义域同一个 Alert 组件在observational域系统故障→ 用户被动看不能要求输入在transactional域表单验证→ 用户主动填必须给反馈在conversational域对话中断→ 上下文要保留不能说断就断没有语义域系统不知道这个组件在用户流程中扮演什么角色约束就会错位。五、不可变边界红线语义令牌定义应该是什么不可变边界定义绝对不能是什么。我把它理解为语义红线——一旦触碰系统必须阻断。示例ERR-001 的不可变边界immutable_boundaries:-boundary_type:safetyrule:禁止直接执行删除操作而不显示二次确认violation_action:block-boundary_type:clarityrule:禁止在错误状态文案中使用模糊词汇如出错了、Something went wrongviolation_action:block-boundary_type:consistencyrule:禁止将不同严重级别的错误使用相同视觉表达violation_action:block为什么叫不可变这些边界不是建议是强制规则block一旦触发直接阻断生成返回修改建议warn触发后警告但允许人工确认后放行escalate触发后升级人工审核与语义令牌的区别语义令牌 fatal 应该用什么颜色推荐性映射不可变边界 “fatal 绝对不能和 retryable 用同一种颜色”强制性约束六、完整示例ERR-001 的语义规范拆解把上面的概念串起来看 ERR-001 是怎么从语义规范翻译成YAML 契约的语义规范层设计师的意图设计意图 - 错误状态必须按后果严重程度分级 - 用户必须知道多严重和该做什么 - 系统绝对不能让不同级别的错误长得一样 语义规范 - 状态级别fatal / transient / retryable / degradedstatus.* - 语义域observational用户被动接收 - 不可变边界不同级别不能用相同颜色语义令牌层机器可读的标识# 语义令牌映射status.critical → 致命错误 → 红色脉冲 status.neutral → 可恢复错误 → 灰色加载 status.warning → 限流提示 → 黄色倒计时 status.info → 部分可用 → 蓝色提示YAML 契约层可执行的规则intent_id:ERR-001semantic_domain:observationalsemantic_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_historyllm_constraints:-必须明确告知用户对话上下文可能已丢失transient:description:网络抖动系统可自动恢复visual_mapping:color_token:status.neutral# ← 语义令牌motion_token:spinner# ← 语义令牌icon_token:loader# ← 语义令牌user_action:-label:等待自动恢复action:waitllm_constraints:-禁止红色背景避免情绪过载immutable_boundaries:-boundary_type:consistencyrule:禁止将不同严重级别的错误使用相同视觉表达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:#EF4444bg:solidicon:warning.svgtext:Something went wrongbutton:重试问题前端看了知道用红色但不知道红色代表什么AI 看了知道生成红色按钮但不知道什么场景下该用什么红色设计系统更新红色色值时YAML 要全部改一遍After有了语义规范YAML 写语义令牌# 错误状态规范有语义层semantic_tokens:error_severity:fatal:visual_mapping:color_token:status.critical# ← 语义令牌不是色值motion_token:pulse.red.urgenticon_token:alert.octagonuser_action:[刷新页面,导出历史]transient:visual_mapping:color_token:status.neutral# ← 同一组件不同语义不同令牌motion_token:spinnericon_token:loaderuser_action:[等待自动恢复]改变前端看了知道fatal 用 status.critical去映射表查具体色值AI 看了知道fatal 必须红色脉冲 刷新/导出按钮设计系统更新色值时改映射表YAML 完全不变九、总结Schema-As-Code 的 YAML 契约里写的不是颜色值、不是文案、不是 Design Token。写的是语义令牌——机器可读的语义标识定义这个界面元素在这个场景下代表什么。四大命名空间status.*—— 状态级别多严重phase.*—— 认知阶段在干什么boundary.*—— 边界强度权利在哪action.*—— 操作性质后果是什么三层语义域observational—— 用户被动看transactional—— 用户主动点conversational—— 用户和系统聊一条红线immutable_boundaries—— 绝对不能做什么理解了这个语义规范体系再看 YAML 格式就知道每个字段填的不是视觉值是语义映射。