USWDS 3.x 自定义变量配置的正确方式解析

背景介绍

USWDS (U.S. Web Design System) 是美国政府设计系统，为政府网站提供一致的设计语言和前端组件。在从 USWDS 2.x 迁移到 3.x 版本时，开发者可能会遇到自定义变量配置的问题。

问题现象

在迁移过程中，开发者尝试在 _uswds-theme.scss 文件中定义一个新的自定义变量 $theme-unit-60 时，遇到了错误提示："This module was already loaded, so it can't be configured using 'with'"。

问题分析

这个错误的核心原因是 USWDS 3.x 采用了 Sass 模块系统的新特性，模块一旦被加载就不能再次配置。具体来说：

1. USWDS 3.x 使用 @use 规则加载核心模块
2. 当开发者尝试在主题文件中重新配置模块时，模块可能已经被其他文件加载过
3. Sass 模块系统不允许对已加载模块进行重复配置

解决方案

方案一：使用现有间距单位

USWDS 已经提供了一套完整的间距单位系统，开发者应优先考虑使用系统内置的单位。例如：

• 间距单位8对应64px，接近自定义的60px
• 这样可以保持与设计系统的一致性

方案二：在自定义样式文件中定义变量

正确的做法是将自定义变量移动到单独的自定义样式文件中：

1. 创建 _uswds-theme-custom-styles.scss 文件
2. 在该文件中定义自定义变量
3. 在主样式文件中导入这个自定义文件

// _uswds-theme-custom-styles.scss
$custom-unit-60: 3.75rem;

方案三：使用 px-to-rem() 函数

对于需要特殊尺寸的情况，可以直接使用 USWDS 提供的单位转换函数：

.element {
  margin: px-to-rem(60px);
}

最佳实践建议

1. 优先使用设计系统内置变量：保持与USWDS设计规范的一致性
2. 合理组织自定义样式：将自定义内容与主题配置分离
3. 了解Sass模块系统：掌握@use和@forward规则的区别和使用场景
4. 考虑提交功能请求：如果确实需要扩展设计系统的变量，可以向USWDS团队提交功能请求

总结

在USWDS 3.x中，自定义变量需要遵循Sass模块系统的规则。通过将自定义内容与主题配置分离，可以避免模块加载冲突的问题。开发者应当优先考虑使用系统内置的设计标记，只有在确实需要时才添加自定义变量，并且要遵循正确的文件组织和导入方式。

这种处理方式不仅解决了技术问题，也保持了代码的可维护性和与设计系统的一致性，是前端工程化实践的良好体现。