USWDS项目中使用自定义字体时的配置问题解析

在使用USWDS（美国Web设计系统）进行前端开发时，配置自定义字体是一个常见需求。本文将深入分析一个典型配置错误案例，并提供完整的解决方案。

问题现象

开发者在尝试配置Roboto自定义字体时，遇到了Sass模块加载冲突的错误提示："This module was already loaded, so it can't be configured using 'with'"。这个错误通常发生在Sass模块被多次加载且配置冲突的情况下。

错误原因分析

1. 错误的变量名使用：原配置中使用了$theme-font-roboto-custom-src变量，而USWDS实际支持的变量名应为$theme-font-sans-custom-src。

2. 字体路径配置问题：虽然修改变量名解决了模块加载错误，但随后出现了字体路径问题。USWDS期望字体文件位于特定目录结构中。

正确配置方案

以下是经过验证的正确配置方式：

@use "uswds-core" with (
  $theme-show-compile-warnings: false,
  $theme-show-notifications: false,
  $theme-font-sans-custom-src: (
    dir: "roboto",
    roman: (
      100: "roboto-latin-100-normal",
      300: "roboto-latin-300-normal",
      400: "roboto-latin-400-normal",
      500: "roboto-latin-500-normal",
      700: "roboto-latin-700-normal",
      900: "roboto-latin-900-normal"
    ),
    italic: (
      100: "roboto-latin-100-italic",
      300: "roboto-latin-300-italic",
      400: "roboto-latin-400-italic",
      500: "roboto-latin-500-italic",
      700: "roboto-latin-700-italic",
      900: "roboto-latin-900-italic"
    )
  ),
  $theme-typeface-tokens: (
    "roboto": (
      "display-name": "Roboto",
      "cap-height": 364px,
      "stack": "sans-serif"
    )
  ),
  $theme-font-type-sans: "roboto"
);

字体文件管理最佳实践

1. 独立字体目录：建议创建专门的字体目录，而非直接引用node_modules中的文件。

2. 目录结构示例：

   /fonts
     /public
       /roboto
         roboto-latin-100-normal.woff2
         roboto-latin-300-normal.woff2
         ...
     /source
       /roboto
         (字体源文件)
   

3. 构建流程集成：在构建过程中自动复制字体文件到目标目录，保持开发环境的整洁。

Angular项目特殊处理

对于使用Angular构建工具的项目，需要在angular.json中正确配置：

{
  "assets": [
    {
      "glob": "**/*",
      "input": "node_modules/@uswds/uswds/dist",
      "output": "/assets",
      "ignore": ["**/*.css", "**/*.scss"]
    },
    {
      "glob": "**/*",
      "input": "node_modules/@fontsource/roboto",
      "output": "/assets/fonts/roboto"
    }
  ]
}

总结

配置USWDS自定义字体时，关键点在于：

1. 使用正确的变量名$theme-font-sans-custom-src
2. 确保字体文件路径配置正确
3. 根据项目构建工具调整字体加载策略
4. 保持字体目录结构清晰

遵循这些原则，可以避免常见的配置错误，实现自定义字体的顺利集成。