Schema-As-Code 不是替代任何工具是所有 AI 工具的上游约束。阶段二的核心把设计意图翻译成机器可读的语义规则。快速阅读阶段一组件语义快照与模式诊断AI 生成界面的第一道检查方法论总纲与开源仓库把设计规范写成代码格式是所有 AI 工具的上游约束方法论摘要阶段一通过语义快照诊断发现了AI生成界面中的系统性语义断层同一组件在不同场景下被混用同一套视觉规则导致用户认知混乱。诊断报告指明了缺什么规则但发现规则缺失不等于解决问题。阶段二的核心任务是将设计意图转化为机器可读的语义契约——不是让设计师写代码而是建立一套语义翻译层让AI在生成内容前就知道什么不能说、什么不能做从源头锁住语义漂移。一、问题为什么设计规范总是传不到位2024-2025 年设计团队全面进入 AI 辅助生产时代。但一个老问题始终没解决设计规范更新了前端没同步AI 更没看还是按老样子生成。我经历过这样的场景设计师把错误状态分四级的规范更新了发在语雀文档里 全员通知2 周后走查发现 3 个产品的 AI 生成界面还是全红问前端“规范更新了你知道吗” 答“啊我没看到那条消息。”问 AI“你知道错误状态要分四级吗” AI“我的训练数据里没有这条。”问题根因设计规范写在文档里是给人看的不是给机器读的。人可能看漏、看错、看过时版本。机器根本看不到。二、核心方案把设计规范写成代码格式我的解法是 Schema-As-Code——把设计意图翻译成 YAML 格式的语义规则让机器能读、能校验、能自动同步。2.1 翻译的本质设计师的核心能力不是画界面而是理解场景语义这个按钮是删除账户不可逆必须让用户知道后果这个错误是系统级故障对话可能丢了必须给恢复路径这个提示是限流等一等就好不需要恐慌以前这些意图写在文档里靠人传人的方式传递层层失真。现在我把这些意图写成 YAML 契约机器直接读取零失真传递。2.2 翻译前后的对比维度传统规范文档BeforeYAML 语义契约After载体Word / 语雀 / Figma 文件YAML 文件放 Git 仓库读者人可能看漏人 机器自动读取同步方式全员 / 开会 / 口头强调Git Diff 自动触发版本管理文档 v1.0, v2.0容易混淆Git 版本号精确可追溯消费方式前端凭经验实现自动编译为 Prompt / Checklist / CI 规则走查覆盖人眼 20%500 页面看不过来机器 100%自动校验关键变化设计意图从人传人的方言变成机器可读的普通话。三、语义规范体系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 语义令牌命名空间命名空间用途示例status.*状态级别status.critical致命、status.warning警告、status.info提示、status.success成功phase.*认知阶段phase.research检索、phase.analysis综合、phase.check验证、phase.output生成boundary.*边界强度boundary.soft软性拒绝、boundary.hard强制终止、boundary.review升级审核action.*操作性质action.destructive不可逆、action.constructive建设性、action.neutral中性命名空间的价值让语义有标准字典不凭感觉。以前设计师说用红色前端可能理解为#EF4444、“#FF0000或”#FF4D4F。现在设计师说用 status.critical所有人都知道这是致命状态的标准红色色值由设计系统映射表定义。3.3 语义域Semantic Domain语义域定义用户与系统的交互关系类型语义域定义典型组件约束特征observational用户被动接收信息错误提示、状态通知、告警卡片禁止要求用户输入必须提供退出路径transactional用户主动触发操作按钮、表单、确认弹窗必须提供反馈必须支持撤销conversational对话式交互聊天界面、问答流程必须保持上下文必须明确边界语义域的价值同一个组件在不同域下约束不同。例如 Alert 组件在 observational 域错误提示→ 用户被动看不能要求输入在 transactional 域确认弹窗→ 用户主动点必须给反馈3.4 不可变边界Immutable Boundaries定义绝对不能做什么的红线immutable_boundaries:-boundary_type:safetyrule:禁止直接执行删除操作而不显示二次确认violation_action:block-boundary_type:compliancerule:禁止在提示场景使用 status.criticalviolation_action:warn不可变边界的价值给 AI 画红线不是建议是禁止。3.5 语义规范 vs Design Token关键区别维度Design Token语义规范Schema-As-Code问题颜色是什么颜色代表什么示例color: #EF4444color_token: status.critical稳定性随设计系统更新而变随语义场景定义而稳定读者前端工程师AI / 机器 / 前端消费方式代码中引用变量编译为 Prompt / Checklist / CI 规则关系Design Token 是底层词汇语义规范是上层语法。四、YAML 契约格式怎么写语义规则理解了语义规范体系后来看 YAML 契约的具体格式。4.1 基础结构intent_id:ERR-001# 规则唯一标识description:错误状态后果差异未分级# 规则描述version:1.0.0# 语义版本号applicable_products:# 适用产品范围-ChatGPT-文心一言-通义千问-Kimi-豆包-DeepSeeksemantic_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:-禁止红色背景避免情绪过载-必须显示自动重试进度retryable:description:请求频率已达上限visual_mapping:color_token:status.warning# 语义令牌警告状态motion_token:noneicon_token:clock# 语义令牌时钟图标user_action:-label:等待倒计时action:wait_countdowncountdown_field:retry_after-label:升级套餐action:upgradellm_constraints:-必须显示剩余等待时间秒/分钟-必须提供升级/扩容路径degraded:description:部分功能可用可继续生成visual_mapping:color_token:status.info# 语义令牌信息状态motion_token:noneicon_token:info.circle# 语义令牌信息图标user_action:-label:继续生成action:continue-label:简化问题重试action:retry_simplifiedllm_constraints:-必须说明哪些功能仍然可用-禁止显示纯技术错误码如 500 Internal Errorimmutable_boundaries:# 不可变边界不能做什么-boundary_type:safetyconstraint_rule_ref:rules/error-severity.yamlviolation_action:block4.2 关键字段说明字段说明示例intent_id规则唯一标识ERR-001semantic_tokens语义令牌定义error_severity.fatalvisual_mapping视觉语义映射color_token: status.criticaluser_action用户行动匹配刷新页面,导出历史llm_constraintsLLM 生成约束“必须明确告知后果”immutable_boundaries不可突破边界违反时阻断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-0015.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.0changes:-增加 degraded 级别部分功能可用-优化同义词防火墙匹配逻辑-修复 retryable 倒计时字段缺失问题Git Diff 自动触发影响面分析当err-001.yaml变更时自动通知所有消费该契约的 AI 工具重编译。七、设计师的新角色语义翻译者7.1 为什么设计师不需要会写代码YAML 契约不是代码是设计意图的翻译层。# 设计师写的语义约束destructive_action:description:不可逆的数据销毁操作visual_mapping:color_token:status.criticalbutton_style:outline_dangerllm_constraints:-必须包含二次确认弹窗-文案必须明确说明此操作不可恢复这段 YAML 里没有 CSS 类名没有 React/Vue 组件名没有文件路径只有设计师的意图“删除按钮必须是红色空心必须有二次确认。”前端工程师拿到这份 YAML可以翻译成 Tailwind、Material UI、DevUI 或任何框架。契约是跨框架的。7.2 组织经济价值环节传统工作流Schema-As-Code 工作流规范定义设计师写文档设计师写 YAML意图直接机器可读规范同步DesignOps 全员 2 周Git Diff 自动触发 0.5 天规范执行前端凭经验实现AI 自动读取 Prompt 前缀规范走查人眼 20% 覆盖机器 100% 自动校验规范修复上线后用户投诉生成前系统拦截总收益设计意图从人传人的方言变成机器可读的普通话。八、快速开始三步写第一份契约步骤 1诊断语义缺失从阶段一导入诊断报告“ChatGPT 错误状态缺少error_severity语义令牌违反 ERR-001 模式。”步骤 2定义语义令牌写 YAMLintent_id:ERR-001semantic_tokens:error_severity:fatal:visual_mapping:color_token:status.criticaluser_action:-label:刷新页面步骤 3编译并验证# 编译为 4 种格式schema-compiler compile intent/err-001.yaml--outputcompiled/# 验证输出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 知识库