USWDS - Draft 3.14.0 release notes

@HopeTurnerUSCIS

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 (5 low, 11 moderate, 3 high) in devDependencies (development dependencies)

Additional contributions

Thanks to @szepeviktor for fixing typos and EditorConfig improvements. (USWDS: Fix typos in 2026 #6720, USWDS: Add missing key to EditorConfig #6278)
Thanks to @manichandra for fixing 18F guide links. (USWDS - Documentation: Fix 18F guide links #6658)
Thanks to @ericsorenson for upgrading our eslint (USWDS - Dependencies: Upgrade ESLint from 8.x to 10.x #6690) and Storybook (USWDS - Storybook: Update Storybook to v8.6 #6697, USWDS - Storybook: Upgrade to Storybook 9 and migrate from Webpack to Vite #6715) tooling

I deliberately chose not to use the @ mention here so we don't notify all the contributors yet. The @ should be added to the release notes so it can live there.

So great to see all this in one place. You especially, but also all of us, have done so much work here. And look at how many contributors we get to thank! 🎉

Suggestions (non-blocking):

Past release notes have put actions needed from teams starting with ✏️ in their own new paragraph. I do think that separation helps people scan for what they need to do.
not sure where the internal notes at the end will go, but for the last item I'd suggest "File input text" rather than "File input copy" for clarity (edited to add: ah! found where those came from; those were just my notes in a meeting to remember highlights and start drafting release notes; they're not needed here, so can just be cut entirely)

Formatting fixes are in. I'm proud of this work and all the contributions that people have made. The community really stepped up to bolster our own efforts.

@annepetersen

@annepetersen, @chandracarney, @iamjolly, @jonathanbobel - This is all current as of today. Feel free to suggest or make edits to this.

Correction needed: `usa-select` box-sizing entry is underscoped

The current release notes attribute the box-sizing: border-box fix only to usa-select (#6736). However commit 0aadb024c ("Move input box sizing to shared form styles") subsequently moved the declaration into %block-input-styles in uswds-core, which is extended by:

usa-input
usa-textarea
usa-range
usa-combo-box
usa-input-prefix-suffix
usa-select

The ✏️ note in the release notes should be expanded from covering only usa-select to covering all form inputs, since all of them now behave consistently. Suggested revision:

✏️ Teams using a custom global box-sizing reset (i.e. $theme-global-border-box-sizing: false) should verify that all form inputs — including usa-input, usa-select, usa-textarea, usa-range, and usa-combo-box — display correctly after this update.

@ethangardner

That revision looks good to me, @ethangardner. Any need to retain the note about CMS theming? (My instinct is no, and I see why you cut it, but surfacing the reasoning here might be helpful)

@annepetersen

@annepetersen - I left that more of a draft for myself so I could come back to the release notes table, the notifications we have in sass, and to widen the scope of the changelogs on the site since it touches multiple components. I wanted to remove the CMS theme comment specifically because that's an external factor, whereas $theme-global-border-box-sizing: false is a styling mechanism we provide directly.

@chandracarney

@chandracarney Thanks for that section about the improvements we made to Alert guidance: mind linking up the PR and the component page itself in that Guidance changes entry you added?

@annepetersen

@annepetersen great idea, done!

@chandracarney

@chandracarney Also just caught me: could we make it "The alert component page now recommends... as well as extended guidance to help teams use the correct alert type." (and then cut the last sentence) to eliminate the passive voice there? I'd do it, but that'd wipe my ability to approve

edit: forgot this didn't require approval here, so just did so

These look ready to go to me; reflected also in #6822 🟢

🥧 🚀

Navigation Menu

Repository navigation

USWDS - Draft 3.14.0 release notes #6809

What's new in USWDS 3.14.0

Features

Bug fixes

Guidance changes

Alert

Markup changes

Memorable date

File input

Accordion icon alignment

Dependencies and security

Dependency updates

Dev dependency updates

Additional contributions

Correction needed: `usa-select` box-sizing entry is underscoped

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

USWDS - Draft 3.14.0 release notes #6809

Description

What's new in USWDS 3.14.0

Features

Bug fixes

Guidance changes

Alert

Markup changes

Memorable date

File input

Accordion icon alignment

Dependencies and security

Dependency updates

Dev dependency updates

Additional contributions

Activity

ethangardner commented on Aug 11, 2026

annepetersen commented on Aug 12, 2026

ethangardner commented on Aug 12, 2026

ethangardner commented on Aug 14, 2026

ethangardner commented on Aug 14, 2026

Correction needed: usa-select box-sizing entry is underscoped

annepetersen commented on Aug 17, 2026

ethangardner commented on Aug 17, 2026

annepetersen commented on Aug 18, 2026

chandracarney commented on Aug 18, 2026

annepetersen commented on Aug 18, 2026

annepetersen commented on Aug 18, 2026

annepetersen commented on Aug 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Correction needed: `usa-select` box-sizing entry is underscoped