Summary

Updates sass map pattern to allow users to only define overrides while keeping defaults for the other values

Breaking change

This is potentially a breaking change.

Previously, if a user left an item out of a map, it would be set to false and thus deactivating it. After this update, an item left out of the map will maintain its default value.

If users deactivated certain settings by not declaring them, this update will cause those variables to be activated. Note that we did not recommend that pattern, but it's possible for users to have done so on their own

Related issue

Closes #5215

Related pull requests

Update sass map instructions on utility pages: uswds/uswds-site#2077

Problem statement

Currently, if you choose to update a USWDS setting within a sass map, you must define each setting within the map even if you are keeping the default values for the other.

Solution

We can use map-merge with a default values map to only replace updated settings keys without needing to redefine default values.

This solution

• Doesn't break existing sass map settings users have previously set
• BUT if users left an element out of the map, (effectively disabling it) this PR would re-enable the default setting.

This PR updates $theme-[map-name]s to $theme-[map-name]-complete wherever the setting is called.

This allows users still use existing setting names, such as $theme-utility-breakpoints, to update which breakpoints are active, while using the -complete map to restore defaults to undefined elements.

Note: I considered naming the complete maps as -defaults but I believe this makes less contextual sense wherever the maps are being called.

Updated maps

• $theme-namespace
• $theme-utility-breakpoints
• $[utility-module]-settings

Ignored maps

These maps were either, empty, set to false by default, or only had example values. In all three settings, we would want the users override to be the only value, which is currently how they are set up.

• $theme-fontface-tokens
• $theme-font-[family]-src
• $[utility-module]-manual-calues

Testing and review

1. Checkout this test uswds-sandbox repo
2. The test repo should already have this branch installed as it's USWDS package
3. Run npm run start on the test repo
4. View each test page and review instructions
5. Visit _uswds-theme.scss and expirament enabling/disabling different settings
6. Revisit index page in browser and view the changes
7. Confirm that
   • : Default breakpoints are working as expected
   • : Updating one breakpoint, doesn't deactivate the others
   • : Updated breakpoints work as expected
8. Look over all maps listed on the settings page
9. Inspect their default values in the USWDS settings and verify there aren't any additional updates to make

These tests are simple and mostly just enable different background colors as a quick visual feedback. Feel free to experiment with other utility settings to verify the new pattern is working!

Default maps for reference:

Breakpoints

@use "uswds-core" with (
  $theme-utility-breakpoints: (
      "card": false,
      "card-lg": false,
      "mobile": false,
      "mobile-lg": true,
      "tablet": true,
      "tablet-lg": false,
      "desktop": true,
      "desktop-lg": false,
      "widescreen": false,
    )
);

Namespace

$theme-namespace: (
  "grid": (
    namespace: "grid-",
    output: true
  ),
  "utility": (
    namespace: "u-",
    output: false,
  ),
),

Before opening this PR, make sure you’ve done whichever of these applies to you:

• Confirm that this code follows the 18F Front End Coding Style Guide and Accessibility Guide.
• Run git pull origin [base branch] to pull in the most recent updates from your base and check for merge conflicts. (Often, the base branch is develop).
• Run npm run prettier:scss to format any Sass updates.