Style Dictionary 深度合并令牌文件时的冲突问题与解决方案

问题背景

在使用 Style Dictionary 处理设计令牌时，当多个令牌文件具有相同的内部结构但不同值时，会出现令牌被意外覆盖的问题。这种情况常见于组件级别的设计令牌，特别是当为不同断点（breakpoint）定义例外值时。

典型场景分析

假设我们有一个轮播组件（carousel），为不同断点（small 和 medium）定义了不同的间距值：

small断点文件：

{
  "component": {
    "surface": {
      "carousel": {
        "basic": {
          "self": {
            "gap": {
              "value": "{spacing.3xs}",
              "type": "spacing"
            }
          }
        }
      }
    }
  }
}

medium断点文件：

{
  "component": {
    "surface": {
      "carousel": {
        "basic": {
          "self": {
            "gap": {
              "value": "{spacing.4xs}",
              "type": "spacing"
            }
          }
        }
      }
    }
  }
}

当 Style Dictionary 处理这两个文件时，由于它们具有完全相同的路径结构，后处理的文件会覆盖前一个文件的值，导致最终只保留一个断点的值。

解决方案探讨

1. 主题维度方法

将断点视为"主题"维度来处理，这是 Style Dictionary 推荐的解决方案：

• 将不同断点（small、medium等）视为主题变体
• 全局/基础令牌在所有变体中共享
• 断点特定的令牌只在对应变体中加载

这种方法不仅解决了当前问题，还为未来可能的其他主题维度（如暗黑模式、高对比度等）提供了扩展性。

2. 并行处理与合并方案

另一种方法是分别处理每个断点，然后在内存中合并结果：

const cfgs = ['small', 'medium'].map(breakpoint => ({
  source: [`tokens/**/*-${breakpoint}.json`],
  platforms: {
    css: {
      transformGroup: 'css',
      files: [{
        format: 'css/variables',
        destination: `output/css/${breakpoint}.css`
      }]
    }
  }
}));

async function runSD(cfg) {
  const sd = new StyleDictionary(cfg);
  const [file] = await sd.formatPlatform('css');
  return [file.destination, file.output];
}

const outputs = Object.fromEntries(await Promise.all(cfgs.map(runSD)));

这种方法提供了更大的灵活性，可以完全控制输出合并的过程。

3. 元数据标记方案（建议方案）

在令牌输出中添加冲突元数据，而不是简单地覆盖：

{
  "value": "8px",
  "type": "dimension",
  "filePath": "tokens/.../self-small.json",
  "collision": [{
    "filePath": "tokens/.../self-medium.json",
    "original": "{ value: '{spacing.4xs}', type: 'spacing' }"
  }]
}

这种方法保留了所有原始信息，让开发者可以清楚地看到哪些值被覆盖，便于后续处理。

最佳实践建议

1. 清晰的命名约定：为不同断点的令牌文件使用明确的命名模式（如*-small.json、*-medium.json）

2. 分离构建流程：考虑为不同断点创建独立的构建流程，避免并行处理导致的不可预测结果

3. 主题优先设计：从一开始就采用主题维度方法设计令牌结构，为未来的扩展性做好准备

4. 文档记录：为团队记录令牌命名和处理规则，避免未来出现类似问题

总结

处理具有相同结构但不同值的令牌文件时，Style Dictionary 的默认行为可能会导致意外的值覆盖。通过采用主题维度方法、并行处理合并或元数据标记等方案，可以有效地解决这一问题。选择哪种方案取决于项目的具体需求和未来的扩展计划。