如何将Figma Tokens映射到Compose Material Tokens及获取映射文件

一、映射文件的获取途径 #

目前官方没有提供现成的映射文件模板，你需要结合Compose Material Tokens的结构和Figma Tokens的定义自行构建。Relay Android插件要求的映射文件本质是JSON配置，核心作用是关联Figma侧的Token名称与Compose主题中对应的Token键值。

二、手动编写映射文件的可行性及操作步骤 #

完全可以手动编写，具体步骤如下：

1. 梳理两边Token结构
   • 先整理Compose Material 3的核心Token分类：比如colorScheme下的primary、onPrimary，typography下的headlineLarge、bodyMedium，shapes下的large、medium等
   • 对应列出Figma Tokens的命名规则：比如Figma中可能命名为color-primary、text-headline-large、shape-corner-large等
2. 编写JSON映射文件
   映射文件采用键值对结构，键为Figma Token的完整路径，值为Compose主题中对应的Token路径。示例如下：

   {
     "color.primary": "colorScheme.primary",
     "color.onPrimary": "colorScheme.onPrimary",
     "typography.headlineLarge": "typography.headlineLarge",
     "shape.corner.large": "shapes.large"
   }
   

   注意：路径格式需严格匹配Relay要求，Compose侧路径要对应Theme类中colorScheme、typography、shapes的属性层级。
3. 在Relay中配置映射文件
   打开Android Studio的Relay插件设置，找到「Theme Mapping」选项，导入你编写的JSON文件即可生效。

三、可用工具推荐 #

虽然Style Dictionary无法直接输出Relay所需格式，但可以通过自定义Transformer适配：

• 自定义Style Dictionary Transformer：在Style Dictionary的配置文件中添加自定义输出格式，将Material Style JSON转换为Relay要求的键值对结构。示例配置片段：

  module.exports = {
    platforms: {
      relay: {
        transformGroup: 'js',
        buildPath: 'src/main/res/relay/',
        files: [{
          destination: 'theme-mapping.json',
          format: function({ dictionary }) {
            const mapping = {};
            dictionary.allTokens.forEach(token => {
              // 自定义Figma Token到Compose Token的路径转换逻辑
              const composePath = token.path.join('.').replace('figma-', '');
              mapping[token.path.join('.')] = composePath;
            });
            return JSON.stringify(mapping, null, 2);
          }
        }]
      }
    }
  };
  

• Figma插件辅助：使用「Token Studio for Figma」（原Figma Tokens插件）的导出功能，先将Figma Tokens导出为符合Material规范的JSON，再通过上述自定义Transformer转换为Relay格式。

四、验证与调试 #

• 导入映射文件后，在Relay预览中检查组件样式是否正确应用Compose主题Token
• 若出现不匹配，检查映射文件中的路径是否完全对应两边的Token名称，重点核对大小写和层级结构

内容的提问来源于stack exchange，提问作者Василий Зайцев