fix(a11y): correct tip/warning/prefix semantics to prevent heading misidentification #7762
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.
Fixing #7594
Summary
This PR addresses one of the accessibility problems highlighted in Issue #7594, where .tip__prefix, .warning__prefix, .preview__prefix, and .todo__prefix are incorrectly interpreted as headings by accessibility tools (axe DevTools shows them as “heading” roles because of their visual styling).
This creates incorrect document hierarchy and fails WCAG 1.3.1 (Info and Relationships).
What does this PR change?
The previous prefix styles visually resembled headings:
font-weight: 700
font-size: getFontSize(1)
color: #000
inline appearance similar to h6
To fix this, the PR updates the styling to ensure these prefixes are treated as body text, not headings.
✔ Added display: block
✔ Added small separation (margin-bottom: 0.25em)
✔ Reduced emphasis
✔ Adjusted size + weight to match body text
✔ Updated color to meet contrast guidelines
Updated prefix styles:
display: block;
margin-bottom: 0.25em;
text-transform: capitalize;
font-weight: 600;
font-size: 0.95rem;
color: #1a1a1a;
Why this change?
Prevents accessibility tools (axe) from flagging these elements as headings
Fixes incorrect document structure
Improves clarity for screen readers
Matches the design intent (labels, not headings)
Did you add tests?
No visual tests for SCSS exist in the project.
However, changes were manually verified locally using:
Axe DevTools browser extension
Browser stylesheet inspection
Rendering in multiple Markdown tip/warning blocks
Does this introduce a breaking change?
❌ No functional breaking changes.
The change only affects documentation UI styling.
Documentation
No documentation update required — this is purely a CSS-level accessibility fix.