USWDS - Utilities: Custom breakpoints #6048

mahoneycm · 2024-09-05T18:49:46Z

Summary

Continuation of #5985. Thank you for your contribution @jamigibbs.

Added new $theme-utility-breakpoints-custom setting. This setting generates responsive variants of USWDS utility classes at custom breakpoints.

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 utilities alongside the default system breakpoints.

Sample implementation

To generate a custom breakpoint for your USWDS utilities, add custom breakpoint values to a Sass map for $theme-utility-breakpoints-custom in your USWDS settings configuration. Here is an example implementation:

@use "uswds-core" with (
  $theme-utility-breakpoints-custom: (
    "new-breakpoint": 800px
  )
);

Important

Custom breakpoints must be defined with px values.

Tip

Every breakpoint added to the system adds about 50kb to the compiled CSS. Be careful to only turn on the breakpoints you need for your project. You can turn off default USWDS breakpoints with the $theme-utility-breakpoints setting. More details about $theme-utility-breakpoints can be found on the Settings page.

Breaking change

This is not a breaking change.

Related issue

Closes #5984

Related pull requests

Continuation of #5985

Site documentation update →

Preview link

Preview link →

Problem statement

It is currently not possible for users to implement custom breakpoints and use them alongside our utility classes

Solution

Create new scss map for users to define their own breakpoints and build out utility classes with.

Major changes

Created $theme-utility-breakpoints-custom map for users to name and define their own breakpoints
Created px-to-user-em() sass function
Collect the breakpoints in system properties
Update _utility-builder.scss to take custom breakpoints
Update at-media mixin to create utility classes with custom breakpoints
At this time, breakpoints can only be set in px units.
Custom breakpoints follow the same em conversation methods as standard USWDS breakpoints
- If $theme-respect-user-font-size is true, breakpoints are converted to em
- If $theme-respect-user-font-size is false, breakpoints are output as px

Testing and review

Testing steps

Checkout feature branch
Visit settings-utilities.scss and add custom breakpoints with px and rem (or some other unit)
- Ex:
```
$theme-utility-breakpoints-custom (
  "bp-px": 64px;
  "bp-rem": 10rem;
)
```
Run npx gulp compileSass
Confirm the non px breakpoint triggers Warning message in the terminal.
View output USWDS css at dist/css/uswds.css.
Search for your custom breakpoint by name.
Confirm new media queries are built using values of your custom breakpoints.
Confirm value is correctly converted to em.
Confirm new utility classes are built using the name of your breakpoints.
Confirm non px breakpoints were not built.
Open _settings-typography and set $theme-respect-user-font-size to false !default
Recompile sass npx gulp compileSass
View output USWDS css at dist/css/uswds.css
Confirm breakpoints are now output as px.

Update responsive settings test

Turn on a responsive utility class that is disabled by default and confirm that the custom breakpoints are created for the new utility.

Visit _settings-utilities.scss
Update background-color-settings-complete change responsive: false to responsive: true
Compile sass npx gulp compileSass
View output USWDS css at dist/css/uswds.css
Find your custom breakpoint and confirm bg-(color) utility classes are created for your custom breakpoint

Testing checklist

Approve map merge method
Approve collecting custom breakpoints in extended system property
Confirm approach in the new px-to-user-em sass function is valid.
Confirm at-mixin and utility builder properly output breakpoints and utility classes
Confirm warning message appears when non px value is used.
Updated responsive settings respect new breakpoints.
No regressions updating standard breakpoints.

This reverts commit e6c7682.

…om breakpoints are included in breakpoints-complete map

…uilder and at-media to handle custom breakpoints

mahoneycm · 2024-09-16T21:07:14Z

Additional consideration: Custom breakpoints + layout grid

This work currently does not build Layout Grid utility classes for the new custom breakpoints, but it would be possible to update _usa-layout-grid.scss to include the custom breakpoints.

Is that something we want to provide to the users with this update? Alternatively, it could be an additional enhancement after this work is merged.

mahoneycm · 2024-09-18T16:25:19Z

@jamigibbs After some discussion, we've opted to only take custom breakpoints in px since it feels like a standard for breakpoints and a common language between designers and developers. We wanted to get your team's opinion on this approach! Do you think this is a valid decision? Are there substantial reasons we should also take in rem or any other units?

I'm unable to tag you as a reviewer for this work, but if you could test this PR to see if it works with your custom breakpoints the way you'd like, it'd be greatly appreciated! All feedback is welcome 👍

mahoneycm

A couple notes on my approach here

mahoneycm · 2024-09-18T16:43:42Z

packages/uswds-core/src/styles/functions/units/px-to-user-em.scss

+@function px-to-user-em($pixels) {
+  @if unit($pixels) != "px" {
+    @error 'This value must be in pixels';
+  }
+  $px-to-user-em: px-to-rem($pixels);
+  $px-to-user-em: rem-to-user-em($px-to-user-em);
+
+  @return $px-to-user-em;
+}


I opted not to re-invent the wheel and use functions we already had to convert pixels to rem.

Alternatively, we could use the following sass math conversion if we don't want to rely on the other functions:

@if unit($pixels) != "px" { @error 'This value must be in pixels'; } $px-to-user-em: (math.div($pixels, root.$root-font-size-equiv)) * 1em; $px-to-user-em: math.div(math.round($px-to-user-em * 100), 100);

mahoneycm · 2024-09-18T16:45:07Z

packages/uswds-core/src/styles/functions/units/rem-to-user-em.scss

+  @if unit($grid-in-rem) != "rem" {
+    @error 'This value must be in rem';
+  }


note: Added error to match other conversion functions

mahoneycm · 2024-09-18T16:47:06Z

packages/uswds-core/src/styles/mixins/helpers/at-media.scss

+$our-breakpoints: map-deep-get($system-properties, breakpoints, standard);
+$custom-breakpoints: map-deep-get($system-properties, breakpoints, extended);
+


note: Moved variable declaration out of mixin since they are used in both at-media and at-media-max

jamigibbs · 2024-09-18T20:07:46Z

@jamigibbs After some discussion, we've opted to only take custom breakpoints in px since it feels like a standard for breakpoints and a common language between designers and developers. We wanted to get your team's opinion on this approach! Do you think this is a valid decision? Are there substantial reasons we should also take in rem or any other units?

I'm unable to tag you as a reviewer for this work, but if you could test this PR to see if it works with your custom breakpoints the way you'd like, it'd be greatly appreciated! All feedback is welcome 👍

@mahoneycm Thanks Charlie! px will be fine for us. I originally called that out just for visibility but I don't see any reason why it needs to be anything other than px.

I also tested your branch locally with our implementation and it seems to be working great! The custom breakpoints were generating and an error message displayed if I tried to using something other than px.

…points

mejiaj

Thanks @mahoneycm. I've been able to successfully test following your instructions. I've created a branch on uswds-sandbox test-uswds-breakpoints-6048, so others can test as well. Links to that testing environment:

Branch: test-uswds-breakpoints-6048.
Draft PR: uswds/uswds-sandbox#153
Preview: Sandbox prose →

Confirming

New utils are generated for custom breakpoint
Breakpoint is available via at-media
Warning on passing non-px values
Additional utils are generated
Overriding root font size sets media queries with px

Non-pixel values

Confirming that passing non-px values give a warning.

Input

// _uswds-theme.scss
@use "uswds-core" with (
  $theme-utility-breakpoints-custom: (
    "desktop-custom-rem": 70rem // 1120px
  )
);

Output

Warning: Custom breakpoint `desktop-custom-rem` has the unit rem. Custom breakpoints must be set in px.
    ../../../@uswds/uswds/packages/uswds-core/src/styles/mixins/helpers/at-media.scss 35:7  at-media()
    ../../../../src/_styles/_uswds-theme-custom-styles.scss 11:1                            @forward
    ../../../../src/_styles/styles.scss 3:1

Additional utils

Warning

Adding responsive variants has an impact on CSS compile size.

Confirming that additional utilities are output.

Input

// _uswds-theme.scss
@use "uswds-core" with (
  $theme-utility-breakpoints-custom: (
    "desktop-custom": 1100px,
  ),
  $background-color-settings: (
    responsive: true,
  )
);

Output

/* styles.css */
@media all and (min-width: 68.75em) {
  .desktop-custom\:bg-transparent,
  .desktop-custom\:hover\:bg-transparent:hover {
    background-color: transparent;
  }
  .desktop-custom\:bg-black,
  .desktop-custom\:hover\:bg-black:hover {
    background-color: #000;
  }
  /* … */
}

Overriding root font size

Input

// _uswds-theme.scss
@use "uswds-core" with (
  $theme-utility-breakpoints-custom: (
    "desktop-custom": 1100px,
  ),
  $theme-respect-user-font-size: false,
  $theme-root-font-size: 20px,
);

Output

/* styles.css */
@media all and (min-width: 1100px) {
  /* … */
}

Output CSS size

Output CSS file size after adding a single custom breakpoint. This issue is compounded when we're adding responsive variants on top.

File	Before	After
styles.css	524KB	572KB

We should create an issue to support at-media without generating utils for performance.

amyleadem

Looking good @mahoneycm! (And thanks for your original work on this @jamigibbs!)

Important

Before I approve, I wanted to highlight that this PR does not generate custom responsive breakpoints for layout grid or icon-list-size classes. I have added additional details in the notes below.

Are we comfortable with this moving forward without these responsive classes?

Everything else is looking good!

Testing details

I tested in uswds-sandbox using the following config:

@use "uswds-core" with (
  $theme-show-compile-warnings: false,
  $theme-show-notifications: false,
  $theme-utility-breakpoints-custom: (
    "new-breakpoint": 800px
  ),
  $theme-utility-breakpoints: (
    widescreen: true,
  ),
  $left-settings: (
    responsive: true
  )
);

Confirm the $theme-utility-breakpoints-custom setting generates new style rules for each new pixel-based value in the map
- Note: There are some gaps in what $theme-utility-breakpoints-custom generates vs $theme-utility-breakpoints
  - Turning on new-breakpoint in $theme-utility-breakpoints-custom generates 898 new references to .new-breakpointin the CSS. Turning on widescreen in $theme-utility-breakpoints generates 1060 new references to .widescreen\:
  - After some digging, discovered that difference was that the custom breakpoint was not generated for:
    - usa-icon-list sizes - for example, it did not generate .new-breakpoint\:usa-icon-list—size-1, but did generate .widescreen\:usa-icon-list—size-1 (In total, there were 90 references for usa-icon-list--size generated for widescreen)
    - layout grid classes - For example, it did not generate .new-breakpoint\:grid-container but did generate .widescreen\:grid-container (In total, 72 grid references were generated for widescreen)
  - For reference, here is the difference in CSS size:
    - with default breakpoints: 524kb
    - with only a new custom breakpoint: 572kb
    - with only an additional standard breakpoint (widescreen): 587kb
Confirm there is an appropriate warning in the console when a non-px unit is added to the $theme-utility-breakpoints-custom setting map
- Note: I added a non-breaking suggestion below to add a bit more clarity to the warning message
Confirm that setting $theme-respect-user-font-size: false outputs new breakpoint in px
Confirm that setting $theme-respect-user-font-size: true outputs new breakpoint in em
Confirm conversion from px to em is accurate (eg, 800px outputs as 50em)
Confirm that turning on a responsive variant of a USWDS utility generates the custom breakpoint from $theme-utility-breakpoints-custom as well as the default breakpoints from $theme-utility-breakpoints (I tested $left-settings)
Confirm the code meets standards

packages/uswds-core/src/styles/mixins/helpers/at-media.scss

amyleadem · 2024-09-26T23:12:49Z

Update: I have opened PR #6083 as a candidate to add support for layout grid utility classes to this PR.

USWDS - Layout grid utility: Custom breakpoints

amyleadem · 2024-10-01T21:42:00Z

Update: I have merged in #6083 after team approval. This adds support for generating custom breakpoints for layout grid utilities.

Will work on finalizing my review of this PR now.

amyleadem

Looks good to me! I do have one suggestion to add detail to the warning message in the comment below, but I don't consider it to be a blocker

packages/uswds-core/src/styles/mixins/helpers/at-media.scss

Co-authored-by: Amy Leadem <93996430+amyleadem@users.noreply.github.com>

thisisdano

Nice feature. Thank you @jamigibbs and @mahoneycm!

jamigibbs and others added 10 commits July 19, 2024 11:36

add $theme-utility-breakpoints-custom setting

b40b9ab

run prettier

e6c7682

Revert "run prettier"

47a5d0a

This reverts commit e6c7682.

run prettier again and fix mapping error

5abc90c

Remove theme token from system-spacing tokens

0e59b9f

Merge all breakpoint maps into 'complete' map

fa93556

Restore utility breakpoint builder to simpler structure now that cust…

a03b062

…om breakpoints are included in breakpoints-complete map

Add error message to rem-to-user-em function

333a726

Move custom breakpoints from standard to extended; refactor utility b…

0ea2129

…uilder and at-media to handle custom breakpoints

Run prettier

5169607

mahoneycm marked this pull request as ready for review September 13, 2024 20:31

mahoneycm requested review from CTGM-Bixal, amyleadem, cathybaptista and mejiaj September 13, 2024 20:31

mahoneycm mentioned this pull request Sep 16, 2024

Cannot find any way to update preset breakpoint widths #4230

Closed

Create and implement px-to-user-em sass function

6354d4e

mahoneycm mentioned this pull request Sep 18, 2024

USWDS-Site - Documentation: Add $theme-utility-breakpoints-custom to settings table. uswds/uswds-site#2837

Merged

mahoneycm added 3 commits September 18, 2024 12:43

Add unit test and error message to px-to-user-em

eea0ec4

Remove period from warning valid value list

3c6e0fa

Remove unsuded settings at-rule from spacing tokens

4d3c318

mahoneycm commented Sep 18, 2024

View reviewed changes

mahoneycm mentioned this pull request Sep 18, 2024

USWDS-Site: Documentation updates for 3.9.0 uswds/uswds-site#2812

Merged

3 tasks

Merge branch 'develop' of github.com:uswds/uswds into cm-custom-break…

6b22e0a

…points

mejiaj mentioned this pull request Sep 19, 2024

USWDS - Utilities: Add theme setting for custom breakpoints #5985

Closed

mejiaj pushed a commit to uswds/uswds-sandbox that referenced this pull request Sep 23, 2024

Test uswds/uswds#6048

d8c1e0b

mejiaj mentioned this pull request Sep 23, 2024

[Test] Custom breakpoint uswds#6048 uswds/uswds-sandbox#153

Closed

mejiaj approved these changes Sep 23, 2024

View reviewed changes

mejiaj mentioned this pull request Sep 23, 2024

USWDS-Sandbox - Test: USWDS custom breakpoints feature uswds/uswds-sandbox#148

Closed

amyleadem reviewed Sep 24, 2024

View reviewed changes

packages/uswds-core/src/styles/mixins/helpers/at-media.scss Outdated Show resolved Hide resolved

amyleadem added 2 commits September 24, 2024 10:26

Add "and can not be generated" to warning message

f319030

Add custom breakpoints to grid-gap, col, & offset

6fb3bcb

amyleadem mentioned this pull request Sep 26, 2024

USWDS - Layout grid utility: Custom breakpoints #6083

Merged

Add custom breakpoints for grid-container

4a93553

mejiaj requested a review from amyleadem October 1, 2024 15:14

Merge pull request #6083 from uswds/al-custom-breakpoints

9c6fbd7

USWDS - Layout grid utility: Custom breakpoints

amyleadem approved these changes Oct 1, 2024

View reviewed changes

packages/uswds-core/src/styles/mixins/helpers/at-media.scss Outdated Show resolved Hide resolved

Add more context to breakpoint units warning

3261823

Co-authored-by: Amy Leadem <93996430+amyleadem@users.noreply.github.com>

thisisdano approved these changes Oct 3, 2024

View reviewed changes

thisisdano merged commit 1fb7e32 into develop Oct 3, 2024

thisisdano deleted the cm-custom-breakpoints branch October 3, 2024 04:17

thisisdano mentioned this pull request Oct 4, 2024

USWDS 3.9.0 #6096

Merged

mejiaj mentioned this pull request Mar 26, 2025

USWDS - Bug: Error encountered while defining custom variable in _uswds-theme.scss #6448

Closed

2 tasks

		$our-breakpoints: map-deep-get($system-properties, breakpoints, standard);
		$custom-breakpoints: map-deep-get($system-properties, breakpoints, extended);

USWDS - Utilities: Custom breakpoints #6048

USWDS - Utilities: Custom breakpoints #6048

Uh oh!

Conversation

mahoneycm commented Sep 5, 2024 • edited by amyleadem Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Sample implementation

Breaking change

Related issue

Related pull requests

Preview link

Problem statement

Solution

Major changes

Testing and review

Testing steps

Update responsive settings test

Testing checklist

Uh oh!

mahoneycm commented Sep 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additional consideration: Custom breakpoints + layout grid

Uh oh!

mahoneycm commented Sep 18, 2024

Uh oh!

mahoneycm left a comment

Choose a reason for hiding this comment

Uh oh!

mahoneycm Sep 18, 2024

Choose a reason for hiding this comment

Uh oh!

mahoneycm Sep 18, 2024

Choose a reason for hiding this comment

Uh oh!

mahoneycm Sep 18, 2024

Choose a reason for hiding this comment

Uh oh!

jamigibbs commented Sep 18, 2024

Uh oh!

mejiaj left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Non-pixel values

Additional utils

Overriding root font size

Output CSS size

Uh oh!

amyleadem left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Testing details

Uh oh!

Uh oh!

amyleadem commented Sep 26, 2024

Uh oh!

amyleadem commented Oct 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thisisdano left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mahoneycm commented Sep 5, 2024 •

edited by amyleadem

Loading

mahoneycm commented Sep 16, 2024 •

edited

Loading

mejiaj left a comment •

edited

Loading

amyleadem left a comment •

edited

Loading

amyleadem commented Oct 1, 2024 •

edited

Loading