fix(a11y): stop docset grids skipping a heading level - #12594
Open
Conversation
Member
Author
|
This pull request is part of a Mergify stack:
|
This was referenced Aug 28, 2026
Contributor
Merge Protections🔴 3 of 7 protections blocking · waiting on 👀 reviews and ⛓️ dependency
🔴 ⛓️ Depends-On RequirementsWaiting for
This rule is failing.Requirement based on the presence of
🔴 👀 Review RequirementsWaiting for
This rule is failing.
🔴 🔎 ReviewsWaiting for
This rule is failing.
Show 4 satisfied protections🟢 🤖 Continuous Integration
🟢 Enforce conventional commitMake sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
🟢 📕 PR description
🟢 🚦 Auto-queueWhen all merge protections are satisfied, this pull request will be queued automatically. |
There was a problem hiding this comment.
Pull request overview
Adjusts Docset card title markup to preserve a correct heading hierarchy in docset grids, improving the document outline for screen readers and other tooling.
Changes:
- Default
Docsetcard titles toh3(instead ofh4) and make the heading level configurable via aheadingLevelprop. - Set
headingLevel={4}for the CI Insights “Components” grid, since it is nested under an###heading.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| src/content/docs/ci-insights.mdx | Sets headingLevel={4} for the “Components” grid docset cards to avoid outline/structure issues under an ### heading. |
| src/components/DocsetGrid/Docset.astro | Introduces configurable heading level for card titles and updates styling to support both h3 and h4. |
Suppressed comments (2)
src/components/DocsetGrid/Docset.astro:33
- The card title is rendered as an h3/h4, but it contains a wrapper for the icon. Headings should only contain phrasing content; a block-levelinside a heading is invalid HTML and can confuse accessibility tooling. Use a (or other phrasing element) for the icon wrapper instead.
This issue also appears on line 34 of the same file.
{productIconName && (
<div class="docset-icon" data-product={productKey}>
<ProductIcon name={productIconName} />
</div>
)}
src/components/DocsetGrid/Docset.astro:38
- The h3/h4 heading contains a wrapper for the lucide/simple-icons icon. Ainside a heading is invalid HTML (headings should contain phrasing content only). Use a wrapper (and keep the same class/data attributes) to preserve styling while keeping markup valid.
{!productIconName && icon && (
<div class="docset-icon" data-product={productKey}>
<Icon name={icon} />
</div>
)}
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
jd
force-pushed
the
devs/jd/agentic-readiness/stop-docset-grids-skipping-heading-level--e01f4c2b
branch
from
August 28, 2026 14:37
4244760 to
76b1d20
Compare
Member
Author
Revision history
|
Docset cards rendered their title as `h4`. Almost every grid sits directly under an `##`, so the outline jumped h2 to h4 — including on the homepage, whose whole body is the "Products" grid. Screen readers and anything parsing the document outline read that as a missing level. Default the card heading to `h3` and make it a prop, because one grid does belong at h4: the "Components" grid in `ci-insights.mdx` is nested under an `### Components`, where h3 would make the cards siblings of their own section heading instead of children. Change-Id: Ie01f4c2b03f1f2b7f798ae89b056135a5b00800e
jd
force-pushed
the
devs/jd/agentic-readiness/stop-docset-grids-skipping-heading-level--e01f4c2b
branch
from
August 28, 2026 15:09
76b1d20 to
0ac1500
Compare
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
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.
Docset cards rendered their title as
h4. Almost every grid sits directlyunder an
##, so the outline jumped h2 to h4 — including on the homepage,whose whole body is the "Products" grid. Screen readers and anything parsing
the document outline read that as a missing level.
Default the card heading to
h3and make it a prop, because one grid doesbelong at h4: the "Components" grid in
ci-insights.mdxis nested under an### Components, where h3 would make the cards siblings of their own sectionheading instead of children.
Depends-On: #12593