heading-structure
Design heading hierarchies and content structure that work for screen readers and cognitive accessibility. Use when structuring pages, articles, dashboards, forms, or any content-heavy interface. Triggers on: headings, heading hierarchy, h1 h2 h3, content structure, page structure, screen reader navigation, document outline, semantic structure, heading levels.
- Installs
- 77
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/owl-listener/inclusive-design-skills --skill heading-structure- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads heading-structure automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Heading Structure
Headings are navigation for screen reader users and cognitive signposts for everyone. A clear heading structure is the difference between content people can find and content people abandon.
Why This Matters
Screen reader users navigate by headings — they press a key to jump between headings the way sighted users scan a page visually. If your heading structure is broken, screen reader users are lost in a wall of undifferentiated text.
For people with cognitive disabilities, headings are the primary way they understand what content a page contains and where to find what they need.
Rules
One H1 Per Page
- The H1 is the page title — what this page is about
- It should match or closely relate to the page's title tag and the link that brought the user here
- Never use more than one H1 on a page
No Skipped Levels
- Go H1 → H2 → H3, never H1 → H3
- Skipping levels breaks screen reader navigation and confuses the document outline
- You can go back up: H3 → H2 is fine (starting a new section)
Headings Describe Content
- Headings are signposts, not decoration
- "Your Account Settings" not "Section 2"
- "Choose a Delivery Date" not "Step 3"
- A user should understand the page's content by reading only the headings
Headings Are Not Visual Styling
- Don't use a heading tag just to make text big or bold
- Don't skip heading tags and just style text to look like a heading
- The tag determines the structure; CSS determines the appearance
- If it looks like a heading but isn't one, screen reader users can't find it
Recommended Depth
- Most pages: H1 through H3 is sufficient
- Complex pages: H1 through H4 maximum
- If you need H5 or H6: the page is probably too complex — consider splitting it
Patterns
Article or Blog Post
H1: Article Title
H2: First Major Section
H3: Subsection
H3: Subsection
H2: Second Major Section
H3: Subsection
H2: Conclusion
Dashboard
H1: Dashboard Name
H2: Summary / Key Metrics
H2: Recent Activity
H2: Tasks
H2: Notifications
Form
H1: Form Title (e.g., "Apply for an Account")
H2: Personal Information
H2: Contact Details
H2: Preferences
H2: Review and Submit
Settings Page
H1: Settings
H2: Profile
H2: Notifications
H2: Privacy
H2: Billing
Assessment Checklist
- Exactly one H1 per page
- No skipped heading levels
- Headings describe the content beneath them
- Heading tags are used for structure, not visual styling
- A user reading only headings would understand the page
- Heading depth does not exceed H4
FAQ
What does the heading-structure skill do?
Design heading hierarchies and content structure that work for screen readers and cognitive accessibility. Use when structuring pages, articles, dashboards, forms, or any content-heavy interface. Triggers on: headings, heading hierarchy, h1 h2 h3, content structure, page structure, screen reader navigation, document outline, semantic structure, heading levels.
How do I install heading-structure?
Run npx skills add https://github.com/owl-listener/inclusive-design-skills --skill heading-structure in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/heading-structure/ (personal) or .claude/skills/heading-structure/ (project).
Which AI agents can use heading-structure?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is heading-structure safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains heading-structure?
It is published by owl-listener in owl-listener/inclusive-design-skills. It has 77 recorded installs.
More from owl-listener/inclusive-design-skills
plain-language-design
owl-listener/inclusive-design-skills
Open the skill to read its SKILL.md instructions.
keyboard-navigation
owl-listener/inclusive-design-skills
Open the skill to read its SKILL.md instructions.
cognitive-load-assessment
owl-listener/inclusive-design-skills
Open the skill to read its SKILL.md instructions.
responsive-review
owl-listener/inclusive-design-skills
Open the skill to read its SKILL.md instructions.
user-preference-respect
owl-listener/inclusive-design-skills
Open the skill to read its SKILL.md instructions.
error-prevention-recovery
owl-listener/inclusive-design-skills
Open the skill to read its SKILL.md instructions.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.