Style Dictionary 多条件/多模式设计令牌的实现方案

设计令牌中的多值需求

在现代设计系统中，设计令牌(Design Token)经常需要支持多种条件或模式下的不同取值。常见场景包括：

1. 暗黑/明亮模式：同一令牌在不同主题下需要返回不同颜色值
2. 响应式设计：同一间距令牌在不同断点下需要不同尺寸
3. 多平台适配：同一组件在不同平台(iOS/Android/Web)需要不同样式表现

传统实现方案及其局限

传统上，开发者会为每种模式创建单独的文件，例如：

• colors.light.json
• colors.dark.json
• spacing.mobile.json
• spacing.desktop.json

这种方法存在明显问题：

1. 维护成本高：每个组件需要维护多个文件
2. 扩展性差：当增加新维度(如新增平台)时，文件数量呈指数增长
3. 工作流复杂：需要手动管理大量文件间的引用关系

技术挑战分析

在Style Dictionary中实现单文件多值令牌面临的核心技术挑战：

1. 转换器(Transformer)限制：默认只处理value属性，忽略其他自定义属性
2. 引用解析问题：多值令牌如何正确处理对其他令牌的引用
3. 输出格式化：如何将多值令牌正确输出为CSS变量和媒体查询

可行的解决方案

方案一：扩展属性模式

{
  "token": {
    "value": "12px",
    "breakpoints": {
      "mobile": "14px",
      "tablet": "16px"
    }
  }
}

优点：

• 结构清晰直观
• 易于理解和维护

缺点：

• 需要自定义格式化器
• 无法自动转换扩展属性值

方案二：令牌分组命名法

{
  "token@#0": {
    "value": "{base.size.16}",
    "mode": "light"
  },
  "token@#1": {
    "value": "{base.size.24}",
    "mode": "dark"
  }
}

实现要点：

1. 使用特殊命名约定区分不同模式
2. 在格式化器中处理命名转换
3. 按模式分组输出CSS规则

优点：

• 所有值都能通过转换器处理
• 保持标准令牌结构

缺点：

• 需要预处理令牌结构
• 引用解析较为复杂

方案三：元数据扩展法

{
  "token": {
    "value": "<themed>",
    "$extensions": {
      "themes": {
        "light": "#ffffff",
        "dark": "#000000"
      }
    }
  }
}

实现机制：

1. 使用$extensions存储多模式值
2. 构建时展开为多个虚拟令牌
3. 分别处理每个模式值

优点：

• 符合DTCG规范
• 保持令牌结构整洁

缺点：

• 无法直接引用多值令牌
• 需要复杂预处理逻辑

性能与架构考量

在评估方案时，需要考虑：

1. 输出文件体积：合并所有模式到单一文件会增加未使用CSS
2. 运行时性能：浏览器需要解析更多CSS规则
3. 维护成本：复杂方案会增加长期维护难度

推荐架构：

1. 基础原始令牌(不受主题影响)
2. 语义层令牌(主题相关)
3. 组件令牌(引用语义层)

最佳实践建议

1. 简单场景：使用扩展属性+自定义格式化器
2. 复杂主题系统：采用多文件+多Style Dictionary实例
3. 平衡方案：元数据扩展法结合预处理脚本

对于GitHub等大型设计系统，推荐采用分层架构，将主题相关性与组件解耦，既能保持灵活性，又能控制复杂度。

未来发展方向

设计令牌社区正在积极讨论主题化标准，未来可能会：

1. 标准化多值令牌语法
2. 提供内置主题支持
3. 优化转换器处理流程

开发者应关注相关规范进展，同时根据当前项目需求选择最适合的过渡方案。