Figma Console MCP Token格式化引擎源码解读10种输出格式如何实现【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcpFigma Console MCPfigma-console-mcp是一个开源的 Figma 设计系统 MCP 服务核心理念是 Your design system as an API——它通过 AI 连接 Figma完成设计 Token 的提取、创建与调试。其中最硬核的模块是能把 Figma 变量一键转换为 CSS 变量、Tailwind v3/v4 配置、SCSS 变量、TS 模块、DTCG 标准 JSON 等10 种以上输出格式的 Token 格式化引擎。本文将从源码视角拆解它的实现原理 整体架构一个规范化中间态 格式化器分发整个引擎位于 src/core/tokens/ 目录下采用经典的Canonical Document规范化文档 分发器Dispatcher架构Figma 变量 → figma-converter → TokenDocument中间态 ↓ format() 分发器 ↓ ↓ ↓ ↓ DTCG CSS Tailwind SCSS ...关键洞察所有格式器都不直接读 Figma 数据而是消费统一的TokenDocument结构定义在 types.ts。这意味着✅ 新增一种输出格式 新增一个纯函数互不干扰✅ 每种格式器的输入输出契约一致(doc, options) → FormatResult✅ 解析parsers与格式化formatters对称设计支持双向同步分发逻辑集中在 formatters/index.ts 的format()函数一个 switch 分支把请求路由到具体格式器并用 TypeScript 的never穷尽检查保证新格式不会被漏掉。12 种导出格式在 types.ts 中以ExportFormat联合类型声明按优先级分为四类规范输出DTCG、Tokens Studio、即开即用的 CSS 家族CSS 变量、Tailwind v4/v3、SCSS、Less、代码模块TS 模块、JSON 平铺/嵌套、向后兼容Style Dictionary v3。格式一DTCG —— 一切的源头formatters/dtcg.ts 是规范格式canonical output——其他所有格式理论上都能从它推导。它产出 W3C Design Tokens 标准的 JSON有三个值得注意的细节细节处理方式多模式Light/Dark推荐按模式拆分为多个文件splitByMode这也是 Style Dictionary v4 和 Tokens Studio 的通行做法非破坏性回写通过$extensions[figma-console-mcp]存储 Figma 变量 ID其他 DTCG 工具会原样保留此字段保证同步往返不丢信息复合 Token字体排版、阴影、渐变输出为 DTCG 结构化的$value对象此外还有一个dtcgDialect选项默认legacy保证与历史输出字节级一致可选2025启用 DTCG 2025.10 的对象化颜色/尺寸表示转换逻辑在 dialect.ts。格式二CSS 变量 —— 别名变var()暗色模式零成本formatters/css-vars.ts 是从中间态到运行时的第一种真实输出处理了三个真实痛点1️⃣ 路径安全化Figma 变量名经常出现空格、点号如tailwind colors/purple/50每段路径都会经过slugify归一化变成合法的 CSS 自定义属性名--tailwind-colors-purple-50。2️⃣ 别名保留级联语义本地别名不解析成字面值而是输出var(--target-token)让 CSS 原生级联继续工作——改一处处处生效。3️⃣ 跨库别名的优雅降级引用外部库变量的 Token__library:标记会跳过并输出注释说明原因同时向warnings收集告警——宁可留缺口让你决策也不生成坏 CSS。多模式映射遵循社区惯例selectorForDefault/Light→:rootDark→.dark对齐 Tailwind 的darkMode: class其他模式 →[data-theme...]格式三Tailwind v4 ——theme命名空间映射formatters/tailwind-v4.ts 适配 Tailwind v4 的 CSS-first 配置Token 直接写入theme inline { ... }块构建时生成bg-primary、text-foreground等工具类。核心是pathToTailwindName()的命名空间映射策略路径首段命中已知命名空间color、spacing、radius、shadow…→ 原样输出color/primary→--color-primary于是bg-primary直接可用未命中 → 按 Token 类型启发式补全color 类型 →color-*dimension 类型 →spacing-*去重逻辑避免theme.color.header这类路径生成color-theme-color-header的丑陋命名暗色模式的处理很巧妙主模式进theme inline其余模式输出到.dark/[data-theme...]选择器下运行时即可切换无需重新构建。格式四Tailwind v3 —— 导出时拍平别名formatters/tailwind-v3.ts 的输出是一个可直接require进tailwind.config.js的 JS 文件。与 v4 最大的差异在于Tailwind v3 构建期读取配置没有运行时级联所以别名必须通过resolveAliasChain在导出时解析为字面值。它还内置了一张 v3 主题键映射表color→colors、radius→borderRadius、text→fontSize、shadow→boxShadow…嵌套 Token 通过writeIntoTree构建成树形对象后输出多模式 Token 则拍平到主模式v3 的暗色方案由darkMode: class自行处理。格式五SCSS 变量 —— 没有级联就给你模式 Mapformatters/scss.ts 输出$ds-color-primary: #4085F2;形式的变量。由于 SCSS 变量没有运行时时换能力它提供了两种多模式方案splitByMode: true→ 每个模式一个文件单文件模式 → 主值输出为普通变量其余模式打包成 map$xxx--modes: (Dark: ..., Vibrant: ...)消费方用map-get取值其余格式各有所长格式文件特点TS 模块ts-module.ts输出as const常量 Tokens类型别名导出时解析为字面值跨库别名输出null加 TODO 注释让缺口显性化JSON 平铺/嵌套json.ts不带 DTCG 外壳的纯键值对供自定义构建脚本使用多模式用--mode后缀拍平Style Dictionary v3style-dictionary-v3.ts裸value/type字段无$前缀并做 v3 与 DTCG 的类型名映射照顾存量项目Tokens Studiotokens-studio.ts多文件布局$themes.json、$metadata.json、按集合拆分保留 Figma 绑定以支持插件send to FigmaLessless.ts目前是明确的占位实现抛出FormatterNotImplementedError路线图占位横切机制别名解析器是整个引擎的胶水所有格式器共享 alias-resolver.ts 提供的三件套buildTokenIndex—— 全文档 Token 索引。注意是全文档而非当前文件因为别名经常跨集合引用语义层 → 原子层referenceTargetPath—— 解析带集合限定的引用{set-slug.path}resolveAliasChain—— 沿别名链一直追到字面值供 v3/TS/JSON 这类构建期求值格式使用不同格式对别名的策略差异正是理解这个引擎的钥匙运行时格式CSS 变量、Tailwind v4、SCSS保留引用语义构建期格式Tailwind v3、TS、JSON导出时求值——同一个中间态两套哲学。拆分策略splitByMode×splitByCollection每种格式都统一支持两个正交开关组合出四种文件布局单文件 │ 按模式拆分 │ 按集合拆分 │ 双重拆分 全量 │ 每个模式一个文件 │ 每个集合一个文件 │ (集合×模式) 每对一个文件文件名由slugify(集合名) slugify(模式名)动态拼接如semantic.dark.css也可通过filename选项显式指定。FormatResult.files返回文件数组而非单一字符串是这个多文件一等公民设计的体现。上手体验配置 MCP 后一句话导出在 AI 客户端中配置好figma-console-mcp后你只需要告诉 AI 把当前 Figma 文件的 Token 导出为 Tailwind v4 格式figma_export_tokens工具就会跑完 提取 → 转换 → 格式化 → 写文件 的全链路并返回 warnings 列表提示被跳过的跨库别名。更多工具用法可参考 docs/tools.md架构背景见 docs/architecture.md。小结这个引擎做对了什么单一中间态TokenDocument让 12 种格式各自独立演化策略外置别名解析时机运行时 vs 构建期由各格式自决而非一刀切失败显性化warnings 收集 注释占位坏 Token 不会静默污染产物字节级兼容意识legacy方言保证升级不破坏既有产物如果你想给项目加一种新格式只需要在 formatters/ 下写一个纯函数、在ExportFormat类型和format()分发器中注册即可——never穷尽检查会替你把关这就是这套架构最大的工程红利 【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Figma Console MCP Token格式化引擎源码解读：10种输出格式如何实现
Figma Console MCP Token格式化引擎源码解读10种输出格式如何实现【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcpFigma Console MCPfigma-console-mcp是一个开源的 Figma 设计系统 MCP 服务核心理念是 Your design system as an API——它通过 AI 连接 Figma完成设计 Token 的提取、创建与调试。其中最硬核的模块是能把 Figma 变量一键转换为 CSS 变量、Tailwind v3/v4 配置、SCSS 变量、TS 模块、DTCG 标准 JSON 等10 种以上输出格式的 Token 格式化引擎。本文将从源码视角拆解它的实现原理 整体架构一个规范化中间态 格式化器分发整个引擎位于 src/core/tokens/ 目录下采用经典的Canonical Document规范化文档 分发器Dispatcher架构Figma 变量 → figma-converter → TokenDocument中间态 ↓ format() 分发器 ↓ ↓ ↓ ↓ DTCG CSS Tailwind SCSS ...关键洞察所有格式器都不直接读 Figma 数据而是消费统一的TokenDocument结构定义在 types.ts。这意味着✅ 新增一种输出格式 新增一个纯函数互不干扰✅ 每种格式器的输入输出契约一致(doc, options) → FormatResult✅ 解析parsers与格式化formatters对称设计支持双向同步分发逻辑集中在 formatters/index.ts 的format()函数一个 switch 分支把请求路由到具体格式器并用 TypeScript 的never穷尽检查保证新格式不会被漏掉。12 种导出格式在 types.ts 中以ExportFormat联合类型声明按优先级分为四类规范输出DTCG、Tokens Studio、即开即用的 CSS 家族CSS 变量、Tailwind v4/v3、SCSS、Less、代码模块TS 模块、JSON 平铺/嵌套、向后兼容Style Dictionary v3。格式一DTCG —— 一切的源头formatters/dtcg.ts 是规范格式canonical output——其他所有格式理论上都能从它推导。它产出 W3C Design Tokens 标准的 JSON有三个值得注意的细节细节处理方式多模式Light/Dark推荐按模式拆分为多个文件splitByMode这也是 Style Dictionary v4 和 Tokens Studio 的通行做法非破坏性回写通过$extensions[figma-console-mcp]存储 Figma 变量 ID其他 DTCG 工具会原样保留此字段保证同步往返不丢信息复合 Token字体排版、阴影、渐变输出为 DTCG 结构化的$value对象此外还有一个dtcgDialect选项默认legacy保证与历史输出字节级一致可选2025启用 DTCG 2025.10 的对象化颜色/尺寸表示转换逻辑在 dialect.ts。格式二CSS 变量 —— 别名变var()暗色模式零成本formatters/css-vars.ts 是从中间态到运行时的第一种真实输出处理了三个真实痛点1️⃣ 路径安全化Figma 变量名经常出现空格、点号如tailwind colors/purple/50每段路径都会经过slugify归一化变成合法的 CSS 自定义属性名--tailwind-colors-purple-50。2️⃣ 别名保留级联语义本地别名不解析成字面值而是输出var(--target-token)让 CSS 原生级联继续工作——改一处处处生效。3️⃣ 跨库别名的优雅降级引用外部库变量的 Token__library:标记会跳过并输出注释说明原因同时向warnings收集告警——宁可留缺口让你决策也不生成坏 CSS。多模式映射遵循社区惯例selectorForDefault/Light→:rootDark→.dark对齐 Tailwind 的darkMode: class其他模式 →[data-theme...]格式三Tailwind v4 ——theme命名空间映射formatters/tailwind-v4.ts 适配 Tailwind v4 的 CSS-first 配置Token 直接写入theme inline { ... }块构建时生成bg-primary、text-foreground等工具类。核心是pathToTailwindName()的命名空间映射策略路径首段命中已知命名空间color、spacing、radius、shadow…→ 原样输出color/primary→--color-primary于是bg-primary直接可用未命中 → 按 Token 类型启发式补全color 类型 →color-*dimension 类型 →spacing-*去重逻辑避免theme.color.header这类路径生成color-theme-color-header的丑陋命名暗色模式的处理很巧妙主模式进theme inline其余模式输出到.dark/[data-theme...]选择器下运行时即可切换无需重新构建。格式四Tailwind v3 —— 导出时拍平别名formatters/tailwind-v3.ts 的输出是一个可直接require进tailwind.config.js的 JS 文件。与 v4 最大的差异在于Tailwind v3 构建期读取配置没有运行时级联所以别名必须通过resolveAliasChain在导出时解析为字面值。它还内置了一张 v3 主题键映射表color→colors、radius→borderRadius、text→fontSize、shadow→boxShadow…嵌套 Token 通过writeIntoTree构建成树形对象后输出多模式 Token 则拍平到主模式v3 的暗色方案由darkMode: class自行处理。格式五SCSS 变量 —— 没有级联就给你模式 Mapformatters/scss.ts 输出$ds-color-primary: #4085F2;形式的变量。由于 SCSS 变量没有运行时时换能力它提供了两种多模式方案splitByMode: true→ 每个模式一个文件单文件模式 → 主值输出为普通变量其余模式打包成 map$xxx--modes: (Dark: ..., Vibrant: ...)消费方用map-get取值其余格式各有所长格式文件特点TS 模块ts-module.ts输出as const常量 Tokens类型别名导出时解析为字面值跨库别名输出null加 TODO 注释让缺口显性化JSON 平铺/嵌套json.ts不带 DTCG 外壳的纯键值对供自定义构建脚本使用多模式用--mode后缀拍平Style Dictionary v3style-dictionary-v3.ts裸value/type字段无$前缀并做 v3 与 DTCG 的类型名映射照顾存量项目Tokens Studiotokens-studio.ts多文件布局$themes.json、$metadata.json、按集合拆分保留 Figma 绑定以支持插件send to FigmaLessless.ts目前是明确的占位实现抛出FormatterNotImplementedError路线图占位横切机制别名解析器是整个引擎的胶水所有格式器共享 alias-resolver.ts 提供的三件套buildTokenIndex—— 全文档 Token 索引。注意是全文档而非当前文件因为别名经常跨集合引用语义层 → 原子层referenceTargetPath—— 解析带集合限定的引用{set-slug.path}resolveAliasChain—— 沿别名链一直追到字面值供 v3/TS/JSON 这类构建期求值格式使用不同格式对别名的策略差异正是理解这个引擎的钥匙运行时格式CSS 变量、Tailwind v4、SCSS保留引用语义构建期格式Tailwind v3、TS、JSON导出时求值——同一个中间态两套哲学。拆分策略splitByMode×splitByCollection每种格式都统一支持两个正交开关组合出四种文件布局单文件 │ 按模式拆分 │ 按集合拆分 │ 双重拆分 全量 │ 每个模式一个文件 │ 每个集合一个文件 │ (集合×模式) 每对一个文件文件名由slugify(集合名) slugify(模式名)动态拼接如semantic.dark.css也可通过filename选项显式指定。FormatResult.files返回文件数组而非单一字符串是这个多文件一等公民设计的体现。上手体验配置 MCP 后一句话导出在 AI 客户端中配置好figma-console-mcp后你只需要告诉 AI 把当前 Figma 文件的 Token 导出为 Tailwind v4 格式figma_export_tokens工具就会跑完 提取 → 转换 → 格式化 → 写文件 的全链路并返回 warnings 列表提示被跳过的跨库别名。更多工具用法可参考 docs/tools.md架构背景见 docs/architecture.md。小结这个引擎做对了什么单一中间态TokenDocument让 12 种格式各自独立演化策略外置别名解析时机运行时 vs 构建期由各格式自决而非一刀切失败显性化warnings 收集 注释占位坏 Token 不会静默污染产物字节级兼容意识legacy方言保证升级不破坏既有产物如果你想给项目加一种新格式只需要在 formatters/ 下写一个纯函数、在ExportFormat类型和format()分发器中注册即可——never穷尽检查会替你把关这就是这套架构最大的工程红利 【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考