AI 原生设计流水线

范式转变：设计的事实源搬家了

传统 SDLC 中，设计的事实源（single source of truth）是 Figma：设计师在画板上创作，开发通过「交付」把设计变成代码。AI 原生 SDLC 中，事实源上移到仓库里的文本规范——因为文本是 AI 的原生格式：可读、可 diff、可 lint、可版本化。

AI 原生设计环节的本质：把设计从「图片」变成「文本 + 工具链」——规范可执行、原型可生成、偏离可审计、流程可复现。

两种流向并非互斥，长期维护的产品会形成双向闭环：AI 产出 HTML → 导入 Figma 供人评审 → 人在画板上微调 → AI 经 MCP 读回改动 → 同步代码。而 DESIGN.md 在两种流向里都是最上游的锚。

阶段一 · 提炼设计规范（网站 → DESIGN.md）

设计规范采用 Google 的 DESIGN.md 格式（npm 包 @google/design.md）：一个双层 Markdown 文件，YAML front matter 存机器可读的 design tokens，正文存人类可读的设计理念。Tokens 给 AI 精确的值，prose 告诉它为什么。

1.1 抓取参考来源

从现有网站提炼时，抓取 HTML 与主样式表，分析颜色、字阶、圆角、间距与组件模式。目标站有反爬保护时的退路是 Wayback Machine：

# 查最近快照
curl "http://web.archive.org/cdx/search/cdx?url=example.com&output=json&limit=-3&filter=statuscode:200"
# 抓快照页面与 CSS
curl -L "http://web.archive.org/web/<时间戳>/http://example.com/"

1.2 编写 DESIGN.md

---
name: SGCC Portal · 国网绿央企门户
colors:
  primary: "#00796A"      # 全站唯一交互强调色
  accent:  "#F6AB00"      # 琥珀金，每屏至多一处
typography:
  body:
    fontFamily: Microsoft YaHei, sans-serif
    fontSize: 14px
components:
  button-page:
    backgroundColor: "{colors.primary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.sm}"
---

## Overview
央企门户美学：庄重、秩序、信息密集但不杂乱……

## Do's and Don'ts
- 不要渐变、投影、发光——庄重感来自"什么都没有"。

三条写作心法（来自 DESIGN.md 的哲学，实践中全部验证）：

• 一个具体引用胜过一串形容词。「央企门户、机关报式排版」比「简洁、现代、大气」信息量大得多——后者只会生成平庸的中间态。
• 负面约束是免费的。引用足够具体时，「不要渐变、不要大圆角」这类限制直接封死风格漂移，不必逐条罗列。
• 格式靠生长，不靠 spec。规范只规定最小结构，项目可自由扩展章节，linter 对未知内容宽容（保留，不报错）。

1.3 质量门：lint 必须 0/0

# 校验（0 errors / 0 warnings 才放行）
designmd lint DESIGN.md
# 版本对比（审计偏离、检测回归）
designmd diff DESIGN.md DESIGN-v2.md
# 导出 tokens 到代码（Tailwind v4 / DTCG）
designmd export --format css-tailwind DESIGN.md > theme.css

lint 内置 11 条规则，最实用的三条：broken-ref（token 引用悬空，error）、contrast-ratio（组件前景/背景低于 WCAG AA 4.5:1，warning）、orphaned-tokens（定义了却没被组件引用的颜色）。对比度检查与适老化设计天然同向——规范工具本身就是无障碍守门员。

阶段二 · HTML 高保真原型（DESIGN.md → 设计稿）

HTML 是 AI 的设计稿，原因有三：迭代速度（改 prompt → 刷新，几秒一轮）；保真度（真实排版引擎、真实字体渲染，高于画板）；可交互（hover、锚点、流程可直接体验）。设计评审在浏览器里完成，不在 Figma 里。

2.1 生成规则

• 单文件、零依赖：tokens 内联为 :root CSS 变量，整页自包含，随处可开。
• 内容对齐领域文档：文案、功能描述必须来自项目的领域文档（如 CONTEXT.md），AI 不杜撰产品行为。
• 规范忠实：颜色、字号、圆角、间距全部取自 tokens；组件模式（导航、卡片、页签、页脚）按规范组件实现。
• 项目偏离显式化：确需偏离（如适老化把正文从 14px 提到 16px），写入 DESIGN.overrides.md 并在 HTML 头部注释引用——见「设计治理」。

2.2 原型即评审物

把原型在浏览器打开即进入评审循环：看效果 → 口头反馈 → AI 修改 → 刷新。确认前不要进 Figma——HTML 阶段的修改成本是秒，Figma 阶段是分钟级且不可由 AI 代劳。

阶段三 · 导入 Figma（HTML → 协作层）

Figma 在 AI 原生流程中的角色是协作与存档：给人看、给人评论、留版本、做交付。先认清工具的能力边界：

3.1 操作步骤（人工完成）

1. AI 在原型目录起本地服务器：python3 -m http.server 8901 --bind 127.0.0.1；
2. Chrome 打开 http://127.0.0.1:8901/，点 html.to.design 扩展 → Capture this page；
3. Send to Figma → 桌面端唤起，配套插件自动落地为可编辑画板；
4. 把文件链接发回给 AI，进入对齐校验。

阶段四 · 对齐与实现（规范 ⇄ 设计稿 ⇄ 代码）

4.1 规范直达代码

export --format css-tailwind 产出的 @theme CSS 变量块，即使不用 Tailwind 也能直接贴进任何项目的 <style> 当 design tokens 用——规范与实现同源，不存在「设计稿和代码两个版本」。

4.2 设计稿回读校验

新会话中通过 Framelink MCP 的 get_figma_data 读取画板结构与样式，与 DESIGN.md tokens 比对，确认导入无损、实现无漂移。

4.3 变更与审计

规范或产出变更时跑 designmd diff 旧 新：token 级增删改一目了然，回归（错误/警告变多）时退出码为 1，可直接接 CI。diff 在这里不是「改完留痕」的工具，而是审计工具——确认项目偏离始终只有 overrides 里声明的那几条。

设计治理：标准只读，偏离显式

AI 会顺手改文件——治理规则必须前置。三层模型：

• 标准不被项目修改。DESIGN.md 是输入，不是草稿。
• 偏离必须带理由。例：「正文 14px → 16px——目标用户为 60–80 岁老花眼人群，适老化可读性优先」。
• 偏离可审计。定期用 diff 对照标准，确认没有隐性漂移。
• 回流有门槛。某条偏离在多个项目反复验证有效后，由标准维护者走评审回流入公司标准——项目侧不代劳。

工具链配置（一次性）

Figma token 管理

Personal access token 放入 shell 环境，绝不进 git：

# ~/.zshrc
export FIGMA_TOKEN="figd_xxxxxxxx"

Figma MCP 注册（Claude Code）

注册在用户级且 token 直接内嵌——GUI 启动的编辑器不读 ~/.zshrc，用 ${VAR} 引用会取到空值：

claude mcp add figma --scope user -- \
  npx -y figma-developer-mcp --figma-api-key figd_xxxxxxxx --stdio
# 验证
claude mcp list   # 期望输出：figma: ... ✔ Connected

DESIGN.md CLI

可用 npx @google/design.md，或克隆仓库后用 bun run cli <cmd> 本地调用（后者绕开包下载的权限拦截，也便于锁定版本）。

踩坑记录：每个坑只踩一次

以下全部来自一次真实实践。固化的意义就是把「试错」变成「照做」。

人工介入点：AI 与人的分界

把这张表写进流程文档后，AI 能自动跑到「需要人点扩展」那一步并把指引递过来——人机分工显式化，是流程可复现的前提。

落地检查清单

把设计环节嵌入 ticket 生命周期：界面类 ticket 标记 ready-for-agent 之前，逐项确认：

• 规范就绪 —— DESIGN.md 存在且 lint 0 errors / 0 warnings
• 原型就绪 —— HTML 原型通过评审，tokens 全部取自规范，内容与领域文档对齐
• 偏离显式 —— 所有项目级偏离已写入 DESIGN.overrides.md 并附理由
• Figma 存档 —— 画板已生成（扩展路径），链接记录在 ticket 中
• 实现同源 —— 代码使用的 tokens 来自 export 产物，非手抄色值
• 标准纯净 —— 公司标准文件本次零改动（git diff 为空）