Design systems guide · 更新 2026-06-28

Design Token Export Checklist：Figma、Penpot、Sketch、DESIGN.md、JSON Tokens、命名、Modes、Assets 与 Code Handoff

把 design-system decisions 转成可 review 的 code artifacts，同时不丢失 names、modes、aliases、semantic intent、accessibility constraints 和 developer ownership 的实用清单。

Design tokens 出问题，往往是因为团队把 export 当成按钮，而不是 contract。Token pipeline 必须在设计工具和代码仓库之间保留 naming、modes、aliases、source ownership、accessibility intent、platform transforms 和 rollback rules。

这份 checklist 把 Penpot、Figma、Sketch、DESIGN.md 和 Excalidraw-style ideation 连成一个采用流程：先决定什么算 token，再把 raw values 映射成 semantic names，导出到可 review JSON shape，转换成 platform outputs，并让 designer 和 engineer 都能审计每次 handoff。

RepoDaily 判断

不要先问哪个设计工具 export format 最多。先定义你的 codebase 能 review 的 token contract：source、name、type、mode、alias、fallback、accessibility note、owner 和 consuming package。好的 export pipeline 会让 design decisions 变成容易 diff、可安全发布的代码变更。

RepoDaily fixture evidence：本地 token-to-code 回归测试

这不是 Figma、Penpot、Sketch、Style Dictionary 或任何 design-token vendor 的评测。RepoDaily 做了一个小型本地 JSON token contract，用来检查 token export workflow 是否能生成可 review 的 CSS/TypeScript outputs，保留 aliases 和 modes，让 asset metadata 可见，暴露 rename / dark-mode diffs，并能从原始 contract 复现 baseline outputs 用于 rollback。

证据项	Fixture 结果	为什么重要	局限性
本地 token regression fixture	7/7 个本地 token-to-code checks 通过。	验证的是 checklist 机制，不是 vendor 或 design-tool 排名。	小型本地 JSON fixture；没有连接真实 design-tool account。
Generated code outputs	一个 token contract 同时生成 `tokens.css` 和 `tokens.ts`。	Design decisions 变成可 review code artifacts，而不是一次性 copy-paste values。	只生成 CSS 和 TypeScript outputs。
Alias 和 mode 保留	action-primary token 保留 raw color alias，light/dark surface modes 生成分离 outputs。	Aliases 和 modes 是很多 token pipeline 丢失意图的地方。	Fixture 使用简单 resolver，不是完整 design-token build system。
Rename 和 mode diffs	Rename `action.primary` 与修改 dark surface value 都会产生明确可 review diff。	团队应该在 tokens 进入 production code 前看到哪些内容会坏。	Diff artifacts 代替 visual regression screenshots。
Asset metadata 与 rollback	Fixture 保留 icon path/license/owner metadata，并能从 original contract 复现 baseline output。	Tokens 和 assets 需要 ownership 与 rollback，而不只是 generated variables。	没有运行完整 component renderer 或 browser screenshot test。

这节应理解为 RepoDaily 对 token export checklist 的自测，不是任何设计工具的 benchmark。
这个测试支持页面建议：export 应被当作包含 names、aliases、modes、assets、diffs 和 rollback 的可 review contract。
这个证据刻意保持小型，因此它证明的是 checklist sanity，不是完整 design-system migration readiness。

快速矩阵

Export surface	要保留什么	好信号	失败信号
Raw values	Colors、typography、spacing、radius、shadows、opacity、motion	每个 value 都有 type、source、owner 和 intended use	匿名 hex codes 或 pixel numbers 被复制到代码里
Semantic tokens	background/default、text/subtle、action/primary 等 role names	Components 使用 semantic names，而不是 raw palette slots	开发者直接在产品代码里 import blue-500
Modes and themes	Light/dark、brand、density、platform、locale 或 high-contrast variants	Mode changes 明确且可测试	Dark mode 是另一个 spreadsheet 或 manual override
Aliases and references	Token-to-token links 和 fallback chains	Aliases 在 export 后仍可 deterministic resolve	Aliases 被 flatten 且没有 review history
Assets	Icons、logos、illustrations、fonts、image exports	Assets 有 version、license、size 和 platform output rules	Screenshots 或 SVGs 被手动复制到 apps
Code outputs	CSS variables、TS constants、Swift、Android XML、Tailwind config、docs	Generated outputs 从同一个 source file review	Design 和 code pipeline 生成不同 names
Governance	Owners、review gates、changelog、deprecation、rollback	Token changes 像 code changes 一样管理	Designer 可以静默 rename 一个会破坏 production 的 token

Design token export 准备度评分卡

导出完整 library 前，先给一个 design-system slice 打分。

控制项	0 分	1 分	2 分	Owner 问题
Token inventory	文件里的 values 未知	部分 naming list	Typed token inventory 有 source 和 owner	哪些 value 是 tokens，哪些只是 local overrides？
Naming policy	Names 只跟视觉外观走	有一些 semantic names	Raw、semantic、component、mode names 分离	Code 不知道设计工具也能消费 names 吗？
Mode handling	Light/dark 手动处理	有 modes 但未测试	Mode matrix 可 export 且可 diff	Mode rename 时什么会坏？
Transform rules	Manual copy-paste	一个 generated output	CSS、JS/TS、mobile、docs transforms 明确	哪些 generated files 是 source of truth？
Review workflow	Token changes 无 review	Designer-only review	Design 和 engineering review 同一个 diff	谁批准 breaking token change？
Rollback	没有 rollback path	只能 revert code	Source tokens 和 generated outputs 可一起 revert	今天如何撤回坏 token export？

30 分钟 design token export 测试计划

在承诺某个工具专属 export workflow 前使用。

0–5 分钟：选择 slice

选择一个 component family，并列出 colors、typography、spacing、radius、icon 和 mode 需求。

成功标准测试范围小到可以人工 review。

5–10 分钟：export source tokens

把这个 slice export 或手动 normalize 成 JSON-like token contract，包含 name、type、value、mode、alias 和 source。

成功标准Designer 和 engineer 能读同一个文件。

10–16 分钟：生成一个 code target

创建 CSS variables、TS constants 或一个 code output，并接入一个 demo component。

成功标准Component 从 generated tokens 渲染，而不是复制值。

16–22 分钟：改一个 semantic token

Rename 或 update 一个 semantic token，检查 diff、generated files 和视觉结果。

成功标准变化可理解且可撤回。

22–30 分钟：review failure modes

检查 alias loss、mode mismatch、asset handling、accessibility notes、changelog 和 rollback path。

成功标准团队知道应该 scale、restrict 还是重设计 pipeline。

Token export 决策流程

先选一个真实 component family，例如 buttons、alerts 或 navigation，不要一开始 export 整个 design system。
列出这个 slice 的 raw values、semantic roles、component-level names、modes、assets 和 consuming code packages。
选择 source of truth：design tool、token repository、DESIGN.md-style spec，或带明确 ownership boundaries 的 hybrid。
导出成可 review 的 JSON shape，并保留 original names、aliases、modes、comments 和 source references。
先转换一个 code target，例如 CSS variables 或 TypeScript constants，并比较 component 前后渲染结果。
扩展到多平台前，补上 changelog、deprecation、rollback、accessibility review 和 ownership rules。

场景表

场景	最小清单	停止条件
Figma library 到 web app	把 variables/styles 映射成 semantic JSON，并从一个 reviewed source 生成 CSS 或 TS	Token names 在 export 中变化，或 aliases 被静默 flatten
Penpot self-hosted design system	用一个 component slice 测 ownership、backups、export fidelity、SVG/assets 和 developer handoff	Self-hosting 让 design data 可用，但 token review 仍然靠手工
Sketch Mac workflow 到多平台代码	Export symbols/styles、映射 names，并测试 generated web/mobile outputs	Mac-only source 给非 Mac 团队制造未 review 的人工翻译
DESIGN.md 给 coding agents 使用	把 token rules 写成 machine-readable constraints，并对照 token source 检查 agent output	Agents 使用 stale brand rules 或 raw values 且不引用 spec
Excalidraw-to-design-system handoff	把 sketches 当作 intent；最终 decisions 后续再转成 typed tokens	Sketch file 被当成 production token authority
Multi-brand 或 dark-mode rollout	要求 mode matrix、fallback rules、visual regression 和 owner signoff	Dark mode 作为单独 hand-tuned stylesheet 发布

Design token export 风险清单

Name drift

设计工具里的视觉名称会变成代码里的 semantic API。Export 前必须有 rename policy。

Alias loss

Flattened values 会隐藏 token 为什么引用另一个 token，让未来 theme changes 变危险。

Mode ambiguity

Light、dark、brand、density、platform modes 需要 matrix；否则团队会发布 manual overrides。

Asset mismatch

Icons 和 fonts 也是 design system 的一部分，但 token exports 常忽略 license、size 和 platform constraints。

Stale agent spec

AI-readable design rules 只有在像代码一样 versioned 和 reviewed 时，才真的帮助 coding agents。

No rollback

Generated outputs 如果没有 source-token rollback path，坏设计决策会很难撤回。

实施模式

Token contract file

维护一个小型 canonical JSON 文件，包含 name、type、value、mode、alias、source、owner 和 deprecation fields。

Design-to-code pull request

把 source token changes 和 generated code outputs 放在同一个 PR review，并附上 visual examples。

Semantic-first naming

内部保留 raw palette names，但暴露给 product code 的是 semantic roles。

Mode matrix snapshot

生成代码前，明确 export light、dark、high-contrast、brand 和 density modes matrix。

Agent-readable summary

把 token contract 镜像到 DESIGN.md-style instructions，让 coding agents 知道哪些 names 允许使用。

Deprecation lane

没有 replacement、changelog 和 release window，不要删除或 rename widely used tokens。

常见问题

给尝试把 tokens 从设计工具移动到代码的团队提供简短答案。

设计工具应该是 source of truth 吗？

只有当工程师可以 review exported contract、generated code、changelog 和 rollback path 时才适合。否则用 token repository 作为可 review source。

Design tokens 只是颜色吗？

不是。成熟 token systems 包括 typography、spacing、radius、shadows、opacity、motion、assets、modes、aliases 和 semantic roles。

DESIGN.md 放在哪里？

它可以给 coding agents 总结 token rules，但应该镜像 canonical token source，而不是变成未 review 的第二套 source of truth。

最小有用 pilot 是什么？

一个 component family，带 light/dark modes、一个 generated code target、一个 visual comparison 和一次 rollback test。

来源

Feedback

这页是否帮助你做出决定？

匿名反馈只用于判断内容是否真正有用。

报告过期或缺失的证据