设计系统文本化：用YAML/JSON统一管理设计令牌，实现多端一致与自动化

1. 项目概述当设计系统遇上纯文本最近在跟一个跨职能团队协作时我们遇到了一个典型的老大难问题设计师在Figma里更新了一个按钮的主色调前端工程师在代码库里改了对应的CSS变量但负责撰写产品文档和营销材料的同事直到上线前才发现自己用的色卡还是旧版本。这种信息不同步带来的返工和沟通成本让我开始思考有没有一种更“朴素”、更“本质”的方式来管理设计系统直到我发现了eshraw/design-system-as-text这个项目它提出了一个非常有意思的构想将整个设计系统用纯文本如YAML、JSON来定义和存储。这个想法初看可能有点反直觉。在大家的印象里设计系统总是和精美的UI工具如Figma、Sketch、复杂的组件库以及可视化文档站点绑定在一起。但design-system-as-text的核心思路是将这些视觉和交互规范剥离其华丽的“外衣”回归到最基础的数据结构描述。它认为设计系统的“单一可信来源”不应该是一个封闭的、专有的设计文件而应该是一份机器可读、人可编辑的文本文件。这就像把一座宏伟建筑的蓝图从精美的效果图册简化成一份标准化的工程图纸清单虽然少了些视觉冲击但确保了施工方、材料商、监理方拿到的数据是完全一致且无歧义的。这个项目非常适合那些追求开发与设计工作流深度集成、强调版本控制和自动化、或者需要跨多种平台和输出格式Web、移动端、打印物料、甚至命令行界面保持品牌一致性的团队。如果你厌倦了在设计工具和代码库之间手动同步的繁琐或者你的设计系统需要作为基础设施被其他程序化工具消费那么以文本为中心的设计系统管理思路或许能为你打开一扇新的大门。2. 核心思路为什么是“文本”2.1 从“视觉资产”到“结构化数据”的范式转变传统设计系统管理方式的核心是“视觉资产”。设计师在Figma中创建样式、组件和页面这些资产通过插件或手动导出转化为开发人员使用的代码如CSS、React组件。这个流程存在几个固有瓶颈单向与滞后变更往往从设计端发起开发端被动接收。即使有插件同步也常存在版本错位或需要手动触发更新的问题。格式壁垒Figma文件是专有二进制格式虽然提供了API但其数据模型与前端代码的数据模型并非天然同构。提取颜色、间距等Token设计令牌通常需要额外的解析和转换步骤。消费场景单一设计文件主要服务于视觉设计和前端开发。对于需要消费设计系统数据的其他角色或场景——比如生成品牌使用的PPT模板、确保数据分析看板的配色合规、或者为硬件产品界面生成资源——就需要额外的、定制化的导出流程。design-system-as-text的思路是将设计系统首先定义为“结构化数据”。一个颜色不是一个在画板上的色块而是一个具有特定标识符如color.primary.500和对应值如#007AFF的数据条目。一个间距单位不是一个参考线而是一个键值对如spacing.4: 16px。字体、边框、阴影等所有样式乃至组件的构成规则都可以用JSON、YAML这类通用的、层次化的数据格式来描述。这样做最根本的优势是实现了“单一可信来源”的平民化。文本文件可以被任何文本编辑器打开、修改可以被git进行完美的版本控制差异对比、分支管理、合并冲突解决可以被任何编程语言轻松读取和解析。设计系统从一个需要特定软件才能访问的“黑盒”变成了团队工作流中一个透明的、可编程的基石。2.2 文本化带来的核心优势解析将设计系统文本化并非为了取代Figma等设计工具而是为了在工具链中建立一个更稳固、更通用的数据层。其优势具体体现在以下几个方面版本控制与协作的天然契合Git成为了设计系统的版本管理工具。任何变更都通过Pull Request进行评审者可以清晰地看到diff了解是哪个Token的值被修改了还是新增了一个组件变量。这为设计变更引入了代码开发中成熟的协作、审查和回滚机制。多端/多平台输出的一致性保证文本定义是平台中立的。从这个单一的YAML/JSON文件出发你可以通过不同的“生成器”或“转换器”自动化地输出各种目标格式前端代码生成CSS或SCSS变量文件、JavaScript/TypeScript常量对象、Tailwind CSS配置扩展。设计工具通过脚本或插件将Token同步回Figma等工具更新样式库实现“代码驱动设计”的逆向同步。移动端生成Android的colors.xml、dimens.xmliOS的ColorAssets.xcassets和Style常量。文档与品牌物料生成样式指南静态网站、PDF手册甚至直接用于CI/CD中生成营销图片的模板参数。提升开发体验与自动化水平在开发阶段设计师修改了主色只需更新文本文件并提交。CI/CD流水线可以自动检测到设计系统文件的变更触发一系列任务生成新的前端样式文件、打包新的组件库NPM包、甚至自动部署更新后的样式指南文档站。开发人员只需更新依赖版本即可获取最新样式无需手动复制粘贴任何值。降低理解与贡献门槛对于开发者、产品经理、甚至内容策略师阅读一份结构清晰的YAML文件远比理解一个复杂的Figma文件结构要简单。这鼓励了跨职能团队对设计系统的共同维护和贡献而不仅仅是设计师的专属领域。注意文本化并非万能。它擅长管理“设计令牌”Design Tokens——即颜色、字体、间距等原始值以及它们组合成的语义化别名如color.background.primary。但对于复杂的、带有交互逻辑的UI组件如一个下拉菜单的展开/收起状态纯文本定义可能无法完整描述仍需与具体的组件实现代码库结合。design-system-as-text更多是解决“样式基础”和“设计变量”的统一管理问题。3. 实操构建从零开始定义一个文本化设计系统理解了“为什么”我们来看看“怎么做”。下面我将以一个虚拟的“Acme Corp”品牌为例演示如何从零开始构建一个文本化的设计系统。我们将使用YAML格式因为它对人类阅读和编辑更友好。3.1 项目结构与文件组织一个清晰的项目结构是成功的一半。建议采用如下目录布局acme-design-system/ ├── design-tokens/ # 核心设计令牌定义 │ ├── global.yaml # 全局基础值原始色值、字体栈等 │ ├── light-theme.yaml # 浅色主题语义化映射 │ └── dark-theme.yaml # 深色主题语义化映射 ├── components/ # 组件令牌定义可选进阶 │ └── button.yaml ├── builders/ # 代码生成器/转换脚本 │ ├── css.js │ ├── tailwind.js │ └── figma-sync.js ├── dist/ # 生成产物输出目录 │ ├── css/variables.css │ ├── tailwind/theme.js │ └── ios/Colors.swift └── package.json # 项目元数据和脚本3.2 设计令牌的定义从基础值到语义化设计令牌是设计系统的原子单位。我们分层定义第一层global.yaml- 定义原始值这个文件存放所有最基础的、无特定语义的原始值。可以把它想象成你的调色板、字体列表和间距尺度的原材料仓库。# design-tokens/global.yaml color: raw: blue: 50: #E6F7FF 100: #BAE7FF 200: #91D5FF 300: #69C0FF 400: #40A9FF 500: #1890FF # 品牌主色 600: #096DD9 700: #0050B3 800: #003A8C 900: #002766 gray: 50: #F5F5F5 # ... 其他灰度色阶 font: family: sans: [Inter, -apple-system, BlinkMacSystemFont, sans-serif] mono: [SF Mono, Menlo, monospace] size: spacing: base: 4 # 基准单位所有间距是其倍数 0: 0 1: 4px 2: 8px 3: 12px 4: 16px # ... 直到 12: 48px border: radius: sm: 2px md: 4px lg: 8px full: 9999px第二层light-theme.yaml- 定义语义化令牌浅色主题这一层将原始值映射到具体的用途上赋予其语义。这是连接设计与代码的关键抽象层。# design-tokens/light-theme.yaml # 导入基础值这里用YAML锚点和引用*示意实际中可能需要工具处理 imports: - ./global.yaml color: semantic: background: primary: *color.raw.blue.50 # 假设引用蓝色50 secondary: *color.raw.gray.50 inverse: *color.raw.gray.900 text: primary: *color.raw.gray.900 secondary: *color.raw.gray.600 on-inverse: white border: default: *color.raw.gray.300 interactive: primary: default: *color.raw.blue.500 hover: *color.raw.blue.600 active: *color.raw.blue.700 secondary: default: transparent hover: *color.raw.gray.100 active: *color.raw.gray.200 font: semantic: body: *font.family.sans heading: *font.family.sans code: *font.family.mono第三层dark-theme.yaml- 定义深色主题语义通过另一套映射关系轻松实现主题切换。# design-tokens/dark-theme.yaml imports: - ./global.yaml color: semantic: background: primary: *color.raw.gray.900 secondary: *color.raw.gray.800 inverse: *color.raw.gray.50 text: primary: *color.raw.gray.50 secondary: *color.raw.gray.300 on-inverse: *color.raw.gray.900 border: default: *color.raw.gray.700 interactive: primary: default: *color.raw.blue.400 # 深色主题下使用较浅的蓝色 hover: *color.raw.blue.300 active: *color.raw.blue.2003.3 编写生成器将令牌转化为可用代码定义了令牌数据下一步是将其转化为各端可用的代码。我们需要编写一些简单的脚本生成器。这里以生成CSS变量和Tailwind CSS配置为例。CSS生成器 (builders/css.js):const yaml require(js-yaml); const fs require(fs); const path require(path); function buildCSS(tokensPath, outputPath) { const tokens yaml.load(fs.readFileSync(tokensPath, utf8)); let cssContent :root {\n; function flatten(obj, prefix ) { for (const [key, value] of Object.entries(obj)) { const newPrefix prefix ? ${prefix}-${key} : --${key}; if (typeof value object value ! null !Array.isArray(value)) { flatten(value, newPrefix); } else { // 处理数组如字体栈 const cssValue Array.isArray(value) ? value.join(, ) : value; cssContent ${newPrefix}: ${cssValue};\n; } } } // 假设我们处理的是语义化颜色 flatten(tokens.color.semantic); flatten(tokens.font.semantic); // 也可以直接导出间距等基础值 // flatten(tokens.size.spacing); cssContent }; // 确保输出目录存在 const outputDir path.dirname(outputPath); if (!fs.existsSync(outputDir)) { fs.mkdirSync(outputDir, { recursive: true }); } fs.writeFileSync(outputPath, cssContent); console.log(CSS variables generated at: ${outputPath}); } // 分别生成浅色和深色主题的CSS buildCSS(./design-tokens/light-theme.yaml, ./dist/css/light-theme.css); buildCSS(./design-tokens/dark-theme.yaml, ./dist/css/dark-theme.css);Tailwind CSS 配置生成器 (builders/tailwind.js):const yaml require(js-yaml); const fs require(fs); function buildTailwindConfig(tokensPath, outputPath) { const tokens yaml.load(fs.readFileSync(tokensPath, utf8)); const config { theme: { extend: { colors: {}, spacing: {}, borderRadius: {}, fontFamily: {}, }, }, }; // 转换颜色 function mapColors(semanticObj, prefix ) { for (const [key, value] of Object.entries(semanticObj)) { const newKey prefix ? ${prefix}-${key} : key; if (typeof value object value ! null) { mapColors(value, newKey); } else { // 将路径如 background.primary 转换为嵌套对象 const keys newKey.split(-); let target config.theme.extend.colors; for (let i 0; i keys.length - 1; i) { if (!target[keys[i]]) target[keys[i]] {}; target target[keys[i]]; } target[keys[keys.length - 1]] value; } } } if (tokens.color?.semantic) { mapColors(tokens.color.semantic); } // 转换间距假设我们直接使用全局的spacing const globalTokens yaml.load(fs.readFileSync(./design-tokens/global.yaml, utf8)); if (globalTokens.size?.spacing) { config.theme.extend.spacing globalTokens.size.spacing; } // 转换字体 if (tokens.font?.semantic) { config.theme.extend.fontFamily tokens.font.semantic; } const configContent module.exports ${JSON.stringify(config, null, 2)}; fs.writeFileSync(outputPath, configContent); console.log(Tailwind config generated at: ${outputPath}); } buildTailwindConfig(./design-tokens/light-theme.yaml, ./dist/tailwind/theme-light.js);在package.json中配置脚本{ scripts: { build:css: node builders/css.js, build:tailwind: node builders/tailwind.js, build: npm run build:css npm run build:tailwind } }运行npm run build你将在dist/目录下得到可直接用于项目的CSS文件和Tailwind配置。4. 集成与工作流让文本化设计系统真正运转起来定义了令牌和生成器接下来是如何将其融入团队的实际工作流。关键在于建立自动化的同步机制和清晰的协作规则。4.1 与设计工具Figma的双向同步理想状态是设计师在Figma中调整样式能自动更新文本文件反之文本文件的修改也能反映到Figma库中。这需要借助Figma API。从Figma到文本同步设计变更你可以创建一个Node.js脚本定期或通过Webhook触发调用Figma API获取特定文件中的样式如颜色、文本样式数据与你本地的global.yaml文件进行比对和更新。核心步骤包括使用Figma个人访问令牌进行认证。调用GET /v1/files/:file_key端点获取文件数据。解析返回的JSON提取styles节点下的paint填充用于颜色和typeStyle文本样式等信息。将提取的颜色值、字体名称等与你global.yaml中的color.raw、font.family等结构进行匹配和更新。如果检测到变更自动提交一个包含YAML文件更改的Pull Request触发团队评审。从文本到Figma同步代码变更同样你可以编写脚本读取global.yaml中的color.raw部分通过Figma API的POST /v1/files/:file_key/styles端点创建或更新Figma文档中的颜色样式。这确保了在代码中定义的新品牌色能快速同步到设计侧。实操心得与Figma的初始同步可能比较繁琐需要仔细映射Figma的数据模型到你自定义的YAML结构。建议从最核心的颜色和字体开始逐步扩展。另外频繁的自动同步可能会干扰设计师的工作可以设置为在特定的“发布分支”合并时才触发同步到Figma主库的操作。4.2 与前端项目的集成在前端项目中你可以将设计系统作为一个独立的NPM包来管理或者直接作为项目子模块git submodule引入。作为NPM包发布在你的设计系统仓库中配置好package.json将dist/目录下的生成产物CSS变量文件、Tailwind配置、TypeScript定义文件等指定为要发布的内容。使用CI/CD如GitHub Actions在向主分支合并时自动运行npm run build然后发布新版本到私有或公共的NPM仓库。在前端项目中通过npm install acme/design-tokens来安装依赖。在项目的构建流程中直接引入包内的CSS文件或扩展Tailwind配置。作为Git子模块引入对于更紧密的耦合或内部项目可以将设计系统仓库作为子模块引入到前端项目根目录。git submodule add design-system-repo-url design-system在前端项目的构建脚本如Webpack、Vite配置中添加一个预处理步骤先进入design-system/目录运行npm run build然后将生成的CSS等文件复制或链接到项目源目录中。这样设计系统的任何提交在前端项目更新子模块引用后即可生效。4.3 建立团队协作规范文本化设计系统的成功一半靠技术一半靠流程。变更管理流程所有对设计令牌的修改必须通过Pull Request进行。PR描述应清晰说明变更原因如“根据品牌升级指南将主色从#1890FF调整为#0072E5”、影响范围哪些组件/页面会受影响以及是否需要同步Figma。评审机制PR至少需要一名设计师和一名前端工程师的批准。设计师负责审核视觉一致性工程师负责审核技术可行性和生成脚本的兼容性。版本语义化遵循语义化版本控制SemVer。例如修改一个原始色值color.raw.blue.500应视为一个破坏性变更Major版本升级因为所有引用它的语义化令牌都会变。而新增一个语义化令牌如color.semantic.background.tertiary则是向后兼容的新功能Minor版本升级。文档即代码在项目根目录维护一个CHANGELOG.md记录每个版本的变更。同时可以编写一个简单的脚本基于YAML令牌文件自动生成一个静态的样式指南网站使用VuePress、Docusaurus等工具并随每次发布自动部署。5. 进阶应用与常见问题排查5.1 组件令牌与复合令牌基础的设计令牌管理颜色、字体等原始属性。但实际开发中我们经常以组件为单位进行思考。你可以进一步定义“组件令牌”它是对基础令牌的组合引用。例如在components/button.yaml中button: primary: background: *color.semantic.interactive.primary.default background-hover: *color.semantic.interactive.primary.hover text-color: white border-radius: *size.border.radius.md padding: [*size.spacing.2, *size.spacing.4] # 水平和垂直间距 secondary: background: *color.semantic.interactive.secondary.default background-hover: *color.semantic.interactive.secondary.hover text-color: *color.semantic.text.primary border: 1px solid *color.semantic.border.default border-radius: *size.border.radius.md padding: [*size.spacing.2, *size.spacing.4]然后你的生成器可以读取这些组件令牌生成更高级别的CSS类或React组件的Props类型定义实现从设计令牌到UI组件的直接桥梁。5.2 多主题与模式切换我们之前已经定义了light-theme.yaml和dark-theme.yaml。在前端实现主题切换时核心思路是生成两套CSS变量文件分别对应浅色和深色主题的所有语义化令牌。在HTML根元素如html或body上通过一个类名如.theme-dark或属性如>/* light-theme.css */ :root { --color-background-primary: #F5F5F5; --color-text-primary: #262626; } /* dark-theme.css */ :root.theme-dark { --color-background-primary: #262626; --color-text-primary: #F5F5F5; }5.3 常见问题与排查技巧在实际落地过程中你可能会遇到以下典型问题问题1YAML文件引用和合并复杂难以管理。排查当令牌数量庞大、层级嵌套深时手动使用YAML锚点和引用*会变得混乱且容易出错。解决引入专门的设计令牌管理工具作为“编译层”如 Amazon Style Dictionary 或 Token Transformer 。这些工具允许你使用更清晰的JSON结构定义令牌并通过“引用”语法如{color.raw.blue.500}来链接值它们会负责解析依赖、合并文件并输出到各种目标平台。你可以将YAML作为源文件或者直接使用这些工具支持的JSON格式。问题2生成器脚本维护成本高每增加一个输出目标如Flutter、React Native就要写一个新脚本。排查自定义脚本缺乏抽象和复用处理不同数据结构时容易产生冗余代码。解决采用或借鉴成熟工具。例如Style Dictionary本身就内置了数十种平台格式CSS、iOS、Android等的“格式化器”你只需要配置输入和输出无需编写大量生成代码。如果你的需求非常定制化也可以基于这些工具提供的插件体系来开发而不是从零开始。问题3设计师不习惯直接编辑YAML/JSON文件。排查文本编辑器对视觉工作者不友好容易产生语法错误且无法实时预览效果。解决不要强求设计师直接修改文本文件。维持现有的工作流设计师在Figma中工作。通过前面提到的“Figma到文本”同步流程将Figma作为设计师友好的“编辑界面”。关键是要确保同步脚本的稳定性和准确性让设计师信任“在Figma里改就等于改了设计系统的源代码”。问题4如何测试设计令牌变更的影响排查直接修改一个基础色值可能引发连锁反应肉眼难以全面评估。解决建立可视化测试流程。在CI/CD中当设计令牌文件变更时可以自动运行一个“视觉快照”测试。这个测试会使用新旧两套令牌分别渲染一组核心组件按钮、输入框、卡片等的示例并生成图片进行差异对比。任何意外的视觉变化都会在合并前被标记出来供团队审查。可以使用像 Chromatic 或 Loki 这类工具来实现。问题5文本文件中的值单位不统一px, rem, hex, rgba导致生成代码时出错。排查在global.yaml中有的值写了16px有的只写了16颜色值有时是#1890FF有时是rgb(24, 144, 255)。解决制定并严格执行令牌值格式规范。例如颜色一律使用十六进制hex格式含透明度时使用8位hex#1890FFE6。间距、尺寸等如果基础单位是px则在global.yaml中明确写出单位如16px。在生成CSS时可以按需将其转换为rem如1rem。可以考虑在YAML中使用自定义标签或注释来标记类型或者使用支持类型校验的格式如JSON Schema来定义令牌结构并在CI中引入校验步骤。将设计系统文本化是一个将设计基础设施工程化的过程。它初期会带来一些学习和迁移成本但一旦这套以数据为中心、以自动化为驱动的流程运转起来它将极大地提升团队效率、减少不一致性并为产品体验的规模化迭代奠定坚实可靠的基础。这不仅仅是换了一种文件格式更是换了一种关于如何协同创造数字产品的思维方式。