Summary

When users moved through the memorable date fields, every control shared one hint (mdHint), so screen readers repeated the full month/day/year instructions on each field. This change adds field-specific hints wired with aria-describedby, keeps a visible group hint for sighted users, and uses a consistent {field-id}-hint id pattern aligned with other USWDS form components.

Breaking change

This is not a breaking change.

Authors who copied the old shared mdHint markup should update to per-field hints. Default component markup is updated; no API or JS changes.

Related issue

Closes #5902

Problem statement

The memorable date component used a single group hint referenced by all three fields (month, day, year) via aria-describedby="mdHint". When a user focused each field, assistive technology announced the entire instruction block every time (dropdown + day format + year format), not guidance specific to that field.

The form test pattern (test-usa-form.twig) was also out of date: it still used the shared hint pattern and month options with leading numbers (01 - January), which USWDS removed in 3.9.0 because dual number/name labels confused screen reader users.

Solution

• Per-field hints - Each control gets its own hint id ({id}-month-hint, {id}-day-hint, {id}-year-hint) and aria-describedby pointing only at that hint.
• Group hint for sighted users - A visible overview hint remains under the legend with aria-hidden="true" so it does not duplicate announcements for assistive technology.
• Screen-reader-only field hints - Per-field hints use usa-sr-only so AT gets targeted guidance on focus without cluttering the visual layout.
• Configurable ids - Twig accepts an id variable (default memorable-date) to generate field and hint ids using the {field-id}-hint pattern used elsewhere in USWDS (file input, date picker).
• Tests - Added unit tests for markup and associations in memorable-date.spec.js.
• Storybook fixture - Updated test-usa-form.twig so Disabled/Error form stories match the component (per-field hints, month names without leading numbers, error id wired into aria-describedby when error_state is true).

Major changes

• packages/usa-memorable-date/src/usa-memorable-date.twig - per-field hints, configurable ids, group hint with aria-hidden
• packages/usa-memorable-date/src/test/memorable-date.spec.js - markup and aria-describedby tests
• packages/usa-memorable-date/src/test/template.html - unit test fixture
• packages/usa-form/src/test/test-pattern/test-usa-form.twig - Storybook form demo aligned with component

Testing and review

• Focus month field - hear month-specific hint only (not full day/year instructions)
• Focus day field - hear day format hint only
• Focus year field - hear year format hint only
• Sighted users still see group hint under legend
• Group hint is not announced when tabbing fields (VoiceOver / NVDA)
• Storybook: Patterns/Forms → DisabledFormElements and TestErrorFormElements render correctly
• Error story: fields reference both field hint and error id in aria-describedby
• Unit tests pass (packages/usa-memorable-date/src/test/memorable-date.spec.js)

References

WAI-ARIA APG

Accessible Names and Descriptions — hints associated with controls via aria-describedby
Form Patterns — labels name controls; descriptions supplement with format or instruction

WCAG 2.2

3.3.2 Labels or Instructions (Level A) - format instructions available when needed for each field
4.1.2 Name, Role, Value (Level A) - programmatic association between fields and their descriptions