What's new in USWDS 3.1.0

This release contains markup changes and potentially breaking changes. A ⚠️ icon indicates where we've made a change that might be a breaking change for your project.

Package updates

usa-button

Style aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). (#4783)

This also affects these dependent or related packages:

• usa-button-group
• usa-card
• usa-modal

⚠️ Added type="button" to all non-form buttons to prevent default submit behaviors. This allowed us to remove preventDefault() from the relevant component JS.

This is a potentially breaking change. Teams should update all non-form buttons to include type="button" in their markup. <button> elements that do not receive a defined type attribute will inherit type="submit" behaviors by default. This can cause unintended and undesired behavior in our buttons. Resource: Details on button types (Mozilla) (#4695)

This also affects these dependent or related packages:

• usa-accordion
• usa-banner
• usa-card
• usa-header
• usa-navbar
• usa-modal
• usa-nav
• usa-sidenav

usa-button-group

Unstyled buttons in a button group now have proper baseline alignment. (#4812)

usa-checkbox

Style aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). (#4783)

usa-date-picker

Style aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). (#4783)

usa-date-range-picker

Updated documentation to properly show how to disable dates. Our documentation provided incorrect information about where to add data-min-date and data-max-date attributes to the date range picker component. Add these attributes to the usa-date-range-picker element. (uswds/uswds-site#1605)

Style aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). (#4783)

usa-header

Fixed mobile menu appearance for different CSS layouts. The menu now appears properly on layouts using flex or CSS grid. (#4817)

usa-hero

Optimize hero image. We replaced our default hero image (644 KB PNG) with an optimized image (147 KB JPG), saving 477 KB. We've also provided a next-generation image format version of the image (105 KB WEBP) as an example.

⚠️ This changes the value of $theme-hero-image. If your project uses this default hero image, you'll need to make sure to move the new asset (hero.jpg) to your project images directory.

usa-icon

Added LinkedIn icon. We now have a LinkedIn icon included in our default icon sprite as linkedin.

⚠️ Use unmodified social media icons. We now provide simpler social media icons, and removed any decoration not in the original icon. This means that the new icons are not in an enclosing circle unless the original icon is enclosed in a circle. (#4872)

This also affects these dependent or related packages:

• usa-footer

usa-password

⚠️ Updated markup in the usa-password package to use a <button> element instead of an anchor element. This markup is more semantically appropriate for the related on-page user interaction.

This is not a breaking change. The old markup is still supported, but teams should consider updating to the new markup for improved semantics. (#4847)

Old

<p class="usa-form__note">
  <a href="#" class="usa-show-multipassword" aria-controls="password confirmPassword"
    data-hide-text="Hide my typing">Show my typing</a>
</p>

New

<button type="button" 
  class="usa-show-password usa-button usa-button--unstyled" 
  aria-controls="password confirmPassword"
  data-hide-text="Hide my typing">Show my typing</button>

usa-radio

Style aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). (#4783)

usa-select

Improved styling for select when the multiple attribute is present. According to the HTML5 standard, a select element whose multiple attribute is present is "expected to render as an inline-block box whose height is the height necessary to contain as many rows for items as given by the element's display size, or four rows if the [size] attribute is absent." Our select now conforms to this guidance. (#4766)

uswds-core

Style aria-disabled to match disabled. Now disabled styling is applied whether you use disabled (disabled and hidden from screen readers) or aria-disabled (disabled and visible to screen readers). (#4783)

uswds-utilities

Integrated the CSS aspect-ratio property into our add-aspect utility and mixins. This change aligns us more closely with expected CSS behavior, while also extending the capabilities of add-aspect. Users can now apply add-aspect directly to media and media wrappers — without the need to use .usa-embed-container. This update is backwards compatible and was written to preserve previous behavior for browsers that do not support the CSS aspect-ratio property. (#4811)

Dependency updates

No dependency updates.

0 vulnerabilities in regular dependencies (dependencies for USWDS projects installed with npm install uswds)

Internal only: 3 moderate, 32 high vulnerabilities in devDependencies (development dependencies)

Release TGZ SHA-256 hash: 727a1883badb336f67f6f355e8fdf7ace9af871ca8af7dbb231b2e3cc7649a9b