docs(Button): document built-in loading announcement#8123
Conversation
Document that Button and IconButton automatically render a visually hidden polite live-region announcement (default "Loading") when the `loading` prop is set, that the text is customizable via `loadingAnnouncement`, and that consumers should not add their own aria-live loading message to avoid duplicate announcements. Closes #7881 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
|
github-actions
Bot
added
the
integration-tests: recommended
Address review feedback from the earlier attempt (#7882): the React examples section, not just the props table, should reflect the loading behavior. Reference the existing LoadingStatusAnnouncementSuccessful and LoadingStatusAnnouncementError example stories from Button.docs.json and add narrative describing how they complement the built-in loading announcement (the button announces "Loading"; consumers announce the result). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 participant
Closes #7881
Documents the
Button(andIconButton) built-in loading announcement behavior. When theloadingprop is set, the component already renders a visually hidden, polite live-region announcement (default"Loading"), customizable via theloadingAnnouncementprop. The previous docs omitted this and instead told consumers to build their ownaria-liveloading message, which causes a duplicate announcement.This is a docs-only change (prop doc metadata, JSDoc comments, and Storybook story descriptions). No component source or runtime behavior is affected.
Note
This supersedes the earlier closed attempt in #7882. That PR's review feedback was that it updated the prop documentation but "completely missed the React examples section in the main component docs." This PR addresses that by adding narrative to the loading example stories via the standard
parameters.docs.description.storypattern (rather than rendering prose inside the story components), and by surfacing the existingLoadingStatusAnnouncement*result-announcement examples in the docs.Changelog
New
loadingandloadingAnnouncementprop entries toIconButton.docs.json.LoadingStatusAnnouncementSuccessful/LoadingStatusAnnouncementErrorexamples inButton.docs.json, with descriptions explaining how announcing the result complements the built-in loading announcement.Changed
loading/loadingAnnouncementJSDoc inButton/types.tsand their descriptions inButton.docs.jsonto explain the built-in announcement and warn against adding a separatearia-livemessage.Removed
Rollout strategy
Docs-only change — no changes to the published component source or runtime behavior, so no release is required. The
skip changesetlabel is applied.Testing & Reviewing
Review the updated prop descriptions in
Button.docs.json/IconButton.docs.json, the JSDoc intypes.ts, and the story descriptions inButton.features.stories.tsx,IconButton.features.stories.tsx, andButton.examples.stories.tsx. Confirmed againstButtonBase.tsx:loadingAnnouncementdefaults to'Loading'and renders aVisuallyHiddenAriaStatus(polite) live region whenloadingis set.Note
The narrative accessibility guidance on primer.style/product (which previously recommended a manual
aria-livemessage) lives in the separategithub/primer-docsrepo and is updated in a companion PR.Merge checklist