① 语义令牌表：把语义概念编码成离散枚举

框架设计背景本文是 Schema-As-Code 证据链 的框架设计站属于主题行的第一个关键设计——语义令牌表Semantic Token Table。在前序章节中阶段一 Guard 结构化诊断通过组件语义快照与三层判定模型发现了6 个漂移模式语义域建立了组件是空容器语义由场景定义的覆盖层模型。但语义要能被机器识别、校验与生成必须先解决一个编码问题如何把语义概念变成机器可运算的离散值本文要建立的正是 Schema-As-Code 的语义编码层——当语义规范体系需要被写入YAML 契约时语义必须以离散令牌的形式存在而非自然语言描述。1. 问题语义是感觉还是可运算的值行业现状中语义以自然语言或视觉样式存在设计师说这个要用红色前端看到 #EF4444AI 生成工具看到 color: red。但红色在不同场景下含义完全不同——在语义域的 transactional 域它是阻断确认在 observational 域它可能是非法绑定跨层禁止。当语义以颜色值、文案词或感觉的形式流动时机器无法区分同一个红色在不同场景下是否合法。6 个漂移模式中的 ERR-001错误状态后果差异未分级根因正是如此致命错误、网络抖动、限流、降级四种完全不同的后果共用同一种红色——因为机器看到的只是 color: #EF4444而不是 error_severity.fatal 与 error_severity.retryable 的语义区别。没有离散令牌就没有机器可执行的判定依据。2. 为什么自然语言守不住语义不可运算设计规范文档用自然语言描述语义“致命错误用红色脉冲限流用黄色时钟”。但自然语言对机器是不可运算的●AI 生成工具读不懂致命错误与限流的区别它的训练语料里只有 red 和 yellow●前端工程师看到的是 Design Token color-danger 和 color-warning但 danger 与 warning 的语义边界没有机器定义AI 可以把 color-danger 用在成功状态●验收走查依赖人的主观判断感觉不对无法转化为可复现的校验规则。组件语义快照的 6 字段记录法已经证明观察界面时需要记录 component_type、visual、copy、interaction、context 等维度。但这些字段的值如果是自由文本如 color: “red”仍然不可运算。语义令牌表的作用就是把红色编码为 status.critical把限流编码为 error_severity.retryable——让语义成为机器可查询、可校验、可拦截的离散值。3. 设计思路把语义概念编码成离散枚举本文的设计思路是三个递进命题●语义概念 → 离散令牌error_severity 不是文档里的段落而是包含 fatal、transient、retryable、degraded 四个枚举值的令牌表每个枚举值绑定唯一的视觉映射status.critical → 红色脉冲与行动约束必须提供恢复路径●令牌 → 字典注册所有语义令牌在语义字典中注册成为组织级唯一信源。契约YAML不定义令牌只引用令牌●令牌 → 可执行规则编译管线将令牌表编译为 Prompt 前缀注入 AI 上下文、JSON Schema组件 Props 校验、CI 规则流水线拦截——同一组离散值在不同工具链中以不同格式执行同一语义。这与语义规范体系的关系语义规范体系定义有哪些语义维度语义令牌表定义每个维度下有哪些离散值。没有令牌表规范体系只是分类框架没有规范体系令牌表只是孤立枚举。3.1 把意思变成编号机器看不懂红色代表很危险机器看得懂 status.critical。把连续的自然语言描述变成离散的编号枚举值。Schema-As-Code 语义编码层 · ① 语义令牌表演示环境里的例子不说红色、很紧急、要刷新 → 说 status.critical不说黄色、等一等、能恢复 → 说 status.warning不说灰色、加载中、不用管 → 说 status.neutral为什么这样做自然语言有同义词“严重≈Critical≈危急”机器会搞混。编号没有同义词一个编号只对应一个意思。3.2 一个编号只绑定一套视觉status.critical 只能是红色脉冲 八边形图标不能今天是红色明天变成橙色。编号和视觉参数是锁死的一对一映射。Schema-As-Code 语义编码层 · ① 语义令牌表演示环境里的例子编号颜色动画图标按钮样式status.critical红色脉冲八边形必须二次确认status.warning黄色静态三角显示恢复时间status.info蓝色静态信息可自动消失status.neutral灰色旋转加载无为什么这样做以前设计规范写错误用红色但不同前端可能用不同红。编号锁死后机器查表就知道唯一答案。3.3 同一个编号能翻译成三种格式设计师写了一份 status.critical 的定义机器自动把它变成三种东西给三种不同的人用。Schema-As-Code 语义编码层 · ① 语义令牌表演示环境里的三种格式给谁用格式内容给 AI 写界面的工程师Prompt 前缀“生成致命错误时必须用红色脉冲…”给校验代码的机器JSON Schema{“color_token”: “status.critical”, “motion_token”: “pulse.red.urgent”}给 CI 流水线阻断规则“如果在 observational 域用 critical阻断合并”为什么这样做设计师只写一次三种消费方自动拿到自己需要的东西。不用设计师给工程师写一遍、给运维写一遍、给测试写一遍。3.4 同一个颜色不同编号代表不同意思机器看到 #EF4444红色不知道这是系统故障还是删除按钮。必须看编号才知道。Schema-As-Code 语义编码层 · ① 语义令牌表演示环境里的对比编号都是红色但意思完全不同场景status.critical红色系统故障对话可能丢了错误状态action.destructive红色删除账户数据永久没了操作按钮为什么这样做以前设计规范只规定红色用在危险场景但机器不知道危险有 10 种。编号把哪种危险说清楚了。3.5 编号不能跨层乱用status.critical红色脉冲只能在错误状态里用不能拿到提示信息里用。跨层使用会被机器自动阻断。Schema-As-Code 语义编码层 · ① 语义令牌表演示环境里的例子合法status.critical 用在消息流中断系统故障非法status.critical 用在限流提示只是等一等不是故障机器拦截如果 AI 把限流提示做成红色脉冲CI 直接阻断代码合不进去为什么这样做防止红色滥用。以前所有错误都用红色用户分不清多严重。现在每个编号有指定的使用范围超范围就报错。4. 本文的核心命题把语义编码成离散令牌必须翻译成可验证的框架设计。本文回答三个命题命题验证标准语义可被离散编码error_severity 的四级后果差异能被编码为四个互斥枚举值而非自然语言描述令牌绑定唯一视觉映射每个令牌如 retryable绑定且仅绑定一组视觉参数status.warning 时钟图标 倒计时不可被自由替换令牌可被机器消费同一组令牌能被编译为 Prompt 前缀、JSON Schema、CI 规则三种格式在不同工具链中执行同一语义判定一、调整前四个角色的真实反馈在没有语义令牌之前各角色在界面层看到的世界用他们自己的话说‍前端与 AI 工程师的真实反馈“致命错误和限流提示被渲染成了同一种红色背景条。”AI 生成工具里只有 Design Token——color.danger: { value: “#EF4444” }。红色是一个色值不附带任何场景含义。同一款 AI 对话产品中对话可能已丢失的致命错误与请求太频繁请等 30 秒的限流提示长得一模一样色板合规、对比度达标视觉走查挑不出任何毛病但用户从界面上读不到两者的区别。‍设计师与产品经理的真实反馈“同一个 alert三个人三种理解每个人都没错。”组件库里的 Alert 只是视觉组件——圆角、图标位、关闭按钮。它不知道自己在交易确认场景里是阻断性语义在信息展示场景里是旁观性语义。前端理解为弹窗设计师指的是顶部通知条两个人都对因为没有任何注册表裁定。‍前端与 AI 工程师的另一条真实反馈“LLM 把 Critical 降级为’严重’代码里查不出来。”在 LLM 的词汇表里“Critical和严重是近义词。AI 生成告警时把 “Critical” 替换为严重”、把 “Data Loss Risk” 替换为请稍后重试——情绪权重在概率性输出中被随机降级而没有任何机制判定这是违规。‍DesignOps 与设计系统负责人的真实反馈“规范写在文档平台里人可能看漏AI 工具完全不可见。”错误状态分四级供人阅读机器查询不了更校验不了。汇总成一张表工具 / 环节界面层呈现状态缺失什么AI 生成工具只有色值与样式语义靠概率猜这个红代表什么的机器可读定义组件库组件只有视觉属性组件在不同场景下的语义身份文案生成同义词自由替换关键术语的权重锚定规范文档供人阅读机器可查询、可校验的注册表这四条反馈指向同一个根因语义没有被编码成机器可读的东西。红色只是色值组件只是容器术语只是字符串——机器拿不到语义就只能靠概率猜。二、把语义编码为离散令牌不是自创概念2003年Eric Evans 在《Domain-Driven Design》中提出 Bounded Context限界上下文——同一个术语在不同业务边界内有不同含义域内唯一定义互不污染。这与我的语义域设计是同一逻辑同一个 Alert 在 transactional 域是阻断确认在 observational 域是旁观通知条——域内唯一定义域间含义不同。同期Evans 定义了 Anti-Corruption Layer防腐层——边界之间做翻译与隔离非法引用被拒绝。这与我的跨层禁止规则设计对应status.critical 不可用于 observational 域非法绑定在编译前置校验时直接阻断。域边界靠机器规则维护。工业界也在做。Microsoft Azure 将 ACL 作为官方架构模式收录W3C DTCG 已定义 Semantic Token 层。我的设计在其之上扩展了行为约束与跨域规则。但行业也有反面的声音。许多设计系统的语义令牌只是换名color-red-500 改叫 color-danger没有场景定义组件分类模型在 AI 生成时代系统性失效 自带语义导致升级时语义跟着重写。这恰恰反证了我为什么要设计覆盖层模型——语义必须外赋于组件空容器由域边界统一定义可被机器校验。参考链接●Eric Evans · DDD Reference 2015https://www.domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf●Microsoft Azure · Anti-Corruption Layer Patternhttps://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer●W3C DTCG · Design Tokens Format Module 2025.10https://www.designtokens.org/TR/2025.10/format/●W3C · Design Tokens Community Grouphttps://www.w3.org/community/design-tokens/三、关键设计语义令牌表3.1 四大命名空间码本原子集语义令牌按回答的问题分为四个命名空间每个令牌是离散索引编译管线查表后展开为连续约束status._ —— 这件事有多严重令牌含义视觉映射示例status.critical致命系统故障、数据丢失红色脉冲 八边形警告status.warning警告限流、降级、可恢复错误黄色提示 时钟图标status.info信息提示、说明、部分可用蓝色静态 信息图标status.success成功保存完成、操作成功绿色静态 对勾图标status.neutral中性加载中、等待中灰色动画 旋转图标【Schema-As-Code 语义编码层 · ① 语义令牌表演示环境status._ 命名空间令牌卡片】对应 HTML 演示环境位置页面中status._标签页下的五个彩色令牌卡片critical 红脉冲 / warning 黄时钟 / info 蓝信息 / success 绿对勾 / neutral 灰旋转每张卡片展示令牌名、含义、视觉映射颜色动画图标按钮样式。phase._ —— AI 处于什么阶段用户在等什么令牌含义视觉映射示例phase.research检索搜索信息、查找来源蓝色 放大镜图标 来源计数phase.analysis综合对比多源、识别分歧黄色 大脑图标 共识度phase.check验证核对链接、验证事实绿色 盾牌图标 验证状态phase.output生成生成答案、输出结果紫色 文档图标 引用索引boundary._ —— 系统拒绝用户时权利边界在哪里令牌含义视觉映射示例boundary.soft软性拒绝拒绝请求但保留会话黄色提示条 保留输入框boundary.hard强制终止终止会话清空上下文红色退出面板 数据政策说明boundary.review升级审核提交人工审核蓝色提示 预计审核时间action._ —— 用户点击后后果是什么令牌含义视觉映射示例action.destructive破坏性删除、清空、不可逆红色空心 二次确认 输入验证action.constructive建设性保存、提交、创建蓝色实心 成功反馈action.neutral中性取消、关闭、返回灰色描边 无后果3.2 字典注册的 6 个语义绑定v1.0.0语义字典v1.0.0 注册的 6 个语义绑定构成组织级语义码本的最小可行原子集语义绑定含义核心约束注入跨层禁止示例status.critical阻断性、可能不可恢复红色脉冲、八边形图标必须二次确认文案必须说明后果不可用于 observational 域限流提示禁用致命红status.warning需注意、可恢复黄色静态、三角图标必须显示恢复时间必须提供操作步骤—status.info中性信息告知蓝色静态、信息图标可自动消失禁止附加操作说明—status.success操作成功确认绿色静态、对勾图标可自动消失禁止附加操作说明—action.destructive不可逆操作红色空心描边、危险图标必须二次确认必须说明不可恢复禁止使用普通主按钮样式action.primary场景主行动品牌色实心、箭头图标点击后跳转显示下一步预览—3.3 令牌如何展开为连续约束每个令牌在契约中展开为一组连续约束。以 status.critical 应用于致命错误ERR-001 · fatal 级别为例一个离散索引status.critical→ 展开为视觉方向红色脉冲 八边形图标 行为约束恢复路径、二次确认 文案约束必须说明后果 机器防线跨层禁止block。这就是码本解码的完整形态。码本解码演示status.critical → 展开为连续约束【演示环境码本解码演示区块】页面中码本解码演示区块包含离散索引status.critical、视觉方向红色脉冲 八边形图标、行为约束必须二次确认 恢复路径、文案约束必须说明后果、机器防线·跨层禁止observational/navigational/conversational 域下非法五栏展开。同一令牌编译为三种消费格式【演示环境三种消费格式并排】页面中同一令牌编译为三种消费格式区块三栏并排展示 Prompt 前缀 / JSON Schema / CI 规则。Prompt 前缀在生成致命错误界面时 - 必须使用红色脉冲视觉 - 必须包含八边形警告图标 - 必须提供恢复路径按钮 - 文案必须说明后果严重性 - 禁止在 observational 域使用JSON Schema{color_token:status.critical,motion_token:pulse.red.urgent,icon_token:alert.octagon,required_actions:[refresh,export],forbidden_domains:[observational]}CI 规则rules:critical-token-usage:token:status.criticalforbidden_in:[observational]required_visual:pulse.red.urgentviolation:block3.4 对比演示同一个红色在不同令牌下的不同含义【演示环境同一个红色对比卡片】页面中对比演示同一个红色在不同令牌下的不同含义区块左右两张卡片对比展示 status.critical系统故障与 action.destructive删除账户。status.criticalaction.destructive都是红色系统故障对话上下文可能丢失不可逆操作数据将永久删除覆盖层transactionaltransactional行为必须二次确认 恢复路径必须二次确认 输入验证样式红色脉冲 八边形红色空心描边非实心跨层observational 域非法—没有令牌时机器只看到 #EF4444有令牌时机器知道这是 status.critical 还是 action.destructive。【演示环境跨层禁止演示CI 阻断日志】页面中跨层禁止区块展示 CI 阻断日志“[CI 阻断] error-severity-cross-layer / Token: status.critical / Used in: observational domain / Expected: status.warning / Action: BLOCK”。3.5 五条思路的依赖关系第1条把意思变成编号离散编码 ↓ 第2条编号锁死一套视觉一对一映射 ↓ 第4条不同编号可以同颜色但不同意思区分场景 ↓ 第5条编号不能跨层乱用使用范围限制 ↓ 第3条编号自动翻译成三种格式一次定义多方消费四、架构层概念设计背景码本而非术语表。术语表供人查阅码本供机器解码每个令牌是离散索引编译管线查表后展开为连续约束视觉方向 行为约束 文案语气。这决定了令牌的读者不只是设计师更是编译管线与 AI 工具。令牌层与呈现层分离。color_token 是语义标识color 是实际色值同一个 status.critical 在不同设计系统里可映射到不同色值Tailwind #EF4444 / Ant Design #F5222D / DevUI #FF4D4F。语义令牌不关心具体色值只关心语义映射关系——设计系统更新时改映射表契约不变。语义覆盖层Semantic Overlay。组件库是底层Underlay只负责渲染——它提供圆角、色值、图标位这些空容器语义覆盖层在组件之上加盖业务语义把空容器翻译为业务语义组件。令牌是覆盖层加盖语义时使用的印泥。术语双轨。面向不同读者群时三层结构有两套叫法语义域 ≈ 覆盖层目录语义令牌 ≈ 语义重绑定场景映射 ≈ 约束注入。两套术语指向同一份注册表。五、这些坑怎么被解掉场景与角色对照回到开头那些真实反馈看令牌就位后它们各自怎么闭环。踩过的坑 1“这个红到底代表什么走查时谁也说不清”● 症状AI 生成限流提示时Before 形态下选 color-danger 无可指责——红色本身没错视觉走查也合规但用户看到红色以为账户出了问题实际只是需要等 30 秒。合规但错误。● 根因Token 只定义颜色没定义场景语义机器拿不到限流 ≠ 致命这条信息。● 关联机制①语义令牌与字典《Token 层差异》● 解法路径有了令牌后限流语义级别是 retryable黄色时钟 倒计时AI 若选 status.critical直接违反跨层规则CI 阻断PR 无法合入。错误在生成阶段就无法成立。● 验证方式前端与 AI 工程师的验收争议从感觉不对变成违反了哪条绑定——争议可引用、可定位、可裁决。踩过的坑 2“LLM 把 Critical 降级为’严重’代码里查不出来”● 症状AI 生成告警时把 “Critical” 替换为严重、把 “Data Loss Risk” 替换为请稍后重试——情绪权重被概率性输出随机降级Schema 校验通过语义却是错的。● 根因文案层没有术语锚定同义词自由替换没有任何机制判定违规。● 关联机制①语义令牌与字典B3 字典 synonym_firewall 同义词防火墙 6 个漂移模式证据库ALR-001● 解法路径YAML 定义禁止词并编译进 Prompt 前缀synonym_firewall 约束下关键术语替换即违规生成阶段被校验规则命中。● 验证方式设计师与产品经理精心设计的语义权重不再被概率性输出随机抹平——“Critical” 在所有产出中保持锚定替换即被校验规则命中。六、调整后工具界面层的呈现状态同一批工具在语义令牌就位之后工具 / 环节调整前调整后AI 生成工具只有色值限流与致命错误同红Prompt 前缀注入令牌约束后致命错误 红色脉冲 八边形图标 恢复路径限流提示 黄色时钟 倒计时.同模型同任务产出语义分级文案生成“Critical” 被随机替换为严重synonym_firewall 锚定关键术语替换即被校验规则命中验收环节走查结论停留在感觉不对Checklist 逐项核对语义分级 / 文案 / 红线违反红线即阻断结论注明契约版本号【推演条件】从演示环境进入生产环境语义令牌表需要以下组织条件谁来维护令牌建议由语义翻译设计师角色 4担任令牌管理员负责定义和更新语义令牌DesignOps角色 3负责版本发布与广播。令牌不是公共文档而是组织的语义宪法修改权限必须集中。变更如何不击穿下游令牌升级如新增 status.degraded 级别必须自动同步到所有消费面设计师的 Checklist、前端的 Prompt 前缀、CI 的拦截规则。组织需要建立字典变更 → 契约重编译 → 消费格式换版 → 角色通知的闭环避免上游改了下游还在用旧定义。谁来证明有效每次令牌升级后需通过语义分级器抽检一定数量的 AI 生成文案验证新规则确实拦截了目标错误。验证结果应沉淀到模式卡片中作为该模式置信度持续递增的证据。边界声明语义令牌表不解决视觉值的一致性那是 Design Token 层的职责不定义具体场景的约束实例那是YAML 契约的职责也约束不了有没有人查它消费纪律在角色侧见角色专题 ①设计师与产品经理。当前量化收益均为数据模型推演待生产数据验证。一句话总结给不同角色给设计师“你以前写’错误用红色’前端可能理解错。现在你写 status.critical机器查表就知道必须是红色脉冲 八边形 二次确认不会跑偏。”给前端“你不需要猜设计师的意思查 status.critical 的表就知道颜色、动画、图标、按钮样式全部锁死。”给 AI 工具开发者“你不需要自己判断用什么颜色输入场景编号查表输出 Prompt 前缀AI 按规矩生成。”给 DesignOps“你改一次编号定义Prompt 前缀、JSON Schema、CI 规则三处自动更新不用发三遍文档。”