Skip to content

USWDS 3.14.0

Latest
Latest

Choose a tag to compare

View all tags
@ethangardner ethangardner released this 18 Aug 20:08
· 0 commits to develop since this release
v3.14.0
This tag was signed with the committer’s verified signature.
ethangardner Ethan Gardner
SSH Key Fingerprint: 0a3Eo2mRq5eTCP1TWSTDnWD47dHeoDmQrwAqXzu4MgY
Verified
Learn about vigilant mode.
92391c3
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What's new in USWDS 3.14.0

Features

Package A11y Breaking Markup change Description
usa-accordion, uswds-core Yes Yes Yes Added a left-aligned expand/collapse icon option. A new $theme-accordion-icon-position setting (default: "start") lets teams set icon placement globally. The .usa-accordion--icon-start and .usa-accordion--icon-end modifier classes support per-instance placement. This improves discoverability for users viewing content at high magnification or zoom levels. Thanks @HopeTurnerUSCIS, @rosamundtgov, and @jeana-adhoc! (#6789)

✏️ Teams should verify layout at common zoom levels for the new default accordion behavior.
usa-breadcrumb Yes Yes - Breadcrumbs now wrap by default. The previous truncation behavior is now opt-in via the new usa-breadcrumb--truncate modifier class. Thanks @AKnassa! (#6722)

✏️ Teams should confirm breadcrumbs display as expected and add usa-breadcrumb--truncate if they want the old truncation behavior.
usa-range Yes - Yes Added a visible hint to the range slider. A new usa-hint element with the text "Move the slider to change the value" is added above the slider so sighted users receive the same guidance that screen reader users already had. Thanks @ravitejapioneerblaze-code! (#6673, #6811)

✏️ Teams should pull in the updated markup.
usa-range Yes - - Improved range slider border visibility. The border is now 2px and uses the base-darker theme token. A focus ring is also added to the slider input. Thanks @manichandra! (#6659)
usa-date-picker Yes - Yes Added aria-current="date" to today's date button. Assistive technologies can now programmatically identify the current date in the calendar widget. Thanks @daresTheDevil! (#6593)
usa-file-input - - - Error border now uses the error-dark token. The file input error state previously used secondary-dark, which could show the wrong color in projects with distinct secondary and error palettes. Thanks @manichandra! (#6669)

Bug fixes

Package A11y Breaking Markup change Description
usa-modal Yes - - Closing a modal now always restores screen reader access to the page. If the element that opened the modal had left the document by the time the modal closed, page content kept aria-hidden="true" and stayed invisible to assistive technology until reload. Thanks @vssinghh! (#6786)
usa-modal, uswds-core Yes - Yes Fixed modal content being read twice by screen readers. The default focus target has changed — on open, focus now moves to the first enabled button in the modal footer, or the first enabled button in the modal if no footer button is present. FocusTrap no longer uses autoFocus. (#6703)

✏️ Teams should verify modal focus lands where expected after this update.
usa-memorable-date Yes - Yes Added per-field hints to the memorable date component. The component previously used a single shared hint referenced by all three fields via aria-describedby, causing screen readers to repeat the full instruction block on every field focus. Each field now has its own targeted hint. The visible group hint remains for sighted users with aria-hidden="true". (#6725)

✏️ Teams should update to the new per-field hint markup. Teams supporting other languages should update their hint strings.
usa-file-input Yes Yes Yes Removed the drag instruction on mobile and coarse-pointer devices. The file input previously showed "Drag file here or choose from folder" on all devices, including mobile where drag-and-drop isn't a practical interaction. Coarse-pointer devices now show and announce "Choose from folder" only. Thanks @manichandra! (#6660)

✏️ Teams should check for layout changes and update any accessibility tests that assert the old exact instruction text.
usa-character-count Yes - - Deferred aria-live to prevent iOS VoiceOver from announcing character count on page load. Live updates continue to fire normally during typing. Thanks @daresTheDevil! (#6595)
usa-character-count - - - Fixed the label selector so it correctly finds the associated label. Thanks @ealexhaywood! (#6385)
usa-footer - Yes - Restricted data-tag to heading elements. The footer's big link list was vulnerable to XSS through unsanitized data-tag values. Non-heading elements now gracefully fall back to h4. Thanks @IHIutch! (#6674)

✏️ Teams should review any footer data-tag values that aren't heading elements.
usa-banner, uswds-core - - - Fixed toggle so it resolves aria-controls from the component's root node. This allows banner toggles to work correctly when used inside a shadow root. Thanks @arpitjain099! (#6714)
uswds-core - - - Fixed the language selector Escape key handler. Thanks @arpitjain099! (#6713)
uswds-core - - - Guarded the keymap against non-keyboard events from datalist selections. This prevents a console error when a user selects an option from a datalist. Thanks @vijaygovindaraja! (#6594)
usa-table - - - Restored the row header border in borderless tables. Row-scoped body header cells now keep their top border so row headers don't appear visually disconnected. Thanks @manichandra! (#6661)
usa-table - - - Fixed .usa-sr-only table caption causing heading-row border collapse. Thanks @IHIutch! (#6633)
usa-time-picker - - - Added missing combobox style dependency to the time picker package. Thanks @IHIutch! (#6634)
usa-input, usa-textarea, usa-range, usa-combo-box, usa-input-prefix-suffix, usa-select - - - Set box-sizing: border-box on the %block-input-styles mixin to prevent overflow. Components in host environments that reset global box sizing no longer overflow their containers. Thanks @VenkateshAddala! (#6736)

✏️ Teams should verify these elements display correctly in projects with custom global box-sizing resets (e.g. those who set $theme-global-border-box-sizing: false).
usa-in-page-navigation - - - Standardized the component's enhancement guard to use data-enhanced in line with other USWDS components. (#6688)
uswds-core - - - Fixed ink assignment referencing the wrong variable. Custom ink colors in a project's theme were referencing the wrong system token. Thanks @nektro! (#6651)

✏️ Teams should verify that custom ink colors in their theme render as expected.

Guidance changes

Alert

The alert component page now recommends that alert headings start with the alert type to improve clarity and urgency of the message, both for accessibility and general usability, as well as adding extended guidance to help teams use the correct alert type. Thanks @jeana-adhoc and @rosamundtgov! (#3288)

Markup changes

Memorable date

The memorable date component's three fields now each have their own aria-describedby hint instead of sharing a single
group hint. Teams who've copied the memorable date markup should update to the per-field pattern:

 <fieldset class="usa-fieldset">
   <legend class="usa-legend">Date of Birth</legend>
-  <span class="usa-hint" id="mdHint">For example: January 19 2000</span>
+  <span class="usa-hint" aria-hidden="true" id="memorable-date-hint">
+    Select a month. Enter 1 or 2 digits for the day and 4 digits for the year.
+  </span>
   <div class="usa-memorable-date">
     <div class="usa-form-group usa-form-group--month usa-form-group--select">
       <label class="usa-label" for="date_of_birth_month">Month</label>
-      <select class="usa-select" id="date_of_birth_month" name="date_of_birth_month" aria-describedby="mdHint">
+      <span class="usa-hint usa-sr-only" id="memorable-date-month-hint">Select a month from the dropdown.</span>
+      <select class="usa-select" id="memorable-date-month" name="memorable-date-month" aria-describedby="memorable-date-month-hint">
         ...
       </select>
     </div>
     <div class="usa-form-group usa-form-group--day">
       <label class="usa-label" for="date_of_birth_day">Day</label>
-      <input class="usa-input" aria-describedby="mdHint" id="date_of_birth_day" name="date_of_birth_day" ... />
+      <span class="usa-hint usa-sr-only" id="memorable-date-day-hint">Enter 1 or 2 digits for the day.</span>
+      <input class="usa-input" aria-describedby="memorable-date-day-hint" id="memorable-date-day" name="memorable-date-day" ... />
     </div>
     <div class="usa-form-group usa-form-group--year">
       <label class="usa-label" for="date_of_birth_year">Year</label>
-      <input class="usa-input" aria-describedby="mdHint" id="date_of_birth_year" name="date_of_birth_year" ... />
+      <span class="usa-hint usa-sr-only" id="memorable-date-year-hint">Enter 4 digits for the year.</span>
+      <input class="usa-input" aria-describedby="memorable-date-year-hint" id="memorable-date-year" name="memorable-date-year" ... />
     </div>
   </div>
 </fieldset>

File input

The file input no longer renders the drag instruction on coarse-pointer or mobile devices. On those devices, the
instruction now reads "Choose from folder" instead of "Drag file here or choose from folder". For fine-pointer devices,
the text remains "Drag file here or choose from folder." Teams with tests that assert the exact instruction text should
update those tests.

- Drag file here or choose from folder
+ Choose from folder

Accordion icon alignment

The default alignment for the accordion toggle icon switches to the left for better accessibility for users who zoom or
use screen magnification. Teams can now use the usa-accordion--icon-start or usa-accordion--icon-end modifier to
left-align or right-align the expand/collapse icon at the instance-level respectively. Icon position can be set globally
with the $theme-accordion-icon-position Sass setting. The default behavior ("start" / left-aligned) is changed from
v3.13.0, and the historical behavior can be preserved with $theme-accordion-icon-position: "end".

- <div class="usa-accordion">
+ <div class="usa-accordion usa-accordion--icon-start">

or

- <div class="usa-accordion">
+ <div class="usa-accordion usa-accordion--icon-end">

Or set globally in your theme:

+ $theme-accordion-icon-position: "start";

or

+ $theme-accordion-icon-position: "end";

Dependencies and security

Dependency updates

Dependency name Previous version New version
lit 3.2.1 3.3.3
receptor 1.0.0 --

Note: receptor has been removed as a dependency. Its functionality has been reimplemented in first-party code.
Thanks @aduth! (#6489)

Dev dependency updates

Dependency name Previous version New version
@babel/core 7.26.8 7.29.7
@babel/preset-env 7.26.8 7.29.7
@chanzuckerberg/axe-storybook-testing 6.3.1 --
@material-design-icons/svg 0.14.13 0.14.15
@rollup/plugin-commonjs 28.0.3 29.0.3
@spiriit/vite-plugin-svg-spritemap 4.0.0 6.0.0
@storybook/addon-a11y 6.5.16 9.1.20
@storybook/addon-essentials 6.5.16 --
@storybook/addon-links 6.5.16 --
@storybook/builder-webpack5 6.5.16 --
@storybook/html 6.5.16 --
@storybook/html-vite -- 9.1.20
@storybook/manager-webpack5 6.5.16 --
@storybook/test-runner -- 0.23.0
@types/node 20.14.10 24.13.3
@uswds/compile -- 1.3.2
autoprefixer 10.4.20 10.5.0
axe-core 4.10.2 --
axe-playwright -- 2.2.2
concurrently -- 10.0.3
css-loader 6.8.1 --
del 6.0.0 8.0.1
esbuild -- 0.28.1
eslint 8.56.0 10.8.0
eslint-config-airbnb-base 15.0.0 --
eslint-config-prettier 9.1.0 10.1.8
eslint-plugin-airbnb-base 0.0.1-security --
eslint-plugin-import 2.31.0 --
eslint-plugin-import-x -- 4.17.1
eslint-plugin-lit 2.0.0 2.3.1
eslint-plugin-no-unsanitized 4.1.2 --
file-loader 6.2.0 --
globals -- 17.8.0
gulp 4.0.2 5.0.1
gulp-mocha 9.0.0 10.0.1
gulp-postcss 9.0.1 10.0.0
gulp-rename 2.0.0 2.1.0
gulp-sass 6.0.0 6.0.1
html-webpack-plugin 5.6.3 5.6.8
http-server -- 14.1.1
magic-string -- 0.30.21
merge-stream 2.0.0 --
mocha 10.8.2 11.8.0
postcss 8.5.2 8.5.25
postcss-discard-comments 6.0.2 8.0.2
postcss-import 15.1.0 --
postcss-loader 7.3.3 --
postcss-preset-env 9.6.0 --
prettier 3.4.2 3.9.6
react-dom 17.0.2 --
resolve-url-loader 5.0.0 --
sass-embedded 1.83.4 1.100.0
sass-loader 16.0.4 --
sass-true 6.0.1 10.1.0
sinon 12.0.1 22.1.0
snyk 1.1295.3 1.1306.2
storybook -- 9.1.20
style-loader 3.3.3 --
svgo 3.3.2 4.0.2
twig -- 3.0.0
twigjs-loader 1.0.3 --
vite 6.2.2 6.4.3
vite-plugin-svg-sprite 0.6.2 --
wait-on -- 9.1.0
webpack 5.98.0 5.109.2
webpack-cli 5.1.4 7.2.2

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

19 vulnerabilities (11 moderate, 3 high) in devDependencies (development dependencies)

SHA-256 for release

da91c65e6fc736fa397f0daf6ca2c2c95711506d85c7ad2537a4570725401e1c

Additional contributions

Contributors

ericsorenson, szepeviktor, and 15 other contributors
Assets 3
Loading