Style Dictionary 中变量覆盖时修饰符未移除的问题分析

问题背景

在 Style Dictionary 项目中，当开发者使用多主题配置时，会遇到一个关于变量覆盖的修饰符保留问题。具体表现为：当一个带有修饰符的变量被另一个不带修饰符的变量覆盖时，原始变量的修饰符信息会被错误地保留下来。

问题复现

假设我们有以下两个主题配置：

基础主题配置：

{
  "test": {
    "value": "#ffffff",
    "type": "color",
    "$extensions": {
      "studio.tokens": {
        "modify": {
          "type": "darken",
          "value": ".25",
          "space": "srgb"
        }
      }
    }
  }
}

覆盖主题配置：

{
  "test": {
    "value": "#ff0000",
    "type": "color"
  }
}

按照预期，覆盖后的结果应该是：

{
  "test": {
    "value": "#ff0000",
    "type": "color"
  }
}

但实际得到的结果却是：

{
  "test": {
    "value": "#ff0000",
    "type": "color",
    "$extensions": {
      "studio.tokens": {
        "modify": {
          "type": "darken",
          "value": ".25",
          "space": "srgb"
        }
      }
    }
  }
}

技术分析

这个问题源于 Style Dictionary 的 deepExtend.js 工具函数在处理对象深度合并时的逻辑缺陷。当前的实现没有考虑到当覆盖一个带有扩展属性的对象时，如果新对象中没有相应的扩展属性，应该完全移除这些扩展属性。

在主题系统设计中，这种覆盖行为通常意味着完全替换原有配置，包括其所有修饰符和扩展属性。保留这些修饰符可能会导致意外的样式计算结果，特别是当这些修饰符会改变颜色值或其他可计算属性时。

影响范围

这个问题主要影响以下场景：

1. 多主题配置系统
2. 需要覆盖基础变量配置的情况
3. 使用了修饰符（如颜色调整、尺寸缩放等）的变量

解决方案建议

对于 Style Dictionary 团队，建议修改 deepExtend.js 中的合并逻辑，使其能够：

1. 检测到新对象中缺少某些扩展属性
2. 在这种情况下完全移除原有对象的扩展属性

对于开发者，在问题修复前可以采取以下临时解决方案：

1. 显式地在覆盖配置中设置 $extensions: null
2. 使用后处理脚本来清理不需要的修饰符
3. 考虑升级到 Style Dictionary v4（虽然目前仍处于开发阶段）

版本兼容性说明

需要注意的是，这个问题在 Style Dictionary v3 中存在，而 v4 版本正在开发中。虽然 v4 版本已经解决了许多 v3 的问题，但其 API 尚未完全稳定。团队预计在 6 月发布正式版 v4，届时将提供更稳定的解决方案。

总结

变量覆盖时修饰符未移除的问题是 Style Dictionary 主题系统中一个需要注意的细节问题。理解这个问题的本质有助于开发者在多主题配置时做出更合理的架构设计。对于需要立即解决此问题的团队，可以考虑上述临时解决方案，同时关注 Style Dictionary 官方对 v4 版本的更新。