> Schema-As-Code 不是替代任何工具，是所有 AI 工具的上游约束。 
阶段二的核心：把设计意图翻译成机器可读的语义规则。
>
> 阶段一：[组件语义快照与模式诊断：AI 生成界面的第一道检查](https://juejin.cn/post/7654878320695607348)
>
> 方法论总纲与开源仓库：[把设计规范写成代码格式，是所有 AI 工具的上游约束方法论](https://juejin.cn/post/7656841584969351202)

---

## 摘要
阶段一通过语义快照诊断，发现了AI生成界面中的系统性语义断层：同一组件在不同场景下被混用同一套视觉规则，导致用户认知混乱。诊断报告指明了"缺什么规则"，但发现规则缺失不等于解决问题。阶段二的核心任务是将设计意图转化为机器可读的语义契约——不是让设计师写代码，而是建立一套"语义翻译层"，让AI在生成内容前就知道什么不能说、什么不能做，从源头锁住语义漂移。

---

## 一、问题：为什么设计规范总是"传不到位"？
2024-2025 年，设计团队全面进入 AI 辅助生产时代。但一个老问题始终没解决：

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

我经历过这样的场景：

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

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

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

---

## 二、核心方案：把设计规范写成代码格式
我的解法是 Schema-As-Code——**把设计意图翻译成 YAML 格式的语义规则**，让机器能读、能校验、能自动同步。

### 2.1 翻译的本质
设计师的核心能力不是"画界面"，而是"理解场景语义"：

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

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

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

### 2.2 翻译前后的对比
| 维度 | 传统规范文档（Before） | YAML 语义契约（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）


![](https://developer.qcloudimg.com/http-save/yehe-12505371/18575191c2d56f3ed7daef6d061a43d8.png)

**语义令牌是 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 域（确认弹窗）→ 用户主动点，必须给反馈


![](https://developer.qcloudimg.com/http-save/yehe-12505371/9215df8517dbf7a20e115cfee2163ed6.png)

### 3.4 不可变边界（Immutable Boundaries）
定义"绝对不能做什么"的红线：

```yaml
immutable_boundaries:
 - boundary_type: "safety"
 rule: "禁止直接执行删除操作而不显示二次确认"
 violation_action: "block"
 - boundary_type: "compliance"
 rule: "禁止在提示场景使用 status.critical"
 violation_action: "warn"
```


![](https://developer.qcloudimg.com/http-save/yehe-12505371/a8f7a41442540eb0ede9365f0a5bb815.png)

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

### 3.5 语义规范 vs Design Token：关键区别
| 维度 | Design Token | 语义规范（Schema-As-Code） |
| --- | --- | --- |
| **问题** | 颜色是什么？ | 颜色代表什么？ |
| **示例** | `color: #EF4444` | `color_token: status.critical` |
| **稳定性** | 随设计系统更新而变 | 随语义场景定义而稳定 |
| **读者** | 前端工程师 | AI / 机器 / 前端 |
| **消费方式** | 代码中引用变量 | 编译为 Prompt / Checklist / CI 规则 |



![](https://developer.qcloudimg.com/http-save/yehe-12505371/ce7641d94e77784c6d6d8ba360ffc726.png)

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

---

## 四、YAML 契约格式：怎么写语义规则
理解了语义规范体系后，来看 YAML 契约的具体格式。

### 4.1 基础结构
```yaml
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"
```


![](https://developer.qcloudimg.com/http-save/yehe-12505371/a47c55607fdd6cc32bad1ebb54f30f69.png)

### 4.2 关键字段说明
| 字段 | 说明 | 示例 |
| --- | --- | --- |
| `intent_id` | 规则唯一标识 | `ERR-001` |
| `semantic_tokens` | 语义令牌定义 | `error_severity.fatal` |
| `visual_mapping` | 视觉语义映射 | `color_token: status.critical` |
| `user_action` | 用户行动匹配 | `刷新页面`, `导出历史` |
| `llm_constraints` | LLM 生成约束 | "必须明确告知后果" |
| `immutable_boundaries` | 不可突破边界 | 违反时阻断 |


### 4.3 与阶段一的衔接
阶段一诊断出："该组件缺少 `error_severity` 语义令牌，违反 ERR-001 模式。"

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


![](https://developer.qcloudimg.com/http-save/yehe-12505371/648b65650c4ccd166291d3ebd2411a1c.png)

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

---

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

![](https://developer.qcloudimg.com/http-save/yehe-12505371/4038d27d730896f5a01d3d8238d80a85.png)

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

### 5.1 编译为 Prompt 前缀（给 AI 编程工具）
```markdown
在生成错误状态界面时，必须遵守以下语义分级：
- Fatal（系统级故障）：红色脉冲 + 八边形警告 + 必须提供恢复路径
- Transient（网络抖动）：灰色加载 + 旋转图标 + 禁止红色背景
- Retryable（限流）：黄色提示 + 时钟图标 + 必须显示倒计时
- Degraded（部分可用）：蓝色提示 + 信息图标 + 必须说明可用功能

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

### 5.2 编译为 Checklist（给设计师走查）
```markdown
错误状态走查清单：
- [ ] 是否区分了 Fatal/Transient/Retryable/Degraded 四级？
- [ ] 每级是否有不同的颜色（红/灰/黄/蓝）？
- [ ] 每级是否有明确的用户行动指引？
- [ ] Fatal 是否有恢复路径（刷新/导出）？
- [ ] Retryable 是否有倒计时或升级入口？
- [ ] 是否引用了意图契约 ERR-001？
```

### 5.3 编译为 JSON Schema（给结构校验）
```json
{
 "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 规则（给自动化流水线）
```javascript
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 }
```


![](https://developer.qcloudimg.com/http-save/yehe-12505371/ecf3fe64aedfe34c296db7551c41211d.png)

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

---

## 六、契约库：让设计规范像代码一样管理
### 6.1 目录结构
```plain
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 版本管理
```yaml
# 版本 1.0.0 → 1.1.0 的变更
version: "1.1.0"
changes:
 - "增加 degraded 级别（部分功能可用）"
 - "优化同义词防火墙匹配逻辑"
 - "修复 retryable 倒计时字段缺失问题"
```

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

---

## 七、设计师的新角色：语义翻译者
### 7.1 为什么设计师不需要会写代码
YAML 契约不是代码，是**设计意图的翻译层**。

```yaml
# 设计师写的：语义约束
destructive_action:
 description: "不可逆的数据销毁操作"
 visual_mapping:
 color_token: "status.critical"
 button_style: "outline_danger"
 llm_constraints:
 - "必须包含二次确认弹窗"
 - "文案必须明确说明'此操作不可恢复'"
```

这段 YAML 里：

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

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


![](https://developer.qcloudimg.com/http-save/yehe-12505371/ae4aec9b6338cc39acd39bcdbf0a0625.png)

前端工程师拿到这份 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：定义语义令牌（写 YAML）
```yaml
intent_id: "ERR-001"
semantic_tokens:
 error_severity:
 fatal:
 visual_mapping:
 color_token: "status.critical"
 user_action:
 - label: "刷新页面"
```

### 步骤 3：编译并验证
```bash
# 编译为 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://github.com/2436041978-ops/semantic-pipeline)
+ **在线体验**：[https://2436041978-ops.github.io/semantic-pipeline/](https://2436041978-ops.github.io/semantic-pipeline/)
+ **完整文档**：语雀 Schema-As-Code 知识库

---

![640.png](https://developer.qcloudimg.com/http-save/yehe-12505371/33f4f97d7fdb6167a8d2b4ebe419603d.png)

Schema-As-Code 不是替代任何工具，是所有 AI 工具的上游约束。  阶段二的核心：把设计意图翻译成机器可读的语义规则。

设计师作为"语义翻译者" 当AI生成界面时怎么用规则锁住设计意图

阶段二聚焦设计师作为“语义翻译者”，通过 Schema-As-Code 将设计意图转化为 YAML 语义契约——定义语义令牌、域与不可变边界，实现对 AI 生成的上游约束，从源头锁住语义漂移，让规范可读、可编、可验。

人工智能

开发工具

Schema-As-Code将设计规范转化为机器可读的YAML语义规则，实现AI生成界面的精准约束。通过语义令牌定义组件在不同场景下的行为规范，建立不可变边界防止语义漂移，并自动编译为Prompt、Checklist等格式，确保设计意图零失真传递。

代码解释

防火墙

DeepSeek

ChatGPT

GitHub

React

JSON

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

设计师作为"语义翻译者" 当AI生成界面时怎么用规则锁住设计意图-腾讯云开发者社区-腾讯云

设计师作为"语义翻译者" 当AI生成界面时怎么用规则锁住设计意图

设计师作为"语义翻译者" 当AI生成界面时怎么用规则锁住设计意图

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐