Write well-considered semantic HTML that serves all users. Use when creating components, page structures, or reviewing markup. Emphasizes native HTML elements over ARIA...
Write HTML that conveys meaning, serves all users, and respects the web platform.
Use this skill when:
Design content is idealized. Real content is messy. Always account for:
Build components that handle real-world content gracefully, not just what looks good in design tools.
Before diving into individual components, consider the full page structure. This allows you to:
Follow the first rule of ARIA: if a native HTML element provides the semantics and behaviour you need, use it instead of adding ARIA to a generic element.
Red flag: High div count combined with high ARIA count on non-complex components signals reaching for patches rather than foundations.
Visual styling and semantic meaning are related but not coupled. CSS classes bridge the gap:
.u-Heading-XXL for consistent visual treatment regardless of semantic levelUse landmark elements to convey page structure:
| Element | Use When | Notes |
|---|---|---|
header |
Page or section header | Can appear multiple times in different contexts |
footer |
Page or section footer | Contact info, copyright, related links |
nav |
Navigation sections | Must be labelled; avoid "navigation" in the label (screen readers announce this) |
main |
Primary content | Only one per page |
aside |
Tangentially related content | Sidebars, pull quotes, advertising |
search |
Search functionality | Contains the search form, not the results |
form |
User input | Only becomes a landmark when labelled via aria-labelledby or aria-label |
article |
Self-contained content | Would make sense syndicated or standalone |
section |
Thematic grouping | Only becomes a landmark when labelled |
A section without an accessible name behaves like a div semantically. When using section:
aria-labelledbysection is the right choiceThink beyond blog posts. Use article for any self-contained content that would make sense on its own:
Test: Would this content make sense if extracted and placed elsewhere with no surrounding context?
Often misunderstood. From the HTML specification:
The address element represents the contact information for its nearest article or body element ancestor.
Use for contact information about the author or owner—not for generic postal addresses. For postal addresses, use a standard <p> or structured markup appropriate to the context.
Maintain a logical heading structure:
h1 per page (typically the main title)For reusable components containing headings:
Example pattern:
Card (generic) → heading level configurable, default h3
└─ ProductCard (specific) → inherits config, may set default based on known context
└─ Used in section with h2 → heading level set to h3
Sometimes text looks like a heading but shouldn't be one semantically. Use CSS classes to apply heading-like styling without affecting document outline:
<p class="u-Heading-L">This looks like a heading</p>
Lists are most useful when knowing the number of items helps the user:
Questions to ask:
| Type | Use When | Example |
|---|---|---|
ul |
Unordered collection where count matters | Nav items, search results |
ol |
Sequential steps or ranked items | Recipes, instructions, top-10 lists |
dl |
Term-description pairs | Glossaries, metadata, key-value pairs |
menu |
Toolbar commands | Action buttons, not navigation |
Ordered list attributes: Use reversed for countdown-style lists (e.g., a top 10 listed from 10 to 1). Use start to begin numbering from a specific value. Both are native HTML—no JavaScript required.
Often overlooked or confused with details/summary. Use dl for:
Note: A single dt can have multiple dd elements for multiple related descriptions.
Traditional rule: Buttons do things, links go places.
Progressive enhancement lens: If a URL provides a meaningful fallback when JavaScript fails, a link is valid even for action-like interactions.
| Interaction | Default Choice | Consider Link When |
|---|---|---|
| Show more content | button |
URL params could load the content server-side |
| Toggle view (grid/list) | button |
URL could preserve view preference |
| Copy to clipboard | button |
Copied content is a shareable URL |
| Tab selection | button |
URL could load specific tab content |
Key question: What happens when JavaScript fails? If a URL provides graceful degradation, a link may be the better choice.
Use for progressive disclosure:
Not a replacement for proper heading structure or definition lists.
Use fieldset and legend for thematic grouping, not layout:
Benefits:
Legends can be visually hidden while still providing accessible names.
Always use a label element. No exceptions.
aria-label when a proper label element worksWhy placeholders fail:
Current best practice (due to browser support gaps with aria-errormessage):
aria-invalid="true" on the invalid inputaria-describedbyaria-live on the error container<label for="email">Email</label>
<input
type="email"
id="email"
aria-invalid="true"
aria-describedby="email-error"
/>
<p id="email-error" class="error">
Enter a valid email address, like name@example.com
</p>
Use a table when data has meaningful relationships in both dimensions:
dl)Always include:
caption — Describes the table's purposethead, tbody, tfoot — Structural groupingth with scope — Identifies header cells and their directionIn order of preference:
Note: Modern browsers (including Safari) no longer strip table semantics when applying display: grid or display: flex, opening new responsive possibilities.
When reviewing markup, look for:
See the references/ directory for detailed guidance on specific topics:
element-decision-trees.md — Quick decision frameworks for element selectionheading-patterns.md — Component heading patterns and configuration strategies
