Skip to content

Add accessibility documentation to Skeleton component#35759

Open
Copilot wants to merge 2 commits intomasterfrom
copilot/add-a11y-docs-skeleton
Open

Add accessibility documentation to Skeleton component#35759
Copilot wants to merge 2 commits intomasterfrom
copilot/add-a11y-docs-skeleton

Conversation

Copy link
Contributor

Copilot AI commented Feb 18, 2026

The Skeleton component lacked guidance on accessibility patterns for loading states, particularly around ARIA attributes and screen reader announcements.

Changes

Added SkeletonAccessibility.md covering:

  • Container-level aria-busy - Use on parent when loading multiple items to prevent premature screen reader interaction
  • Label placement strategies - On Skeleton itself, or on wrapper elements with nameable roles (article, group, region)
  • Unique labels - Differentiate multiple simultaneous loaders ("Loading profile", "Loading comments")
  • Live region announcement constraints:
    • Max frequency: once per 5 seconds
    • Single "loaded" announcement for all content
    • No announcements for scroll-triggered loading (avoids distraction from loaded content)

Documentation follows established v9 pattern with Do/Don't sections integrated into Storybook component docs.

Original prompt

This section details on the original issue you should resolve

<issue_title>feat: add a11y docs to Skeleton</issue_title>
<issue_description>Updating the aria-label to not be set by default was a good reminder that we need some a11y docs on how & when to label skeleton loaders, as well as other potential a11y considerations. Specifically they should cover:

  • Using aria-busy at a higher level than Skeleton if there are a lot of items simultaneously loading and the content is changing quickly enough that you don't want users to start trying to read it until it's done
  • If the skeleton is wrapped by a control with a nameable role (e.g. article, group, region, etc.), the label could go on that element
  • If there are a bunch of simultaneously loading skeleton loaders and there's any information to differentiate them, they should have unique labels
  • Do not fire loading/loaded live regions for each skeleton if there are many skeleton loaders. Loading announcements for the entire page should not be more frequent than once every 5 seconds, and the "loaded" announcement should usually happen only once for all currently-loading content. If content loads as it scrolls into view, it's possible one may not want any live region announcements, as they would just be distractions from the user reading the already-loaded content.</issue_description>

Comments on the Issue (you are @copilot in this section)


💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: dmytrokirpa <1492102+dmytrokirpa@users.noreply.github.com>
Copilot AI changed the title [WIP] Add accessibility documentation for Skeleton component Add accessibility documentation to Skeleton component Feb 18, 2026
Copilot AI requested a review from dmytrokirpa February 18, 2026 13:43
@dmytrokirpa dmytrokirpa requested a review from smhigley February 18, 2026 19:43
@dmytrokirpa dmytrokirpa marked this pull request as ready for review February 18, 2026 19:43
@dmytrokirpa dmytrokirpa requested a review from a team as a code owner February 18, 2026 19:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: add a11y docs to Skeleton

2 participants

Comments