USWDS 3.5.0

[thisisdano]

What's new in USWDS 3.5.0

Features

Package	A11y	Breaking	Description
usa-button, usa-dark-background, uswds-core	—	—	Stopped using font smoothing. No longer use font smoothing for dark backgrounds and disabled buttons. (#5250)
usa-button, usa-checkbox, usa-date-picker, usa-pagination, usa-radio, usa-range, usa-search, uswds-core	Yes	—	Improved legibility of buttons in forced colors mode. Added a consistent border in forced colors mode. (#5147)
usa-button, usa-checkbox, usa-combo-box, usa-date-picker, usa-date-range-picker, usa-file-input, usa-input, usa-input-mask, usa-input-prefix-suffix, usa-radio, usa-range, usa-select, usa-textarea, uswds-core	Yes	—	Improved consistency of disabled styles in forced colors mode. (#5295)
usa-button, usa-checkbox, usa-combo-box, usa-date-picker, usa-date-range-picker, usa-file-input, usa-input, usa-input-prefix-suffix, usa-radio, usa-range, usa-select, usa-textarea, usa-time-picker, uswds-core	Yes	—	Improved consistency and visibility of disabled styles. Disabled form inputs now use a consistent gray background. (#5063) ⚠️ We don't consider this a breaking change, but teams should check disabled form elements to assure that the new styles are working in their layouts.
usa-link, uswds-core	Yes	—	Labeled external links for screen readers. Added a label for screen readers that identifies external links and if they open in a new tab. (#5166)
uswds-core	Yes	—	Added settings for announcing external links. Added $theme-external-link-sr-label-tab-same and $theme-external-link-sr-label-tab-new to control how screen readers announce external links. (#5166)
usa-content, usa-paragraph, usa-prose, uswds-core	—	Yes	Removed usa-prose- mixins and placeholders from Sass. Users should instead use typeset- mixins in their place. This is a breaking change only if your project Sass uses usa-prose- mixins and placeholders. It does not affect the look of any usa-prose–styled element.(#5158)
uswds-core	—	—	Added $theme-heading-margin-top and $theme-paragraph-margin-top system variables. (#5158)
uswds-core	—	Yes	Updated individual Sass map settings without affecting defaults. Now adjusting a single Sass map setting will no longer set all other values in the map to false. Users can now update only the map values they wish to change. This is a breaking change only if your project deactivated mapped settings by not declaring them. (#5216)
usa-accordion, usa-banner, usa-nav, uswds-core	—	—	Added two new settings to customize accordion background colors. You can now customize accordion button and content background colors with $theme-accordion-button-background-color and $theme-accordion-background-color. (#5269)

Bug fixes

Package	A11y	Breaking	Description
usa-header	—	—	Removed the id attribute from the usa-logo element. (#5319)
usa-header	—	—	Fixed a bug that caused inaccurate megamenu template markup. The markup in megamenu code examples now accurately includes the usa-megamenu class. (#5311)
usa-table	Yes	—	Fixed a typo in the sortable table JavaScript that caused the aria-label in table headers to have an unnecessary single quote. (#5280)
uswds-core, uswds-utilities	—	—	Removed unused utility builder comments from compiled CSS. This update significantly reduces the compiled file size. (#5209)
usa-tooltip	—	—	Fixed a bug that removed default positioning. If the data-position attribute is not specified, the tooltip position will now default to "top". (#5228)
usa-in-page-navigation	—	—	Fixed a bug that prevented links that start with a number from scrolling when clicked. (#5200)
usa-alert	—	—	Removed redundant and invalid height declaration. (#5187)
usa-button	Yes	—	Fixed a bug that caused button type attribute to render empty. (#5247)
usa-button	Yes	—	Added spacebar trigger to links styled as buttons. Now any item that looks like a button will trigger with the spacebar, even if the element is a link. (#4385)
usa-card	Yes	Yes	Replaced button elements with links styled as buttons. ⚠️ This is marked as a breaking change because it changes the recommended card component markup to include <a href="#" class="usa-button"></a> for the call to action instead of a button element. (#4385)
usa-pagination	Yes	Yes	Improved accessible markup of overflow ellipses. We replaced the role="presentation" with aria-label="ellipsis indicating non-visible pages" for usa-pagination__overflow items to better conform to WCAG 2.0 and 2.1. ⚠️ This is marked as a breaking change because it changes the recommended component markup. In the usa-pagination__overflow element, use aria-label="ellipsis indicating non-visible pages" instead of role="presentation". (#5197)
usa-file-input	—	—	Fixed an issue with large file previews. Now adding large files no longer results in an infinite spinner. Adding large files should now result in an accurate preview. (#5114)
usa-file-input	Yes	—	Improved the file input experience for voice command and screen reader users. Voice command users can now interact with the component by speaking the visible instructions text. Additionally, screen reader users now have access to both the instructions text and the file selection status. (#5213)
usa-combo-box	Yes	—	Improved consistency of keyboard actions. Users can now to use Tab to escape the Combo box selection without making a choice, and Space to select the current highlighted option when within the dropdown menu. (#5160)
usa-accordion, usa-banner, usa-nav	Yes	—	Adjusted forced colors mode styles to ensure visibility and increase consistency. Forced colors mode styles will now override the background color and display the button outline. The open/close icons now dynamically adjust to ButtonText colors. (#5286)
usa-identifier	—	Yes	Updated Accessibility statement link text. Updated the identifier to use the text "Accessibility statement" (EN) / "Declaración de accesibilidad" (ES) for the required link to an accessibility statement. ⚠️ This is a breaking change because it changes the content of the identifier. Earlier versions of the identifier will continue to work as expected. (#5278)
Guidance	Yes	—	Updated guidance to suggest identifying required and optional fields. We added a new section on identifying required fields and now suggest labeling required fields with a red asterisk and optional fields with the word optional. (uswds/uswds-site#1834)

Dependencies and security

Dependency name	Previous version	New version
@chanzuckerberg/axe-storybook-testing	5.0.1	6.3.0
axe-core	4.3.4	4.6.3
extract-loader	5.1.0	—
webpack	5.58.1	5.76.0

---

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

1 moderate 29 high vulnerabilities in devDependencies (development dependencies)

---

Related PR

USWDS-Site: Add changelog items for USWDS 3.5.0 #2096

---

Release TGZ SHA-256 hash: e0dbab25bffaaf02b3b7317690939d9e0e63bc5c824046e778de8f4c15227a9c

[amyleadem]

@thisisdano I reviewed the release notes in the PR description and had some notes. I am happy to work on edits if it would be helpful - either directly in the description or in a separate markdown file (whichever you prefer). Just let me know.

Note: this might be easier to read in edit mode since it doesn't enhance the PR numbers there.

• Confirmed that all items in the 3.5.0 milestone are accounted for
  • USWDS - Accordion: Add color settings #5269 not listed in description
  • USWDS - Banner: Add accordion dependency #5242 is included but we should remove since we aren’t including it in the release
  • USWDS - Accessibility: Added button functionality to usa-button links #4385 - the description for this matches USWDS: Button - Forced colors outline #5147, not USWDS - Accessibility: Added button functionality to usa-button links #4385. We should update the PR number to USWDS: Button - Forced colors outline #5147
    • Might be clearer if it said “Improved legibility of buttons in forced colors mode.”
  • “Added spacebar trigger to links styled as buttons.” and “Replaced button elements with links styled as buttons.”are tagged as part of USWDS: Button - Forced colors outline #5147 but should be USWDS - Accessibility: Added button functionality to usa-button links #4385
  • “Removed unused utility builder comments from compiled CSS.” PR number is inaccurate. Should be USWDS - Core: Remove commented code from utility builder #5209.
    • Also should it include uswds-core?
  • Can we put both USWDS - Links: External link labels #5166 items next to each other?
  • USWDS - Prose: Placeholder fix. Resolves #5094 #5158. - Should we also mention the placeholder fix?
• Confirmed all a11y items have been appropriately identified
  • USWDS - Accordion: Create more consistent high contrast styles #5286 should be marked as a11y
  • USWDS - Pagination: Remove presentation role #5197 is marked appropriately, but there is a typo in the table cell
• Confirmed all breaking changes have been identified
  • [Identifier] Update Accessibility statement language #5278 should be listed as breaking - added a note about break
  • USWDS - Prose: Placeholder fix. Resolves #5094 #5158 should be listed as potentially breaking
  • USWDS - Settings: Update sass map pattern #5216 should be listed as potentially breaking - added a note about break
• Confirmed that all listed packages are accurate:
  • Note: I tried to flag only the missing packages that had user-facing changes.
  • USWDS - Core: Deprecate font-smoothing mixins #5250 - Should we list that it also impacts the usa-dark-background and uswds-core packages?
  • USWDS: Button - Forced colors outline #5147 - Missing uswds-core?
  • USWDS - Disabled styles: Improve consistency in high contrast mode #5295 - Missing usa-input-mask, usa-range, usa-textarea, uswds-core, ; usa-text-input should be usa-input
  • Form Inputs: Normalize disabled forms styles #5063 - Missing usa-range, usa-textarea, usa-time-picker, uswds-core
  • USWDS - Links: External link labels #5166 - Missing uswds-core
  • USWDS - Accordion: Create more consistent high contrast styles #5286 - missing usa-banner, usa-nav
  • USWDS - Prose: Placeholder fix. Resolves #5094 #5158. - Missing usa-content, usa-paragraph, uswds-core
  • USWDS - Prose: Placeholder fix. Resolves #5094 #5158 (settings entry) - replace usa-prose with uswds-core
• Confirmed items are written in a consistent tense
  • USWDS - Settings: Update sass map pattern #5216 is in present tense
  • USWDS - Links: External link labels #5166 is in present tense
  • USWDS: Button - Forced colors outline #5147 is in present tense
• Confirmed no typos or errors in spelling/grammar
  • USWDS - Button: define default type in JSON #5247 Extra “NNNN” in copy

[amyleadem]

@thisisdano @mejiaj @mahoneycm I have updated the PR description according to my notes above. I'll come back tomorrow morning to take another look and confirm everything looks good.

[thisisdano]

Thank you for your careful review @amyleadem!

[thisisdano]

I've updated references from 3.4.1 to 3.5.0, added the breaking notifications, and merged in the most recent work from develop. I think this is now pretty much ready to go: ready to run the release script and begin the release process.

[mejiaj]

LGTM, I tested:

• Milestone PRs are listed PR description.
• Milestone PRs are merged in develop branch.
• Release branch is sync'd with develop.
• Vulnerabilities are accurate (30 vulnerabilities (1 moderate, 29 high) - 06/09/23)
• Changelog PRs match release note PRs.

[amyleadem]

Looks good to me. Took another look at the description and made a couple small updates related to breaking changes.

PR contents:

• Confirmed all USWDS items tagged as part of 3.5.0 have been merged into develop
• Confirmed all USWDS-site items tagged as part of 3.5.0 have been merged into release-3.5.0
• Confirmed that release-3.5.0 is up-to-date with all changes from develop

PR description:

• Confirmed the PR description has a description for every issue tagged in 3.5.0 milestone
• Confirmed a11y items have been correctly identified
• Confirmed breaking items have been correctly identified and give description of the break
  • Form Inputs: Normalize disabled forms styles #5063 marked as potentially breaking in PR
    • I did not update this because it felt on the borderline of breaking. Flagging it here for attention.
  • USWDS - Accessibility: Added button functionality to usa-button links #4385 is marked as a breaking change in PR.
    • I updated the PR description by adding a breaking flag with the text: “This is marked as a breaking change because it changes the recommended markup of the component.”
  • USWDS - Pagination: Remove presentation role #5197 is marked as a breaking change in PR
    • I updated the PR description by adding a breaking flag with the text: “This is marked as a breaking change because it changes the recommended component markup.”
  • ⚠️ Some items are marked as “potentially” breaking - would it be beneficial to mark them as such here or just stick to the binary yes/no?
• Confirmed dependency updates
• Confirmed no spelling or grammatical errors

[thisisdano]

I think for these elements that are not technically breaking, we do not mark as breaking, but add a callout in the release notes that there's a recommended change in markup, and call out that change in the notifications file as well. I can do that now.

[thisisdano]

Updated breaking or potentially breaking changes with notes and a ⚠️ icon.
Updated notifications.

Current notifications:

--------------------------------------------------------------------
3.5.0
- Sass: Removed `usa-prose-` mixins and placeholders from Sass.
  This is a breaking change only if your project Sass uses
  `usa-prose-` mixins and placeholders. Users should instead use
  `typeset-` mixins in their place.
- Settings: Now adjusting a single Sass map setting will no
  longer set all other values in the map to `false`. Users can
  now update only the map values they wish to change. This is a
  breaking change only if your project deactivated mapped
  settings by not declaring them.
- Accessibility: [usa-pagination] Replace the
  `role="presentation"` with `aria-label="ellipsis indicating
  non-visible pages" in `usa-pagination__overflow` items.
- Accessibility: [usa-card] Use link elements in
  any card component for calls to action instead of buttons. Use
  `<a href="#" class="usa-button"></a>` for these
  call-to-action links.
- Content: [usa-identifier] We updated the accessibility statement
  link text. Use the text "Accessibility statement" (EN)
  or "Declaración de accesibilidad" (ES) for the required
  link to an accessibility statement.
- Guidance [usa-link]: We now suggest using the `rel="noreferrer"`
   property on external links. This prevents the browser from leaking
  information about the original web address.
- Guidance [usa-form]: We now suggest identifying both required
  and optional fields in forms. Label required fields with a red
  asterisk and optional fields with the word "optional".

[thisisdano]

Added a disabled form controls note:

--------------------------------------------------------------------
3.5.0
- Sass: Removed `usa-prose-` mixins and placeholders from Sass.
  This is a breaking change only if your project Sass uses
  `usa-prose-` mixins and placeholders. Users should instead use
  `typeset-` mixins in their place.
- Settings: Now adjusting a single Sass map setting will no
  longer set all other values in the map to `false`. Users can
  now update only the map values they wish to change. This is a
  breaking change only if your project deactivated mapped
  settings by not declaring them.
- Accessibility: [form controls] We improved the consistency and
  visibility of disabled styles. Teams should check disabled form
  elements to assure that the new styles are working in their
  layouts.
- Accessibility: [usa-pagination] Replace the
  `role="presentation"` with `aria-label="ellipsis indicating
  non-visible pages" in `usa-pagination__overflow` items.
- Accessibility: [usa-card] Use link elements in
  any card component for calls to action instead of buttons. Use
  `<a href="#" class="usa-button"></a>` for these
  call-to-action links.
- Content: [usa-identifier] We updated the accessibility statement
  link text. Use the text "Accessibility statement" (EN)
  or "Declaración de accesibilidad" (ES) for the required
  link to an accessibility statement.
- Guidance [usa-link]: We now suggest using the `rel="noreferrer"`
  property on external links. This prevents the browser from leaking
  information about the original web address.
- Guidance [usa-form]: We now suggest identifying both required
  and optional fields in forms. Label required fields with a red
  asterisk and optional fields with the word "optional".