Style Dictionary多品牌主题构建中的令牌引用问题解析

问题背景

在使用Style Dictionary构建多品牌设计系统时，开发者经常会遇到令牌引用错误的问题。典型表现为构建过程中出现"Some token references could not be found"的错误提示，导致构建失败。这种情况通常发生在尝试为不同品牌和主题创建独立但又有共享引用的设计令牌体系时。

核心问题分析

错误的令牌引用结构

在示例中，开发者尝试为两个品牌(brand-a和brand-b)创建基础令牌，然后为每个品牌创建自定义主题(theme-a和theme-b)。问题出在主题文件中引用品牌令牌的方式：

"primaryDivider": {
  "$value": "{brand-a.brand-a/palette/light/divider}"
}

这种引用结构存在几个关键问题：

1. 命名空间冲突：同时使用了点表示法(brand-a.)和斜杠表示法(brand-a/palette/light/divider)混合的引用方式
2. 跨品牌引用：主题文件试图引用可能不存在的品牌令牌
3. 构建隔离：每个Style Dictionary实例只加载特定品牌的令牌，无法访问其他品牌的令牌

构建流程缺陷

构建脚本为每个品牌创建独立的Style Dictionary实例：

['brand-a', 'brand-b'].map(function (brand) {
  ['web', 'css'].map(function (platform) {
    const sd = new StyleDictionary(getStyleDictionaryConfig(brand, platform));
    sd.buildPlatform(platform);
  });
});

这种实现方式导致：

• 构建brand-a时，brand-b的令牌不可见
• 构建brand-b时，brand-a的令牌不可见
• 主题文件中的跨品牌引用自然就会失败

解决方案

正确的令牌引用模式

1. 统一引用格式：选择点表示法或斜杠表示法中的一种，不要混用
2. 分层引用结构：建立清晰的令牌层级关系，例如：

   "primaryDivider": {
     "$value": "{palette.light.divider}"
   }
   

改进的构建策略

1. 集中式构建：创建一个包含所有品牌令牌的Style Dictionary实例
2. 使用别名系统：为不同品牌的相同概念创建别名，而不是直接引用
3. 主题切换机制：通过变量或环境变量控制当前激活的主题

代码结构优化建议

// 改进后的构建配置
function getStyleDictionaryConfig(theme) {
  return {
    include: [`tokens/core/**/*.json`],
    source: [
      `tokens/brands/${theme.brand}/**/*.json`,
      `tokens/themes/${theme.name}/**/*.json`
    ],
    // ...其他配置
  };
}

最佳实践

1. 核心令牌分离：将与品牌无关的基础设计令牌放在核心目录中
2. 品牌特定覆盖：品牌目录只包含需要覆盖核心值的令牌
3. 主题作为扩展：主题只修改品牌令牌的值，不改变令牌结构
4. 引用限制：避免跨品牌引用，使用抽象层隔离品牌差异

总结

在Style Dictionary中实现多品牌多主题系统时，关键在于建立清晰的令牌层级结构和合理的构建流程。令牌引用应当遵循一致的模式，避免跨品牌直接引用。通过分层抽象和适当的构建策略，可以创建灵活且可维护的多品牌设计系统。记住，主题应当只改变令牌的值，而不改变令牌的结构和引用关系，这样才能确保系统的可扩展性和一致性。