Summary

Added a theme setting for including custom breakpoints to the utility classes.

Being able to add a custom breakpoint to the utilities is useful for integrating USWDS with existing frameworks or other design requirements. Custom breakpoints will generate with the default system breakpoints.

Breaking change

This is not a breaking change.

Related issue

Closes #5984

Problem statement

As a designer or developer on projects that have existing designs, I would like to be able to add existing breakpoints to the generated USWDS utilities. Currently, the only breakpoints generating with the utilities are those that are available in the internal system settings (which are understandably not modifiable).

The consequence of not being able to add custom breakpoints is the fracturing of site stylesheets causing additional maintenance as well as the possibility of needing to fork parts of the USWDS system in order to handle those custom breakpoints. Being able to programmatically add custom breakpoints also provides a safer approach versus hacking the $system-properties directly.

Solution

This PR will add a new theme setting $theme-utility-breakpoints-custom which is a map to pass additional breakpoint keys and values.

This approach does not modify the default breakpoints. Instead, it simply integrates any custom breakpoints with those system properties in order to generate utility classes.

A possible gotcha is that it appears the setting will require that the key value be in rem because of the at-media mixin. This could be mitigated by adding clear documentation for setting usage though.

The new theme setting can be used alongside the existing breakpoint setting like this:

@use "uswds-core" with (
  $theme-namespace: (
    'utility': (
      namespace: 'u-',
      output: false,
    ),
  ),
  $theme-utility-breakpoints: (
    "card": false,
    "card-lg": false,
    "mobile": true,
    "mobile-lg": false,
    "tablet": true,
    "tablet-lg": false,
    "desktop": false,
    "desktop-lg": true,
    "widescreen": false
  ),
  $theme-utility-breakpoints-custom: (
    "medium-screen": 48rem,
  )
);

Which will generate additional utility breakpoint classes. For example:

@media all and (min-width: 48em) {
  .medium-screen\:vads-u-border-top--10px {
    border-top: 10px solid;
  }
  .medium-screen\:vads-u-border-right--10px {
    border-right: 10px solid;
  }
  .medium-screen\:vads-u-border-bottom--10px {
    border-bottom: 10px solid;
  }
  .medium-screen\:vads-u-border-left--10px {
    border-left: 10px solid;
  }

  ....
}

Testing and review

I tested this locally with the VA design system CSS-Library utilities generator and inspecting the generated utility classes.