fix(a11y): mark decorative star rating symbols aria-hidden (WCAG 1.4.3) - #13028
Merged
Conversation
…4.3) Star symbols (★) in StarRatingsComponent are purely decorative — the rating value is always conveyed by the adjacent text span (e.g. "4.2 (120 ratings)"). Marking them aria-hidden="true": 1. Correctly removes them from the accessibility tree (AT users hear the numeric rating, not a sequence of "star star star" characters) 2. Fixes pa11y WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail violations — HTMLCS skips aria-hidden elements for contrast checks (79 errors on search results pages, 14 on other pages) The gold color (--gold: hsl(50, 100%, 50%)) is intentionally preserved for sighted users. Changing it would require a design review. Applies to both full-size stars (book page) and small stars (search results, author pages). Applies to full stars and half-star.
mekarpeles
added
the
Theme: Accessibility
Resolve StarRatingsComponent.html conflict: master rewrote the macro to the aggregateRating/schema.org structure. Re-applied this PR's sole change (aria-hidden="true" on the decorative star spans) onto master's version.
lokesh
approved these changes
Jul 3, 2026
lokesh
left a comment
lokesh
left a comment
Collaborator
There was a problem hiding this comment.
Another narrow a11y fix, LGTM.
50 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Star symbols (★) in
StarRatingsComponent.htmlwere not marked as decorative, causing two problems:Accessibility semantics: Screen readers would announce "star star star" before the numeric rating, creating redundant/confusing output. The rating value is always in the adjacent
<span itemprop="ratingValue">(e.g. "4.2 (120 ratings)").pa11y WCAG 1.4.3 violations: Gold text (
hsl(50, 100%, 50%)) on white = ~1.4:1 contrast. pa11y reported 79 errors on search results pages and ~14 on other pages. WCAG 1.4.3 exempts purely decorative text, and HTMLCS honorsaria-hidden="true"for contrast checks.Fix: add
aria-hidden="true"to both the full star spans and the half-star span. The gold color is preserved — it's intentional for sighted users and doesn't need to change once the element is correctly marked decorative.Why not darken the gold color?
The star gold is a visual design choice (
--goldtoken). Darkening it enough to reach 4.5:1 on white would require near-amber (#7a5c00 range), which significantly changes the look. Since the stars are correctly decorative,aria-hiddenis the WCAG-compliant solution without a design regression.Test plan
npm run test:a11y— the jest-axe tests forOlPopover,OlOptionsPopover, andOlToastshould remain passing (unrelated components)Playwright regression test will be added in #12998 once the fix is verified deployed.
Related
WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail/ WCAG 1.4.3