Style Dictionary 中 SCSS 映射格式的变量前缀问题解析

在 Style Dictionary 4.0 版本中，开发者在使用 scss/map-deep 格式时可能会遇到一个关于变量前缀的常见问题。本文将深入分析这个问题，并提供解决方案。

问题现象

当开发者同时配置 CSS 变量和 SCSS 映射格式时，会发现 scss/map-deep 格式的输出存在不一致性。具体表现为：

1. 在 SCSS 变量声明部分，前缀正确应用
2. 但在 SCSS 映射(map)内部的值引用部分，前缀却丢失了

例如，配置了 $common- 前缀后，期望映射中的引用应该是 $common-duration-fast，但实际输出却是 $duration-fast。

技术分析

这个问题的根源在于 scss/map-deep 格式的内部实现机制：

1. 格式处理器会接收完整的字典数据
2. 但格式化选项(包括前缀配置)没有被传递到映射构建过程中
3. 映射构建函数 processJsonNode 直接使用了原始变量名，没有应用前缀

解决方案

临时解决方案

对于需要立即解决此问题的开发者，可以使用平台级别的 prefix 配置项：

{
  platforms: {
    scss: {
      prefix: `common`,
      // 其他配置...
    }
  }
}

这种方法会将前缀直接应用到所有令牌名称上，确保所有引用都包含前缀。

长期解决方案

Style Dictionary 团队已经确认这是一个 bug，并计划在 4.0 版本中修复。修复后，formatting.prefix 选项将能够正确应用于映射内部的变量引用。

最佳实践建议

1. 对于 SCSS 输出，优先使用平台级别的 prefix 配置
2. 保持配置一致性，避免在多个地方设置前缀
3. 注意前缀的命名规范，确保符合 SCSS 变量命名规则
4. 对于复杂项目，考虑使用转换器(transformer)统一处理命名问题

总结

理解 Style Dictionary 中不同格式对前缀配置的处理方式差异，有助于开发者更好地组织和管理设计令牌。虽然当前存在一些不一致性，但通过合理的配置和即将到来的修复，开发者可以构建出更加一致和可维护的设计系统输出。

对于需要更精细控制的情况，开发者也可以考虑创建自定义格式或扩展现有格式，以满足特定项目的需求。