USWDS - Date picker: Improve touch readout and weekday header announcements

Summary

Improves the date picker calendar for touch and iOS VoiceOver users by announcing touch-specific instructions when the calendar opens on touch-primary devices, and by fixing weekday header and date readout so VoiceOver no longer prefixes dates with ambiguous abbreviations (e.g. "Th - sept 28" or "T, T, July 14th"). Date buttons announce the full weekday (for example "Thursday, July 14, 2026"). Weekday headers stay visual only.

Breaking change

⚠️ This is a breaking change.

Date picker calendars generate different accessible names and header markup. Update tests and custom code that read those strings or that DOM.

Date button aria-label values now lead with the full weekday: Tuesday, July 14, 2026 instead of 14 July 2026 Tuesday. Names still follow the document language.

.usa-date-picker__calendar__day-of-week no longer has an aria-label for the full day name. The visible abbreviation is inside <span aria-hidden="true">. The header accessible name is empty. Read the abbreviation from that span. textContent on the th still includes it.

Related issue

Related to #5503

Problem statement

Desired: On touch devices with VoiceOver, opening the calendar should announce guidance that matches swipe/double-tap interaction. When navigating dates, users should hear the full weekday from the date button, without confusing letter prefixes from the column headers.

Actual (before): The status region always announced keyboard instructions (arrow keys, Page Up/Down) on open, even on iOS/touch. When swiping through dates, VoiceOver could read abbreviated weekday letters before the date (e.g. "T - sept 28"), or duplicate narrow letters ("T, T, July 14th") depending on header markup - behavior that differed from develop and was hard to interpret.

Consequences: Touch users received irrelevant keyboard guidance on open. iOS VoiceOver users got garbled or redundant weekday context while moving through the date grid, making the calendar harder to use with VoiceOver Gestures.

Solution

Three complementary changes in packages/usa-date-picker/src/index.js:

Touch-aware open instructions
On first calendar open, the polite status region announces touch hints on iOS and (pointer: coarse) devices (swipe, double-tap, month/year controls). Desktop/keyboard-first devices still receive the existing keyboard hints.

Weekday-first date button labels
Each date button aria-label leads with the full localized weekday, for example Thursday, July 14, 2026. That replaced 14 July 2026 Thursday.

Visual-only weekday column headers
Weekday <th> elements keep compact visible abbreviations (T, W, and so on) for layout. The abbreviation is wrapped in a span with aria-hidden="true". The header has no usa-sr-only text, no abbr, and no aria-label. The spoken weekday comes from the date button. This keeps iOS Safari + VoiceOver from reading the narrow letters in front of the date.

Why this approach: Aligns open instructions with the user's input modality. Hiding the compact header letters from assistive tech stops the ambiguous or duplicate letter prefix, while the date button still announces the full weekday. No change to role="application", dialog semantics, or tab order.

Limitations / not in scope / still TBD:

• iOS VoiceOver - reaching header controls: Swipe left/right mainly walks the date grid from the focused date, so Previous/Next month and month/year can feel hard to reach by linear swipe alone. Explore by touch (place a finger on the screen and drag) is standard iOS VoiceOver and works to find those controls. Open status hints also point users at month/year controls. Not a regression from develop.
• iOS VoiceOver - swipe up/down: Vertical swipes follow the VoiceOver rotor (e.g. Headings), not the calendar's week navigation. Users may hear "Heading not found" when the rotor is set to Headings. There is no reliable way to map up/down gestures to "move one week" while keeping normal VO gesture behavior. Left/right swipe for dates and header month controls remain the supported paths.
• Numeric keypad on text input: Not changed; APG uses plain type="text" with aria-describedby for format hint. inputmode="numeric" was considered and deferred (not APG-aligned; conflicts with mm/dd/yyyy slash entry).
• Desktop NVDA sparse announcements on open/arrow navigation: observed on APG as well; separate follow-up if needed.
• APG dialog + grid pattern: Possible future improvement for landmark/rotor behavior; out of scope here.

Major changes

• index.js
  • CALENDAR_OPEN_KEYBOARD_HINTS, CALENDAR_OPEN_TOUCH_HINTS
  • isTouchPrimaryDevice(), getCalendarOpenStatusHints()
  • renderCalendar: touch vs keyboard hints on first open
  • Date buttons: aria-label leads with the localized full weekday
  • Weekday headers: aria-hidden visible abbreviation only
• date-picker.spec.js
  • Keyboard vs touch status hints on calendar open
  • Visual-only day-of-week headers, and weekday-first date button labels
• date-picker-i18n.spec.js
  • Localized visible abbreviations, and localized weekday-first date button labels

Testing and review

• iOS Safari + VoiceOver: Open calendar: status mentions swipe, double-tap, and month controls (not arrow keys)
• iOS Safari + VoiceOver: Swipe left/right through dates: hear the button label, such as "Thursday, July 14, 2026", without a "Th -" or "T, T" prefix
• iOS Safari + VoiceOver: After open, explore by touch (drag) can reach Previous/Next month and month/year buttons
• iOS Safari + VoiceOver: Swipe up/down may say "Heading not found" depending on rotor: expected; not week navigation
• Desktop / keyboard-first: Open calendar: status mentions arrow keys (not swipe)
• Desktop keyboard: Arrow keys still move focused date; Tab still reaches header controls
• Spanish (lang="es") on document: Weekday headers show localized visible abbreviations (D, L, M, X, J, V, S). Date button labels lead with the localized full weekday. Headers have no usa-sr-only name.
• Select a date: value updates; calendar closes
• Compare header/date readout to develop on iOS: should be improved or equivalent, not regressed

Unit tests pass:

• packages/usa-date-picker/src/test/date-picker.spec.js
• packages/usa-date-picker/src/test/date-picker-i18n.spec.js

References

WAI-ARIA APG

• Date Picker Dialog Example: keyboard help via live region on open

WCAG 2.2

• 3.3.2 Labels or Instructions (Level A): touch-appropriate instructions when calendar opens on touch devices
• 4.1.2 Name, Role, Value (Level A): date button labels lead with a clear weekday, month, day, and year, and weekday headers do not add a second accessible name
• 1.3.1 Info and Relationships (Level A): compact weekday letters stay visible in the column headers, and the spoken weekday stays on the date button

Maintainer scope clarification (ryparker, September 20, 2026): The closing reference has been changed to a related reference because this PR does not settle every reported touch-navigation and keypad concern. The remaining cases stay in #5503 for current-device testing and an explicit resolution; this change does not expand the implementation scope of this PR.