USWDS 3.8.0

Features

Package	A11y	Breaking	Markup change	Description
usa-checkbox, uswds-core	-	-	-	Added styles for indeterminate checkboxes. Checkboxes will now display as indeterminate when you set input.indeterminate = true via JavaScript or add the data-indeterminate attribute. This is only a style addition and does not affect checkbox functionality. Thanks @lpsinger! (#5713)
usa-in-page-nav	-	-	-	Added the ability to customize which headings will be pulled into the in-page navigation link list. Use the optional data-heading-selector attribute to designate the heading levels that should be included in the component. By default, the component will pull all H2 and H3 headers. (#5444)
usa-table, uswds-core	-	-	-	Added a sticky header variant to the table component. Use the new .usa-table--sticky-header class to enable sticky positioning on table headers. Use the new $theme-table-sticky-top-offset setting to set the value of the top offset for sticky table headers. (#5420) Thanks @etanb!
usa-table, uswds-core				Added the ability to customize the table background color at a theme level. Use the $theme-table-background-color setting to set your desired table background color. (#5420)
usa-validation	-	-	-	Added textarea support to the validation component. (#5233) Thanks @danbrady!
usa-layout-docs, uswds-core	Yes	Yes	Yes	Added $theme-sidenav-reorder for documentation page sidenav. Use $theme-sidenav-reorder to support old CSS order functionality. This setting can introduce usability issues, so we suggest that teams update their sidenav markup instead. (#5807)

Bug fixes

Package	A11y	Breaking	Markup change	Description
usa-button, uswds-core	-	-	-	Improved the vertical alignment of usa-icon elements inside of usa-button. Use the new $theme-button-icon-gap setting to set the width of the horizontal gap between the button's text and icon. (#5398)
usa-button, usa-checkbox, usa-combo-box, usa-file-input, usa-radio, uswds-core	Yes	-	-	Added automated color contrast checks for disabled tokens. On compilation, USWDS will test disabled element color contrast and provide a fallback color if minimum contrast is not met. If the fallback also fails to meet minimum contrast requirements, the system will provide a warning in the terminal. (#5455)
usa-button-group	-	-	-	Improved the appearance of button groups when button text wraps to multiple lines. Now, every button in the group will be the same height. (#5657) Thanks @aduth!
usa-date-picker	Yes	-	-	Added focus styles to the calendar button in high contrast mode. Now, the calendar icon changes to the highlight high contrast token on focus. (#5701)
usa-footer	-	-	-	Fixed a bug that caused some grid utility classes to be ignored when used inside usa-footer. (#5675)
usa-layout-docs, uswds-core	Yes	Yes	Yes	Updated the order of the side navigation markup on the documentation page template. Now, the HTML order of the page matches the visual order at narrow screen widths. (#5794)
usa-table	Yes	-	Yes	Simplified the structure of the scrollable table component example. This removes some accessibility errors related to incomplete table markup. (#5783)

Breaking changes

Documentation page template

We're updating the documentation template to better match the HTML order of the side navigation to the visual order at mobile widths. Before USWDS 3.8.0 we used CSS to re-order the sidenav at mobile widths, placing it below the page's main text content. Starting with USWDS 3.8.0, our default styles no longer use CSS to re-order the side navigation. Now, we suggest including a duplicate sidenav after the main text content, using utility classes to hide/show the sidenavs at the proper widths. The example below shows a before/after.

<div class="grid-container">
  <div class="grid-row grid-gap">
-   <div class="usa-layout-docs__sidenav">
+   <!-- One of two sidenav's only shown in desktop breakpoints. --> 
+   <div class="usa-layout-docs__sidenav display-none desktop:display-block desktop:grid-col-3">
      {{ SIDENAV_MARKUP }}
    </div>
-   <main class="usa-layout-docs__main desktop:grid-col-9 usa-prose usa-layout-docs" id="main-content">
+   <main class="desktop:grid-col-9 usa-prose usa-layout-docs" id="main-content">
      {{ MAIN_CONTENT }}
    </main>
  </div>
+ <!-- New duplicate section only shown on mobile. -->
+  <div class="usa-layout-docs__sidenav desktop:display-none">
+    {{ SIDENAV_MARKUP }}
+  </div>
</div>

Teams that wish to maintain the old CSS order functionality can temporarily add $theme-sidenav-reorder: true to their project settings. This setting reinstates the CSS re-ordering. As we mentioned, this setting can introduce usability issues, so the best long-term solution is to update the sidenav markup instead.

Dependencies and security

Dependency name	Previous version	New version
@babel/core	7.23.2	7.23.6
@babel/preset-env	7.23.2	7.23.6
@types/node	20.8.9	20.10.4
eslint	8.52.0	8.55.0
eslint-config-prettier	9.0.0	9.1.0
gulp-mocha	8.0.0	9.0.0
handlebars-helpers	0.10.0	--
html-webpack-plugin	5.5.3	5.5.4
postcss	8.4.31	8.4.32
postcss-import	--	15.1.0
postcss-preset-env	9.2.0	9.3.0
postcss-sass-loader	1.1.0	--
resolve-url-loader	4.0.0	5.0.0
sass	--	1.69.5
snyk	1.1237.0	1.1262.0
svgo	3.0.2	3.1.0
typescript	5.2.2	5.3.3

0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install @uswds/uswds)
15 moderate, 25 high vulnerabilities in devDependencies (development dependencies).

Release TGZ SHA-256 hash: 072f0f8333b1aa000183e00676616d9ff5a174e27ca8d35c130ca70ea5d4f66d