---
name: a11y-semantic-html
description: >
Use this skill when the user asks about semantic HTML structure, heading hierarchy, landmark
regions, div soup, divitis, "which HTML element should I use", "semantic markup", "HTML
accessibility", "ARIA landmarks", "page structure", "section vs div", "article vs section",
"when to use aside", or is writing HTML templates, page layouts, or component markup that
requires accessible structural decisions. Also use when reviewing HTML for screen reader
compatibility or document outline correctness.
---
# Semantic HTML for Accessibility
> **Skill type: Reference.** This is teaching/pattern content — it explains *which element to use when* and *why*. It is not a scanner. For static review of existing markup, use `/a11y-review`. For runtime verification, use the `a11y-testing` skill to set up real axe.
Semantic HTML is the foundation of accessible web content. The right element provides built-in roles, keyboard behavior, and accessibility tree information that ARIA cannot fully replicate.
**Core principle:** Always use the most semantically specific native HTML element available. ARIA is a supplement for custom widgets — not a replacement for correct HTML.
---
## Document Outline and Headings
### The Heading Rule: One `
`, Sequential Order, No Skips
Headings create a machine-readable outline that screen reader users navigate by jumping between levels.
```html
Guide to Accessible Design
Color and Contrast
Text Contrast Requirements
UI Component Contrast
Keyboard Navigation
Focus Management
Guide to Accessible Design
Color and Contrast
```
**Rules:**
- One `
` per page — the primary descriptor of the page's topic
- Never skip heading levels downward (`h1` → `h3` skips `h2`)
- You CAN jump back up (`h3` → `h2` when starting a new section)
- **Never use headings for visual size.** Use CSS `font-size`. Heading level = document structure, not visual hierarchy.
### Heading Level vs. Visual Appearance (Tailwind/React pattern)
```tsx
// WRONG: Using h4 because you want small text
Card Label
// CORRECT: Use the right level, control size with CSS
Card Label
// CORRECT: If it's not actually a heading, use a
or
Card Label
```
---
## Landmark Regions
HTML5 landmark elements map directly to ARIA landmark roles. Screen reader users navigate between landmarks to skip to the content they want.
| Element | Implicit ARIA Role | Use For |
|---|---|---|
| `` | `banner` | Site header, logo, primary navigation |
| `