USWDS - Accordion: Extending accordion to allow for start/end icon alignment

Summary

Extended the expand/collapse icon to default to the start, or "left" side in the accordion button so magnification and zoom users can more easily discover interactive accordion controls, while keeping "end" (right-aligned) icons as an option.

Breaking change

This is not a breaking change.

Related issue

Closes #6784

Related pull requests

Related discussion: Component proposal in #6483 (VA user research on left-justified accordion controls).
Documentation for the new modifier and $theme-accordion-icon-position has a follow-up branch

Problem statement

Desired: Accordion expand/collapse controls are discoverable and understandable for users viewing content at high magnification or zoom levels, including screen magnification users and users who pinch-zoom or use programmatic zoom (e.g. Ctrl/Cmd + +).

Actual: Accordion expand/collapse icons are fixed on the right/end side of the button. When users zoom in, the control can fall outside the visible viewport or be harder to associate with the accordion heading, so users may not realize the accordion is interactive and important content can remain hidden.

Consequence: This disproportionately affects low-vision users who rely on screen magnification, but it also affects anyone zoomed in on mobile or desktop when content does not reflow as expected. VA user research (February 2026, referenced in #6483) found that left/start-justified expand/collapse controls improved discoverability: all screen magnification users in that study could identify the accordion as interactive. Left/start-justified controls were also reported as understandable and usable across broader user groups, not only magnification tool users.

Solution

This PR adds an easy, supported way to default to the left/start side of the accordion trigger, while keeping the option for a user to set the icon to the right/end.

1. Theme setting: $theme-accordion-icon-position (default "start") sets icon placement globally. Use "end" to keep the previous right-side (LTR) look.
2. Modifier classes: .usa-accordion--icon-start and .usa-accordion--icon-end support per-instance placement in markup.
3. Refactored styles: Shared mixins use logical properties (padding-inline-*, text-align: start, RTL background-position flips) so start and end variants stay visually and accessibly consistent in LTR and RTL.
4. Storybook: Default stories use the start-side icon. Added an IconEnd story and content fixture for the previous end-side placement.

No JavaScript or markup structure changes were required; open/closed icon behavior continues to be driven by existing aria-expanded styles.

Why this approach: A theme token plus modifier classes matches USWDS patterns and uses logical start / end so placement follows writing direction. Default is now "start" (left in LTR, right in RTL), which matches VA research on left-justified controls. Teams that want the previous look can set $theme-accordion-icon-position: "end" or add .usa-accordion--icon-end.

Limitations: Placement is limited to "start" and "end". Teams should still verify layout at common zoom levels and with screen magnification tools in their target browsers, including RTL (dir="rtl").

Major changes

• Added $theme-accordion-icon-position to _settings-components.scss (default: "start")
• Refactored accordion button padding and background positioning into shared mixins using logical properties
• Updated high contrast mode ::before icon positioning to respect icon side
• Added .usa-accordion--icon-start and .usa-accordion--icon-end modifiers
• Added usa-accordion~icon-end.json content and IconEnd Storybook story
• Set accordion button text-align: start so heading text follows RTL with the icon and body copy

Testing and review

• Run npm test and confirm all tests pass

Manual verification

Run npm start

1. Default / IconEnd stories: Confirm default shows the icon on start (left in LTR); IconEnd shows the previous end-side placement with correct spacing
2. RTL: Set dir="rtl" and confirm heading text, body copy, and icon all flip with start/end
3. Zoom / magnification: At 200%+ browser zoom (and with OS screen magnification if available), confirm the expand/collapse icon remains visible and clearly associated with the accordion heading
4. Interaction: Expand/collapse panels; confirm open/closed icon states update correctly
5. Hover and forced-colors: Verify hover states and high contrast icon placement on both sides
6. Bordered variant: Confirm bordered accordion follows the theme default unless a modifier is applied

Additional notes

Banner and header accordions are unchanged. The “Here’s how you know” control and header navigation keep their existing icon placement.