Style Dictionary 中多转换器与相同令牌类型冲突的解决方案

在 Style Dictionary 项目中，设计系统开发者经常会遇到一个典型问题：当多个转换器(transformer)需要处理相同类型的令牌(token)时，系统默认行为会导致冲突。本文将深入分析这一问题的本质，并提供专业级的解决方案。

问题本质分析

在 Style Dictionary 中，令牌类型(token type)是转换器匹配和处理的基础。当多个内置转换器（如 size/pxToRem 和 size/px）都针对相同的 dimension 类型时，系统会按照转换器在组中的顺序执行，但最终只会保留最后一个转换器的输出结果。

这种设计源于一个基本假设：同一类型的令牌在特定平台上应该保持一致的输出格式。然而，在实际设计系统中，这种假设往往不成立。例如：

• 字体大小可能需要同时输出 rem 和 px 两种单位
• 间距可能需要保留 px 单位
• 行高可能需要使用无单位值或 em 单位

专业解决方案

方案一：自定义转换器过滤条件

通过注册自定义转换器并覆盖其过滤条件，可以精确控制哪些令牌应该应用哪种转换：

const pxToRemBuiltin = StyleDictionary.hooks.transforms['size/pxToRem'];

StyleDictionary.registerTransform({
  ...pxToRemBuiltin,
  filter: (token) => token.type === 'dimension' && token.path.includes('font-size'),
  name: 'font-size/rem',
});

这种方法保持了内置转换器的核心逻辑，只修改了其匹配规则。

方案二：令牌元数据扩展

更专业的做法是在令牌定义中加入元数据，通过扩展令牌结构来实现精确控制：

{
  "font": {
    "size": {
      "$type": "dimension",
      "$unit": "rem",
      "100": {
        "$value": 100
      }
    }
  }
}

然后创建自定义转换器根据 $unit 元数据决定转换方式：

StyleDictionary.registerTransform({
  type: 'value',
  name: 'custom/size',
  matcher: (token) => token.type === 'dimension',
  transformer: (token) => {
    if (token.$unit === 'rem') {
      return `${token.value/16}rem`;
    }
    return `${token.value}px`;
  }
});

架构设计建议

对于大型设计系统，建议采用以下专业架构：

1. 令牌分类体系：建立清晰的令牌分类命名规范，如：

   • dimension/spacing
   • dimension/font-size
   • dimension/line-height

2. 转换器分层：

   • 基础转换器：处理原始值到标准格式
   • 平台专用转换器：处理平台特定需求
   • 复合转换器：组合多个转换逻辑

3. 转换器注册策略：

   function registerTransformWithFilter(transformName, customFilter) {
     const builtin = StyleDictionary.hooks.transforms[transformName];
     StyleDictionary.registerTransform({
       ...builtin,
       filter: customFilter,
       name: `custom/${transformName}`
     });
   }
   

最佳实践

1. 避免直接修改内置转换器：始终通过注册新转换器的方式扩展功能

2. 保持转换器纯净：每个转换器应只负责单一职责

3. 文档化转换规则：为自定义转换逻辑编写详细文档

4. 单元测试：为关键转换逻辑编写测试用例

通过以上专业方案，开发者可以灵活应对设计系统中复杂的令牌转换需求，同时保持代码的可维护性和扩展性。