1. 项目概述从设计稿到结构化文档的自动化桥梁在团队协作中设计和开发之间的鸿沟往往体现在文档的断层上。设计师在Figma中精心打磨的组件、样式和布局到了开发环节常常需要手动整理成设计规范文档这个过程不仅耗时而且极易出错一旦设计稿更新文档又得重来。我最近深度使用并研究了gabrielDF/figma-to-design-md这个开源项目它精准地击中了这个痛点。简单来说这是一个命令行工具能够自动将你的Figma设计文件或其中的特定页面、画板解析并生成结构清晰的Markdown设计文档。想象一下你只需要运行一条命令就能得到一个包含颜色变量、文本样式、组件库甚至布局栅格系统说明的.md文件。这个文件可以直接放入你的项目文档库与代码仓库一同管理实现设计资产的版本化。这不仅仅是“导出图片”那么简单它提取的是构成设计的元数据——十六进制色值、字体大小、字重、间距、阴影参数等并将其转化为人类可读、开发者友好的文档格式。对于追求高效协同和设计系统化的团队尤其是那些采用“设计即代码”Design as Code理念的团队这个工具的价值不言而喻。无论你是负责维护设计系统的设计师还是需要频繁查阅设计参数的开发者或是项目管理者都能从中获得效率的极大提升。2. 核心原理与架构拆解Figma API与AST的共舞这个工具的核心能力建立在两大支柱之上Figma的开放API和对文档结构的抽象语法树AST处理。理解其工作原理能帮助我们在使用中更好地定位问题和进行定制。2.1 Figma API数据之源figma-to-design-md首先是一个Figma API的客户端。它通过你提供的个人访问令牌Personal Access Token和文件ID向Figma服务器发起请求获取文件的完整JSON结构。这个JSON数据包就是Figma文件的“源代码”里面以树形结构完整记录了文件中每一个节点Node的信息包括画板Frame、组件Component、实例Instance、文本Text、矢量图形Vector等以及它们的所有属性位置、尺寸、填充色、描边、字体、效果如阴影、模糊等。工具的核心任务就是遍历这棵庞大的节点树从中筛选出我们关心的设计元素。例如它会识别出被标记为“颜色”或“Color”的画板提取其中形状的填充色作为颜色变量会收集所有文本图层并按其字体、字号、行高、字重等属性进行归类生成文本样式。注意Figma API有速率限制。免费计划每分钟的请求次数有限在处理大型、复杂的文件时工具可能需要分多次请求或者你可能遇到限流。因此合理规划文件结构如将设计资源集中到少数几个页面能提升生成效率。2.2 模版引擎与AST转换格式化之魂获取到原始的JSON数据后工具并没有直接拼接字符串生成Markdown。相反它采用了一种更优雅、更强大的方式基于抽象语法树的模版引擎。项目内部定义了一套用于描述设计文档结构的“语法”或“模式”Schema。这个模式规定了设计文档应该包含哪些部分如“颜色”、“排版”、“组件”以及每个部分的数据应该如何组织。工具的工作流是原始Figma数据 - 数据提取器 - 符合内部模式的结构化数据 - 模版引擎 - Markdown文本。数据提取与转换针对颜色、文本样式、组件等不同类型有专门的提取器Extractor。它们像过滤器一样从Figma节点树中捞出目标数据并转换成内部模式定义的数据结构。例如颜色提取器会输出{ name: Primary Blue, value: #007AFF, description: 主要品牌色 }这样的对象数组。模版渲染工具使用像Handlebars或EJS这样的模版引擎具体实现可能不同将上一步得到的结构化数据注入到预设的Markdown模版文件中。模版中包含了Markdown的标题、列表、表格语法以及用于插入动态数据的占位符如{{#each colors}}...{{/each}}。这种架构的优势在于关注点分离和可扩展性。数据提取逻辑和文档呈现逻辑是解耦的。如果你想改变生成的Markdown样式比如想用不同的表格风格你只需要修改模版文件无需触碰复杂的数据提取代码。更强大的是如果你想支持导出为另一种格式如JSON、YAML甚至直接生成CSS变量文件你只需要为这种格式编写一个新的模版和渲染器即可核心的数据提取逻辑可以复用。3. 环境准备与工具配置从零开始的实操指南要让figma-to-design-md跑起来你需要完成几个关键步骤的配置。这个过程涉及到开发环境和Figma账户的权限设置。3.1 本地开发环境搭建首先你需要一个基本的Node.js开发环境。这个工具本身是用JavaScript/TypeScript编写的通过npm进行包管理。安装Node.js与npm访问Node.js官网下载并安装LTS长期支持版本。安装完成后在终端运行node -v和npm -v来验证安装是否成功。我推荐使用nvmNode Version Manager来管理Node.js版本这样可以轻松地在不同项目间切换版本。获取项目代码你可以通过Git克隆仓库或者直接下载ZIP包。对于持续使用和贡献克隆仓库是更好的选择。git clone https://github.com/gabrielDF/figma-to-design-md.git cd figma-to-design-md安装项目依赖进入项目根目录运行安装命令。通常项目会提供package.json文件。npm install # 或者如果你看到有 yarn.lock 文件也可以使用 # yarn install这个过程会下载工具运行所需的所有第三方库包括Figma API客户端、模版引擎、命令行参数解析器等。3.2 Figma访问令牌与文件权限获取这是最关键的一步因为工具需要代表你与Figma对话。生成个人访问令牌Personal Access Token登录你的Figma账户。点击右上角个人头像进入“Settings”设置。在左侧菜单找到并点击“Personal access tokens”个人访问令牌。点击“Create new token”创建新令牌。输入一个易于识别的令牌名称例如 “Design Doc Generator”。在权限Scopes选择中至少需要勾选“File read”。这个权限允许令牌读取你拥有访问权限的文件内容。为了安全遵循最小权限原则不要勾选不必要的写权限。点击“Create”生成令牌。重要Figma只会显示这一次令牌字符串请立即将其复制并安全保存例如保存在本地的密码管理器或环境变量中。关闭页面后你将无法再次查看完整令牌。获取Figma文件ID在浏览器中打开你想要生成文档的Figma文件。观察浏览器的地址栏。URL的格式通常是https://www.figma.com/file/[FILE_ID]/[FILE_NAME]。FILE_ID就是你需要的那一串由数字和字母组成的字符串。复制它。检查文件访问权限确保你用于生成令牌的Figma账户对该文件至少拥有“可以查看”View的权限。如果是团队文件你可能需要被邀请为查看者。3.3 基础配置与首次运行项目通常会提供一个配置文件如config.json或figma.config.js或要求通过命令行参数传入必要信息。一种常见的方式是通过环境变量来传递敏感信息如访问令牌通过命令行参数传递文件ID等动态信息。# 在终端中设置环境变量Linux/macOS export FIGMA_ACCESS_TOKEN你的个人访问令牌 # Windows (Command Prompt) set FIGMA_ACCESS_TOKEN你的个人访问令牌 # Windows (PowerShell) $env:FIGMA_ACCESS_TOKEN你的个人访问令牌然后运行工具提供的命令。具体命令需要查看项目的README.md通常类似这样# 假设工具提供了一个名为 generate-doc 的命令 npx generate-doc --fileId YOUR_FILE_ID --output ./design-system.md # 或者如果工具是本地安装并配置了npm scripts npm run generate -- --fileId YOUR_FILE_ID首次运行可能会因为网络或权限问题失败需要根据错误信息进行排查。4. 核心功能深度解析与定制化成功运行基础命令后你会得到一个基础的Markdown文档。但要让这份文档真正贴合你的团队工作流必须深入理解其核心功能并进行定制。4.1 设计令牌Design Tokens的提取策略现代设计系统的基石是“设计令牌”——命名的实体用于存储视觉设计属性。figma-to-design-md的核心价值就在于自动化提取这些令牌。颜色令牌工具如何识别一个色板常见策略是寻找特定命名规则的画板或图层组。例如它会扫描所有画板寻找名称包含“Colors”、“Palette”、“颜色”、“色板”的画板。然后提取该画板内所有形状矩形、圆形等的“填充”Fills属性中的十六进制色值。图层或画板的名称如“Primary/Blue/500”会被用作令牌的名称。实操心得为了获得最佳提取效果请在Figma中严格规范你的颜色板命名和结构。建议使用一个独立的页面Page来存放所有颜色并使用清晰的画板Frame进行分组如“基础色”、“语义色”、“中性色”。画板内每个色块可以用一个简单的矩形表示并确保其命名就是你想在文档中看到的令牌名例如primary.500。排版令牌文本样式工具会遍历文件中的所有文本图层收集它们的字体家族Font Family、字号Font Size、字重Font Weight、行高Line Height、字母间距Letter Spacing等属性。然后它会根据这些属性的组合将文本图层聚类成不同的“文本样式”。注意事项Figma中文本样式的覆盖Override可能会干扰提取。如果一个文本图层应用了某个样式但又做了局部修改如只改了颜色工具可能需要判断是将其视为新样式还是忽略覆盖。通常更可靠的策略是直接提取Figma中已创建并命名好的“文本样式”Text Styles这需要工具调用对应的API。在配置时请明确工具采用的是“从图层推断”还是“从已发布样式获取”的策略。间距与尺寸令牌高级的配置可以提取用于间距Spacing和尺寸Sizing的令牌。这通常通过分析画板内元素的间隔Gaps、内边距Padding或一些具有标准尺寸如8px, 16px, 24px…的参考线或形状来实现。这需要更复杂的启发式算法可能不是所有工具版本都默认开启。4.2 组件库文档的生成逻辑除了样式令牌另一个重头戏是组件Components文档。工具可以列出Figma文件中的所有主组件Main Component及其变体Variants。组件识别通过API获取所有类型为COMPONENT和COMPONENT_SET的节点。属性与变体解析对于组件集工具会解析其变体属性如typeprimary/secondary,sizesmall/medium/large并在文档中以表格形式展示这些属性的组合。使用示例与说明理想的文档还应包含组件的描述、Props属性列表以及使用示例。这部分信息可以来自两个地方Figma图层描述鼓励设计师在Figma组件的主画板或一个特定“文档”页面上使用文本图层来编写描述和属性说明。工具可以通过提取这些特定位置的文本来丰富文档。外部映射文件更工程化的做法是维护一个外部的JSON或YAML配置文件将Figma组件的ID与其详细的文档说明包括代码Prop类型、默认值等映射起来。工具在生成时读取这个映射文件将信息注入到文档中。4.3 模版定制与输出格式化默认生成的Markdown可能不符合你公司的文档规范。这时就需要定制模版。定位模版文件在项目代码中查找templates/目录或类似命名的文件夹。里面应该会有.hbs(Handlebars)、.ejs或.md.template文件。理解模版语法学习所用模版引擎的基础语法。以Handlebars为例你需要了解如何循环数组{{#each}}、输出变量{{variable}}、使用条件判断{{#if}}。修改与创建你可以修改现有的模版或者复制一份作为基础创建自己的新模版。例如你可以改变文档的整体结构先介绍组件再介绍样式。为颜色令牌添加一个色块预览在Markdown中可以使用div配合style内联CSS但并非所有渲染器都支持。更通用的做法是生成一个颜色表格并在旁边用文字描述色值。调整表格的列顺序增加“使用场景”、“注意事项”等列这些数据需要从Figma描述或配置文件中获取。在文档头部添加你公司的Logo和文档版本信息。一个简单的Handlebars模版片段可能长这样## 颜色系统 | 名称 | 色值 | 描述 | |------|------|------| {{#each colors}} | {{this.name}} | {{this.value}} | {{this.description}} | {{/each}} ## 文本样式 {{#each textStyles}} ### {{this.name}} * **字体**: {{this.fontFamily}} * **字号**: {{this.fontSize}}px * **字重**: {{this.fontWeight}} * **行高**: {{this.lineHeight}}px {{/each}}通过定制模版你可以让生成的文档无缝接入你的Confluence、GitBook或任何其他Markdown驱动的文档平台。5. 集成到CI/CD与自动化工作流单次运行工具生成文档很有用但真正的威力在于自动化。我们可以将其集成到持续集成/持续部署CI/CD流水线中确保设计文档与设计文件同步更新。5.1 基于Git Hooks的本地自动化对于小型团队或个人项目可以在本地利用Git的pre-commit或post-merge钩子在提交代码或拉取更新后自动生成/更新设计文档。在项目根目录的.git/hooks目录下或使用husky这样的工具更方便地管理创建一个pre-commit脚本。脚本内容大致是运行figma-to-design-md命令生成最新的design-system.md文件然后将这个文件添加到本次Git提交中。这样每次设计师更新Figma并同步了文件ID或开发拉取了包含新文件ID的配置在提交代码时文档就会自动更新并包含在提交历史里。5.2 基于GitHub Actions/GitLab CI的云端自动化这是更健壮、更适合团队协作的方式。以GitHub Actions为例在项目仓库中创建.github/workflows/update-design-docs.yml文件。配置一个定时任务例如每天凌晨2点或者监听对特定配置文件如figma.config.json的推送事件来触发工作流。在工作流中设置好FIGMA_ACCESS_TOKEN作为仓库的加密Secret。工作流步骤包括检出代码、安装Node.js环境、安装项目依赖、运行文档生成命令。关键的一步使用git命令检查生成的design-system.md是否有变化。如果有变化自动创建一个新的提交并推送到仓库或者创建一个Pull RequestPR来通知团队成员设计规范已更新。name: Update Design Documentation on: schedule: - cron: 0 2 * * * # 每天UTC时间2点运行 push: paths: - figma.config.json # 当配置文件变更时也运行 jobs: update-docs: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 with: token: ${{ secrets.GITHUB_TOKEN }} - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: 18 - name: Install Dependencies run: npm ci - name: Generate Design Doc run: npm run generate-doc env: FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }} - name: Check for changes and commit run: | git config --global user.name github-actions[bot] git config --global user.email github-actions[bot]users.noreply.github.com git add design-system.md if git diff --staged --quiet; then echo No changes to design docs. else git commit -m docs: auto-update design system from Figma git push fi这样设计文档就成为了一个由Figma源文件驱动的、自动更新的“活文档”极大地降低了维护成本。6. 常见问题、排查技巧与进阶优化在实际使用中你肯定会遇到各种问题。以下是我踩过的一些坑和解决方案。6.1 常见错误与排查表问题现象可能原因排查步骤与解决方案认证失败(401/403错误)1. 访问令牌无效或已过期。2. 令牌权限不足缺少file:read。3. 文件ID错误或账户无文件访问权限。1. 去Figma设置中重新生成令牌并更新环境变量/配置。2. 确认令牌Scopes包含file:read。3. 核对文件ID并确保当前账户能被文件所有者访问。尝试在浏览器中用该账户直接打开文件链接。网络超时或连接错误1. 网络不稳定。2. Figma API服务暂时性问题。3. 文件过大请求超时。1. 检查本地网络尝试重试。2. 查看Figma Status页面确认API服务状态。3. 尝试在Figma中简化文件或将设计资源拆分到多个文件分别生成文档。工具配置中可能可以调整超时时间。生成文档为空或缺失内容1. Figma文件结构不符合工具的提取规则。2. 配置错误指定了错误的页面或画板名称。3. 提取器Extractor逻辑有Bug或版本不匹配。1. 使用--debug或--verbose参数运行工具查看它遍历了哪些节点提取了哪些数据。这是最重要的调试手段。2. 仔细检查配置文件中的pageNames,frameNames等过滤条件确保它们与Figma中的命名完全匹配注意大小写和空格。3. 对照工具的版本和Figma API的版本。有时Figma更新API后工具需要相应更新。查看项目的Issue列表是否有类似问题。生成的Markdown格式错乱1. 模版文件语法错误。2. 数据中包含特殊字符如,未做转义破坏了Markdown表格。6.2 性能优化与处理大型文件当你的Figma文件包含数百个组件和数千个图层时生成过程可能会变慢甚至内存不足。增量提取不要每次都全量生成整个文档。如果工具支持可以配置只提取特定页面或画板。例如颜色和排版样式在一个“Foundation”页面组件在另一个“Components”页面可以分别运行命令生成最后手动或再用脚本合并。缓存机制高级用法是实现一个简单的缓存层。将Figma API返回的原始JSON缓存到本地文件例如以文件ID和最后修改时间为键。下次运行时先检查Figma文件的“最后修改时间戳”API响应中包含如果未变化则直接使用缓存数据生成文档跳过网络请求。这能极大提升重复生成的速度并减少对API的调用。分页处理对于返回大量数据的API请求如列出所有组件检查工具是否实现了分页Pagination逻辑。如果没有你可能需要修改代码循环请求直到获取所有数据。6.3 与现有设计系统代码库联动终极目标是打通设计到代码的闭环。figma-to-design-md生成的是文档但我们可以更进一步。生成CSS/SCSS变量文件修改或新建一个模版不输出Markdown而是输出.css或.scss文件。例如将颜色令牌输出为:root { --color-primary-500: #007AFF; }将文本样式输出为Sass mixin或CSS类。这样开发可以直接引用这个样式文件。生成TypeScript类型定义如果你的设计系统有对应的React组件库可以生成描述组件Props的TypeScript接口定义文件.d.ts。这需要更复杂的数据映射通常需要额外的配置文件来定义Figma组件属性与TS类型的对应关系。集成到Storybook将生成的组件文档包括属性描述、变体说明转化为Storybook的.mdx文件或直接生成Stories让组件文档和可视化示例在一起。这个过程需要更深入的脚本编写和集成工作但一旦搭建完成就能实现“Figma更新 - 自动生成设计令牌和组件文档 - 同步至代码库和Storybook”的自动化流水线将设计和开发的协作效率提升到一个新的高度。
Figma设计稿自动化生成Markdown文档：原理、配置与CI/CD集成实践
发布时间：2026/5/18 22:01:18
1. 项目概述从设计稿到结构化文档的自动化桥梁在团队协作中设计和开发之间的鸿沟往往体现在文档的断层上。设计师在Figma中精心打磨的组件、样式和布局到了开发环节常常需要手动整理成设计规范文档这个过程不仅耗时而且极易出错一旦设计稿更新文档又得重来。我最近深度使用并研究了gabrielDF/figma-to-design-md这个开源项目它精准地击中了这个痛点。简单来说这是一个命令行工具能够自动将你的Figma设计文件或其中的特定页面、画板解析并生成结构清晰的Markdown设计文档。想象一下你只需要运行一条命令就能得到一个包含颜色变量、文本样式、组件库甚至布局栅格系统说明的.md文件。这个文件可以直接放入你的项目文档库与代码仓库一同管理实现设计资产的版本化。这不仅仅是“导出图片”那么简单它提取的是构成设计的元数据——十六进制色值、字体大小、字重、间距、阴影参数等并将其转化为人类可读、开发者友好的文档格式。对于追求高效协同和设计系统化的团队尤其是那些采用“设计即代码”Design as Code理念的团队这个工具的价值不言而喻。无论你是负责维护设计系统的设计师还是需要频繁查阅设计参数的开发者或是项目管理者都能从中获得效率的极大提升。2. 核心原理与架构拆解Figma API与AST的共舞这个工具的核心能力建立在两大支柱之上Figma的开放API和对文档结构的抽象语法树AST处理。理解其工作原理能帮助我们在使用中更好地定位问题和进行定制。2.1 Figma API数据之源figma-to-design-md首先是一个Figma API的客户端。它通过你提供的个人访问令牌Personal Access Token和文件ID向Figma服务器发起请求获取文件的完整JSON结构。这个JSON数据包就是Figma文件的“源代码”里面以树形结构完整记录了文件中每一个节点Node的信息包括画板Frame、组件Component、实例Instance、文本Text、矢量图形Vector等以及它们的所有属性位置、尺寸、填充色、描边、字体、效果如阴影、模糊等。工具的核心任务就是遍历这棵庞大的节点树从中筛选出我们关心的设计元素。例如它会识别出被标记为“颜色”或“Color”的画板提取其中形状的填充色作为颜色变量会收集所有文本图层并按其字体、字号、行高、字重等属性进行归类生成文本样式。注意Figma API有速率限制。免费计划每分钟的请求次数有限在处理大型、复杂的文件时工具可能需要分多次请求或者你可能遇到限流。因此合理规划文件结构如将设计资源集中到少数几个页面能提升生成效率。2.2 模版引擎与AST转换格式化之魂获取到原始的JSON数据后工具并没有直接拼接字符串生成Markdown。相反它采用了一种更优雅、更强大的方式基于抽象语法树的模版引擎。项目内部定义了一套用于描述设计文档结构的“语法”或“模式”Schema。这个模式规定了设计文档应该包含哪些部分如“颜色”、“排版”、“组件”以及每个部分的数据应该如何组织。工具的工作流是原始Figma数据 - 数据提取器 - 符合内部模式的结构化数据 - 模版引擎 - Markdown文本。数据提取与转换针对颜色、文本样式、组件等不同类型有专门的提取器Extractor。它们像过滤器一样从Figma节点树中捞出目标数据并转换成内部模式定义的数据结构。例如颜色提取器会输出{ name: Primary Blue, value: #007AFF, description: 主要品牌色 }这样的对象数组。模版渲染工具使用像Handlebars或EJS这样的模版引擎具体实现可能不同将上一步得到的结构化数据注入到预设的Markdown模版文件中。模版中包含了Markdown的标题、列表、表格语法以及用于插入动态数据的占位符如{{#each colors}}...{{/each}}。这种架构的优势在于关注点分离和可扩展性。数据提取逻辑和文档呈现逻辑是解耦的。如果你想改变生成的Markdown样式比如想用不同的表格风格你只需要修改模版文件无需触碰复杂的数据提取代码。更强大的是如果你想支持导出为另一种格式如JSON、YAML甚至直接生成CSS变量文件你只需要为这种格式编写一个新的模版和渲染器即可核心的数据提取逻辑可以复用。3. 环境准备与工具配置从零开始的实操指南要让figma-to-design-md跑起来你需要完成几个关键步骤的配置。这个过程涉及到开发环境和Figma账户的权限设置。3.1 本地开发环境搭建首先你需要一个基本的Node.js开发环境。这个工具本身是用JavaScript/TypeScript编写的通过npm进行包管理。安装Node.js与npm访问Node.js官网下载并安装LTS长期支持版本。安装完成后在终端运行node -v和npm -v来验证安装是否成功。我推荐使用nvmNode Version Manager来管理Node.js版本这样可以轻松地在不同项目间切换版本。获取项目代码你可以通过Git克隆仓库或者直接下载ZIP包。对于持续使用和贡献克隆仓库是更好的选择。git clone https://github.com/gabrielDF/figma-to-design-md.git cd figma-to-design-md安装项目依赖进入项目根目录运行安装命令。通常项目会提供package.json文件。npm install # 或者如果你看到有 yarn.lock 文件也可以使用 # yarn install这个过程会下载工具运行所需的所有第三方库包括Figma API客户端、模版引擎、命令行参数解析器等。3.2 Figma访问令牌与文件权限获取这是最关键的一步因为工具需要代表你与Figma对话。生成个人访问令牌Personal Access Token登录你的Figma账户。点击右上角个人头像进入“Settings”设置。在左侧菜单找到并点击“Personal access tokens”个人访问令牌。点击“Create new token”创建新令牌。输入一个易于识别的令牌名称例如 “Design Doc Generator”。在权限Scopes选择中至少需要勾选“File read”。这个权限允许令牌读取你拥有访问权限的文件内容。为了安全遵循最小权限原则不要勾选不必要的写权限。点击“Create”生成令牌。重要Figma只会显示这一次令牌字符串请立即将其复制并安全保存例如保存在本地的密码管理器或环境变量中。关闭页面后你将无法再次查看完整令牌。获取Figma文件ID在浏览器中打开你想要生成文档的Figma文件。观察浏览器的地址栏。URL的格式通常是https://www.figma.com/file/[FILE_ID]/[FILE_NAME]。FILE_ID就是你需要的那一串由数字和字母组成的字符串。复制它。检查文件访问权限确保你用于生成令牌的Figma账户对该文件至少拥有“可以查看”View的权限。如果是团队文件你可能需要被邀请为查看者。3.3 基础配置与首次运行项目通常会提供一个配置文件如config.json或figma.config.js或要求通过命令行参数传入必要信息。一种常见的方式是通过环境变量来传递敏感信息如访问令牌通过命令行参数传递文件ID等动态信息。# 在终端中设置环境变量Linux/macOS export FIGMA_ACCESS_TOKEN你的个人访问令牌 # Windows (Command Prompt) set FIGMA_ACCESS_TOKEN你的个人访问令牌 # Windows (PowerShell) $env:FIGMA_ACCESS_TOKEN你的个人访问令牌然后运行工具提供的命令。具体命令需要查看项目的README.md通常类似这样# 假设工具提供了一个名为 generate-doc 的命令 npx generate-doc --fileId YOUR_FILE_ID --output ./design-system.md # 或者如果工具是本地安装并配置了npm scripts npm run generate -- --fileId YOUR_FILE_ID首次运行可能会因为网络或权限问题失败需要根据错误信息进行排查。4. 核心功能深度解析与定制化成功运行基础命令后你会得到一个基础的Markdown文档。但要让这份文档真正贴合你的团队工作流必须深入理解其核心功能并进行定制。4.1 设计令牌Design Tokens的提取策略现代设计系统的基石是“设计令牌”——命名的实体用于存储视觉设计属性。figma-to-design-md的核心价值就在于自动化提取这些令牌。颜色令牌工具如何识别一个色板常见策略是寻找特定命名规则的画板或图层组。例如它会扫描所有画板寻找名称包含“Colors”、“Palette”、“颜色”、“色板”的画板。然后提取该画板内所有形状矩形、圆形等的“填充”Fills属性中的十六进制色值。图层或画板的名称如“Primary/Blue/500”会被用作令牌的名称。实操心得为了获得最佳提取效果请在Figma中严格规范你的颜色板命名和结构。建议使用一个独立的页面Page来存放所有颜色并使用清晰的画板Frame进行分组如“基础色”、“语义色”、“中性色”。画板内每个色块可以用一个简单的矩形表示并确保其命名就是你想在文档中看到的令牌名例如primary.500。排版令牌文本样式工具会遍历文件中的所有文本图层收集它们的字体家族Font Family、字号Font Size、字重Font Weight、行高Line Height、字母间距Letter Spacing等属性。然后它会根据这些属性的组合将文本图层聚类成不同的“文本样式”。注意事项Figma中文本样式的覆盖Override可能会干扰提取。如果一个文本图层应用了某个样式但又做了局部修改如只改了颜色工具可能需要判断是将其视为新样式还是忽略覆盖。通常更可靠的策略是直接提取Figma中已创建并命名好的“文本样式”Text Styles这需要工具调用对应的API。在配置时请明确工具采用的是“从图层推断”还是“从已发布样式获取”的策略。间距与尺寸令牌高级的配置可以提取用于间距Spacing和尺寸Sizing的令牌。这通常通过分析画板内元素的间隔Gaps、内边距Padding或一些具有标准尺寸如8px, 16px, 24px…的参考线或形状来实现。这需要更复杂的启发式算法可能不是所有工具版本都默认开启。4.2 组件库文档的生成逻辑除了样式令牌另一个重头戏是组件Components文档。工具可以列出Figma文件中的所有主组件Main Component及其变体Variants。组件识别通过API获取所有类型为COMPONENT和COMPONENT_SET的节点。属性与变体解析对于组件集工具会解析其变体属性如typeprimary/secondary,sizesmall/medium/large并在文档中以表格形式展示这些属性的组合。使用示例与说明理想的文档还应包含组件的描述、Props属性列表以及使用示例。这部分信息可以来自两个地方Figma图层描述鼓励设计师在Figma组件的主画板或一个特定“文档”页面上使用文本图层来编写描述和属性说明。工具可以通过提取这些特定位置的文本来丰富文档。外部映射文件更工程化的做法是维护一个外部的JSON或YAML配置文件将Figma组件的ID与其详细的文档说明包括代码Prop类型、默认值等映射起来。工具在生成时读取这个映射文件将信息注入到文档中。4.3 模版定制与输出格式化默认生成的Markdown可能不符合你公司的文档规范。这时就需要定制模版。定位模版文件在项目代码中查找templates/目录或类似命名的文件夹。里面应该会有.hbs(Handlebars)、.ejs或.md.template文件。理解模版语法学习所用模版引擎的基础语法。以Handlebars为例你需要了解如何循环数组{{#each}}、输出变量{{variable}}、使用条件判断{{#if}}。修改与创建你可以修改现有的模版或者复制一份作为基础创建自己的新模版。例如你可以改变文档的整体结构先介绍组件再介绍样式。为颜色令牌添加一个色块预览在Markdown中可以使用div配合style内联CSS但并非所有渲染器都支持。更通用的做法是生成一个颜色表格并在旁边用文字描述色值。调整表格的列顺序增加“使用场景”、“注意事项”等列这些数据需要从Figma描述或配置文件中获取。在文档头部添加你公司的Logo和文档版本信息。一个简单的Handlebars模版片段可能长这样## 颜色系统 | 名称 | 色值 | 描述 | |------|------|------| {{#each colors}} | {{this.name}} | {{this.value}} | {{this.description}} | {{/each}} ## 文本样式 {{#each textStyles}} ### {{this.name}} * **字体**: {{this.fontFamily}} * **字号**: {{this.fontSize}}px * **字重**: {{this.fontWeight}} * **行高**: {{this.lineHeight}}px {{/each}}通过定制模版你可以让生成的文档无缝接入你的Confluence、GitBook或任何其他Markdown驱动的文档平台。5. 集成到CI/CD与自动化工作流单次运行工具生成文档很有用但真正的威力在于自动化。我们可以将其集成到持续集成/持续部署CI/CD流水线中确保设计文档与设计文件同步更新。5.1 基于Git Hooks的本地自动化对于小型团队或个人项目可以在本地利用Git的pre-commit或post-merge钩子在提交代码或拉取更新后自动生成/更新设计文档。在项目根目录的.git/hooks目录下或使用husky这样的工具更方便地管理创建一个pre-commit脚本。脚本内容大致是运行figma-to-design-md命令生成最新的design-system.md文件然后将这个文件添加到本次Git提交中。这样每次设计师更新Figma并同步了文件ID或开发拉取了包含新文件ID的配置在提交代码时文档就会自动更新并包含在提交历史里。5.2 基于GitHub Actions/GitLab CI的云端自动化这是更健壮、更适合团队协作的方式。以GitHub Actions为例在项目仓库中创建.github/workflows/update-design-docs.yml文件。配置一个定时任务例如每天凌晨2点或者监听对特定配置文件如figma.config.json的推送事件来触发工作流。在工作流中设置好FIGMA_ACCESS_TOKEN作为仓库的加密Secret。工作流步骤包括检出代码、安装Node.js环境、安装项目依赖、运行文档生成命令。关键的一步使用git命令检查生成的design-system.md是否有变化。如果有变化自动创建一个新的提交并推送到仓库或者创建一个Pull RequestPR来通知团队成员设计规范已更新。name: Update Design Documentation on: schedule: - cron: 0 2 * * * # 每天UTC时间2点运行 push: paths: - figma.config.json # 当配置文件变更时也运行 jobs: update-docs: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 with: token: ${{ secrets.GITHUB_TOKEN }} - name: Setup Node.js uses: actions/setup-nodev3 with: node-version: 18 - name: Install Dependencies run: npm ci - name: Generate Design Doc run: npm run generate-doc env: FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }} - name: Check for changes and commit run: | git config --global user.name github-actions[bot] git config --global user.email github-actions[bot]users.noreply.github.com git add design-system.md if git diff --staged --quiet; then echo No changes to design docs. else git commit -m docs: auto-update design system from Figma git push fi这样设计文档就成为了一个由Figma源文件驱动的、自动更新的“活文档”极大地降低了维护成本。6. 常见问题、排查技巧与进阶优化在实际使用中你肯定会遇到各种问题。以下是我踩过的一些坑和解决方案。6.1 常见错误与排查表问题现象可能原因排查步骤与解决方案认证失败(401/403错误)1. 访问令牌无效或已过期。2. 令牌权限不足缺少file:read。3. 文件ID错误或账户无文件访问权限。1. 去Figma设置中重新生成令牌并更新环境变量/配置。2. 确认令牌Scopes包含file:read。3. 核对文件ID并确保当前账户能被文件所有者访问。尝试在浏览器中用该账户直接打开文件链接。网络超时或连接错误1. 网络不稳定。2. Figma API服务暂时性问题。3. 文件过大请求超时。1. 检查本地网络尝试重试。2. 查看Figma Status页面确认API服务状态。3. 尝试在Figma中简化文件或将设计资源拆分到多个文件分别生成文档。工具配置中可能可以调整超时时间。生成文档为空或缺失内容1. Figma文件结构不符合工具的提取规则。2. 配置错误指定了错误的页面或画板名称。3. 提取器Extractor逻辑有Bug或版本不匹配。1. 使用--debug或--verbose参数运行工具查看它遍历了哪些节点提取了哪些数据。这是最重要的调试手段。2. 仔细检查配置文件中的pageNames,frameNames等过滤条件确保它们与Figma中的命名完全匹配注意大小写和空格。3. 对照工具的版本和Figma API的版本。有时Figma更新API后工具需要相应更新。查看项目的Issue列表是否有类似问题。生成的Markdown格式错乱1. 模版文件语法错误。2. 数据中包含特殊字符如,未做转义破坏了Markdown表格。6.2 性能优化与处理大型文件当你的Figma文件包含数百个组件和数千个图层时生成过程可能会变慢甚至内存不足。增量提取不要每次都全量生成整个文档。如果工具支持可以配置只提取特定页面或画板。例如颜色和排版样式在一个“Foundation”页面组件在另一个“Components”页面可以分别运行命令生成最后手动或再用脚本合并。缓存机制高级用法是实现一个简单的缓存层。将Figma API返回的原始JSON缓存到本地文件例如以文件ID和最后修改时间为键。下次运行时先检查Figma文件的“最后修改时间戳”API响应中包含如果未变化则直接使用缓存数据生成文档跳过网络请求。这能极大提升重复生成的速度并减少对API的调用。分页处理对于返回大量数据的API请求如列出所有组件检查工具是否实现了分页Pagination逻辑。如果没有你可能需要修改代码循环请求直到获取所有数据。6.3 与现有设计系统代码库联动终极目标是打通设计到代码的闭环。figma-to-design-md生成的是文档但我们可以更进一步。生成CSS/SCSS变量文件修改或新建一个模版不输出Markdown而是输出.css或.scss文件。例如将颜色令牌输出为:root { --color-primary-500: #007AFF; }将文本样式输出为Sass mixin或CSS类。这样开发可以直接引用这个样式文件。生成TypeScript类型定义如果你的设计系统有对应的React组件库可以生成描述组件Props的TypeScript接口定义文件.d.ts。这需要更复杂的数据映射通常需要额外的配置文件来定义Figma组件属性与TS类型的对应关系。集成到Storybook将生成的组件文档包括属性描述、变体说明转化为Storybook的.mdx文件或直接生成Stories让组件文档和可视化示例在一起。这个过程需要更深入的脚本编写和集成工作但一旦搭建完成就能实现“Figma更新 - 自动生成设计令牌和组件文档 - 同步至代码库和Storybook”的自动化流水线将设计和开发的协作效率提升到一个新的高度。
