Review web page headings for skipped levels, unclear labels, and incorrect structure. Organize HTML headings around the content so people using screen readers can understand page sections and navigate between them.
Use when reviewing rendered HTML, interactive components, or design-system patterns related to Use logical heading hierarchy. Check native semantics first, then inspect keyboard behavior, focus flow, accessible names, and screen-reader output where relevant.
heading-hierarchy checks whether a web page’s headings accurately represent the structure of its content. It verifies that the page has one h1 identifying its main subject, that levels progress from h1 to h2 and h3 without skipping, and that each heading describes the content that follows. It also reviews places where heading tags are used only to change appearance.
Use it when you want screen reader users to navigate headings like a table of contents. It supports accessibility reviews of existing pages and reviews of design system patterns used across multiple pages.
The review targets the HTML actually rendered in the browser. The material includes a verification step after corrections: use browser accessibility tools or a screen reader to check the heading structure and how easily users can navigate it.
This overview was written by AI (OpenAI Codex) from the public SKILL.md. Check the original below for the exact behavior.
AI rated this skill on four points using only the contents of its SKILL.md. Stars and popularity are not taken into account.
The total counts each point as A = 25, B = 15, C = 5. Rated by AI (OpenAI Codex) as of Oct 23, 2026. Treat it as a guide and read the original before installing.
Review the instructions the agent will receive before you install.
Screen reader users navigate by headings like a table of contents—skipping levels or poor hierarchy makes content impossible to understand and navigate.
Verify pages have exactly one h1, headings follow sequential order without skipping levels (h1 → h2 → h3), and heading text clearly describes the content that follows. Use accessibility tools to generate a heading outline.
Structure headings to reflect content hierarchy. Start with h1 for the page title, use h2 for major sections, h3 for subsections. Never skip heading levels or use headings purely for visual styling.
Explain how screen reader users navigate by headings like a table of contents, and why skipped levels or missing structure forces users to work harder to understand page organization.
Review the rendered markup and interactive states that affect Use logical heading hierarchy. Flag exact elements, roles, labels, focus behavior, or keyboard interactions that violate the rule, and note how to verify the fix with browser accessibility tooling or assistive tech.
For full implementation details, code examples, and framework-specific guidance,
see references/rule.md.
Rule page: https://frontendchecklist.io/rules/accessibility/heading-hierarchy
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Create and review custom 404 pages that help visitors recover from broken or moved links through search and navigation. Check the rendered page and HTTP response so missing content returns a proper 404 status.
Audit or create a dedicated About page that explains a website’s purpose and identifies its people or organization. Review the rendered output and supporting information, including expertise and contact details, to find gaps.
Review and add automated accessibility checks for components, pages, and continuous integration workflows. Use axe-based tools to detect structural and attribute issues, while identifying checks that still need keyboard or screen reader testing.
Review sign-in, registration, multi-factor authentication, and account recovery for accessibility barriers. Find blocked paste, difficult code entry, and inaccessible backup methods, then suggest authentication paths that support password managers, autofill, or device approval.
Review form errors, success messages, and live updates so screen reader users receive important notifications. Check the HTML delivered to the browser, announcement settings, display duration, and dismissal controls, then identify specific elements that need changes.
Review HTML tables so screen reader users can understand how headers and data relate. Check header markup, table descriptions, and merged cells, then identify specific fixes and ways to verify them.