Material UI for Figma 设计套件：用本地变量与主题令牌打通设计与开发的协作链路

Material UI for Figma 是 Material UI 官方提供的 Figma 设计套件（Design Kit），它把 React 组件库中的组件以 1:1 的视觉形态带入 Figma，让设计师与开发者使用同一套术语（props、变量、设计令牌）进行沟通。本文基于仓库中的 官方文档，完整梳理设计套件的安装、主题变量定制、组件编辑、代码同步（Code sync）以及版本更新的实操流程，并结合仓库内 Sync 插件文档 的源码级细节，说明“设计即代码”这一链路是如何落地的。读完后，你将能够独立完成：在 Figma 中安装并使用 Material UI 设计套件、通过本地变量（local variables）定制品牌主题、编辑 Table 等复合组件，以及了解如何将 Figma 中的定制导出为 createTheme 主题代码。

一、Material UI for Figma 是什么

Material UI for Figma 由 React 组件库在 Figma 中的可视化表示（representations）组成，其目标是让设计师与开发者能够更高效地沟通与迭代。该设计套件包含三类内容：

• 与 Material UI 视觉一致的组件：Figma 中的组件样式与 React 组件的渲染结果保持一致；
• Material Design 未覆盖的附加组件与特性：即 React 库中有、但 Material Design 规范之外的扩展内容；
• 与 React 库共享的术语体系：props、变量、设计令牌（design tokens）等其他取值，在设计端与代码端使用同一套命名，减少沟通中的歧义。

从仓库中设计套件落地页的实现 DesignKitValues.tsx 可以看到，官方将其价值定位归纳为三类角色：

• 对设计师：省去从零搭建 Material UI 组件的时间，直接在常用设计工具中使用最新组件；
• 对产品负责人：使用产品真实使用的组件快速产出高保真原型与方案；
• 对开发者：与设计师围绕 Material UI 组件的 props 与变体使用同一套语言沟通，零摩擦交接。

二、社区版与完整版的区别及安装

设计套件提供两个版本，二者的能力差异如下（来自官方文档的对比表）：

能力	社区版（免费）	完整版（付费）
无定制化的组件	全部	全部
带定制化的组件	4 个	全部
Figma 变量（Figma variables）	无	支持

两个关键结论：

1. 想要使用 Figma 变量来管理主题令牌（palette、spacing、shape 等），必须使用完整版；社区版只提供未定制化的组件集合。
2. 社区版可用于体验，也支持配合 Sync 插件做主题生成测试（见下文“代码同步”一节）。

安装完整版

1. 从官方商店获取完整版后，解压包含 .fig 文件的 .zip 压缩包；
2. 二选一完成导入：
   • 按 Figma 官方的导入指南将文件导入 Figma 文件浏览器；
   • 将文件添加到团队库（team library），供整个团队共享使用——这是团队协作场景下的推荐做法。

跟踪版本更新

设计套件的更新记录发布在官方的 mui-design-kits 仓库 Releases 中（可按 "figma" 过滤），建议在引入设计套件前先看 Changelog，确认当前版本支持的组件与变量范围。

三、主题：用 Figma 本地变量定制颜色、排版与明暗模式

这是设计套件最核心的部分。设计套件使用 Figma 的本地变量（local variables） 构建了一组风格集合，其结构与 Material UI 代码中的 theme 结构相对应——也就是说，Figma 里的变量集合映射了 Material UI 默认主题 的层级：调色板、断点、形状、间距等令牌都存放在本地变量集合（local variable collections）中，而排版（typography）与阴影（shadow）相关的令牌则放在本地样式集合（local styles collection）中，这一区分在 Sync 插件文档 中同样有明确说明。

基于这一结构，官方文档给出了四个典型定制场景：

1. 查看所有可用变量

打开 Figma 的本地变量面板（点击变量筛选图标进入本地变量弹窗），即可看到设计套件预置的全部变量。设计套件出厂即带有完整映射到 React 库默认主题的设计令牌，可直接在此基础上调整。

2. 定制颜色

在变量面板中直接修改 palette 相关的变量值，所有引用该变量的组件会同步更新——这与在代码中修改 theme.palette 的效果一致。

3. 定制排版

注意：排版定制使用的是本地样式（local styles）而非本地变量，操作体验与改色类似——修改 typography 相关的 text style，组件中的文字样式随之变化。这与代码端 theme.typography 对应。

4. 切换明暗模式

设计套件利用本地变量支持变量模式（variable mode）在 light 与 dark 之间切换：切换模式后，同一套组件自动呈现明/暗两套取值，等价于代码端在 palette.mode 为 'light' / 'dark' 之间的切换。

这一机制与仓库中 Theming 文档 介绍的主题能力一脉相承：Figma 变量对应主题对象，Figma 模式对应 palette.mode，两者是结构化的同构关系，这也是后续 Code sync 能够把设计端令牌“翻译”成代码端主题的前提。

四、组件编辑技巧

批量编辑主组件

当需要一次性修改多个共享某属性的组件时，可以使用 Similayer 插件（Figma 社区插件）按属性批量选中组件，避免逐个打开主组件（main component）修改。

Table 组件：如何加列

Figma 中的 Table 与 Data Grid 组件默认只带有限数量的列，文档给出了两种加列方式：

1. 在实例上自由编辑：将单元格从其行（row）组件上分离（detach），之后就可以自由移动、增删内容，适合快速演示；
2. 在主组件上加列：直接在 Table / Data Grid 的主组件上复制单元格并粘贴为新列。这种方式会更新主组件本身，适合沉淀为团队的规范组件。

选择原则：一次性演示用方案 1，需要团队复用的标准表格结构用方案 2。

五、代码同步（Code sync）：从 Figma 导出主题令牌

设计套件的设计目标是尽可能贴近 React 组件（图层结构与命名刻意对齐），因此它原生支持通过 Material UI Sync 插件把 Figma 中的主题令牌与组件定制导出为代码。该链路的工作方式（依据 Sync 插件文档）：

• Sync 插件基于设计套件的本地变量集合（颜色调色板、断点、形状、间距令牌）与本地样式集合（排版、阴影令牌）提取定制，生成主题；
• 生成结果可直接在插件的主题页查看、复制，并通过 Storybook 预览页在线预览生成效果；
• 插件需要 Design Kit v5.16.0 及以上版本才能正确工作。

需要特别注意的是：Figma 文档中该章节标注为 beta，且仓库内文档已明确声明 Sync 插件的开发已于 2024 年暂停，不建议在新项目中使用（见 Sync 文档的提示 与 设计套件 FAQ）。因此，若当前项目需要“设计到主题代码”的能力，应将 Sync 作为参考实现来理解其生成物结构，而不是长期依赖；更稳妥的做法是以 Figma 变量为“设计真源”，按本文第三节的对应关系人工落地主题代码。

生成物的代码形态

Sync 生成的组件定制最终会落入 theme.components 的 styleOverrides 中。以一个定制过的 Switch 为例，将生成主题接入代码库的完整写法如下（来自 Sync 文档）：

import { createTheme, ThemeProvider } from '@mui/material/styles';

const theme = createTheme({
  cssVariables: true,
  shape: {
    borderRadiusRound: 999,
  },
  components: {
    MuiSwitch: {
      styleOverrides: {
        root: {
          '&.MuiSwitch-sizeMedium:has(.MuiSwitch-colorPrimary)': {
            '&:has(.Mui-checked):not(:has(.Mui-disabled)):not(:has(.Mui-focusVisible))':
              {
                width: '40px',
                height: '21px',
                padding: '0',
                '& .MuiSwitch-switchBase': {
                  transform: 'translateX(19px) translateY(2px)',
                  padding: '0',
                  '& .MuiSwitch-thumb': {
                    width: '17px',
                    height: '17px',
                    background: '#FAFAFA',
                  },
                  '& + .MuiSwitch-track': {
                    width: '38px',
                    height: '21px',
                    background: 'var(--mui-palette-success-light)',
                    borderRadius: 'var(--mui-shape-borderRadiusRound)',
                    opacity: '1',
                  },
                },
              },
          },
        },
      },
    },
  },
});

export default function MyApp(props) {
  const { Component, pageProps } = props;

  return (
    <ThemeProvider theme={theme}>
      <Component {...pageProps} />
    </ThemeProvider>
  );
}

从这份生成代码可以读出三个关键实现细节：

1. cssVariables: true 是主题令牌生效的前提：生成代码中大量出现 var(--mui-palette-success-light) 这类 CSS 变量引用，只有开启 CSS 变量模式，Material UI 才会把 palette、shape 等令牌输出为 --mui-* 变量，与设计端的令牌一一对应；
2. 选择器精确锚定到“特定变体”：&.MuiSwitch-sizeMedium:has(.MuiSwitch-colorPrimary) 表示该定制只对 size="medium" 且 color="primary" 的 Switch 生效，样式不会外溢到其他变体；
3. 状态由 :has() 选择器表达：:has(.Mui-checked) 等结构用于从父元素（root）向下匹配子层级的状态类。Sync 文档特别说明：has() 选择器如今已被所有现代浏览器支持，可以放心用于主题样式——这也解释了为什么设计端能基于“选中某个 Figma 变体”精确还原为代码端的条件样式。

六、使用新版设计套件的三种方式

官方在更新设计套件时一般不发布破坏性变更，而是以“新增内容”的方式迭代。当某个组件被更新、需要替换项目中已有引用时，文档给出了三个选项：

1. 库替换（Figma library swap）：把新版设计套件作为一个 library 加入，利用 Figma 的库替换功能批量替换——前提是新旧两个库中组件命名一致；
2. 观察并手动重放（多项目场景的推荐做法）：先观察新版组件的改动，再把同样的修改重新应用到现有项目；需要批量更新多个项目时，这种方式最可控；
3. 复制-重名-重链接令牌：把新组件复制进现有项目，先临时改个不同名字，再把令牌（tokens）重新链接到新组件上。配合 Select Similar 类插件，整个过程预计不超过五分钟，之后即可删除旧组件并改回新组件的名字。

选型建议：单项目、改动集中时用选项 1 或 3；多项目、需要审计每个改动时用选项 2。

七、反馈渠道与生态集成

• 反馈与缺陷报告：设计套件的问题与功能建议统一在官方 mui-design-kits 仓库的 Discussions 中收集（Figma 文档的反馈章节 与 Sync 文档 均指向同一入口），这是跟踪套件能力演进的可靠渠道。
• Anima 集成：可在 Figma 内通过 Anima 插件（或 VS Code 扩展）将 Figma 设计转换为 Material UI 代码，插件会把设计中的组件自动匹配到最相关的代码 API，目标是产出干净、可复用、可直接投产的代码。
• Quest 集成：Quest 与该设计套件有原生集成，使用其 Figma 插件可把基于该套件绘制的组件转换为 Material UI 代码，官方称生成结果达到生产可用级别。

小结

Material UI for Figma 的价值链路可以概括为：Figma 本地变量/本地样式 ↔ Material UI 主题令牌与 styleOverrides 的结构化同构。免费版足以体验全部组件形态，完整版（Figma 变量支持）才具备完整的设计令牌定制能力；而 Code sync（Sync 插件）展示了“设计端令牌导出为主题代码”的完整闭环——尽管该插件开发已暂停，其生成代码的结构（cssVariables + 变体级 styleOverrides + :has() 状态选择器）依然是理解“Figma 令牌如何映射为 Material UI 主题”的最佳参照。对于需要长期维护的设计体系，建议以完整版设计套件的变量结构为设计真源，按本文的映射关系将定制人工落地到 createTheme，并配合 Theming 文档 维护代码端主题。