Menu
Write well-considered semantic HTML that serves all users. Use when creating components, page structures, or reviewing markup. Emphasizes native HTML elements over ARIA. Treats proper document structure and accessibility as foundations rather than afterthoughts.
Write tests that start with acceptance criteria, then add implementation tests for robustness. Use when writing unit tests (Vitest), end-to-end tests (Playwright), visual regression tests, or accessibility tests. Emphasizes user-centric testing, semantic locators, accessibility validation, and the balance between acceptance and implementation testing.
Audit frontend codebases for security vulnerabilities and bad practices. Use when performing security reviews, auditing code for XSS/CSRF/DOM vulnerabilities, checking Content Security Policy configurations, validating input handling, reviewing file upload security, or examining Node.js/NPM dependencies. Target frameworks include web platform (vanilla HTML/CSS/JS), React, Astro, Twig templates, Node.js, and Bun. Based on OWASP security guidelines.
Provides foundational CSS design tokens (custom properties) for typography, spacing, colors, borders, z-index, and transitions. Use when setting up a base token system for a web project.
Generate Drupal/Twig component skeletons with web components and Miyagi validation. Use when user requests to create, scaffold, or add a new component at a specific path (e.g., "add component skeleton at patterns/share-button"), or when creating component files including Twig templates, CSS, JavaScript web components, JSON schemas, or mock data files.
Analyse component dependencies and usage patterns in a Drupal/Twig component library. Use when user asks to find where a component is used, check if a component can be safely removed, audit component dependencies, find components using specific properties, or analyse impact of refactoring a component.
| name | semantic-html |
| description | Write well-considered semantic HTML that serves all users. Use when creating components, page structures, or reviewing markup. Emphasizes native HTML elements over ARIA. Treats proper document structure and accessibility as foundations rather than afterthoughts. |
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.
Adding ARIA to elements that already carry the correct semantics is noise—it clutters the code, can confuse assistive technology, and obscures genuine intent:
<!-- Redundant: <ul> already has list semantics -->
<ul role="list">
...
</ul>
<!-- Redundant: alt="" already suppresses the accessible name -->
<img src="avatar.png" alt="" role="presentation" />
<!-- Redundant: aria-label duplicates visible text the AT will already read -->
<span aria-label="Most Popular">Most Popular</span>
ARIA role changes how assistive technology interprets an element. Applying a role that changes a native element's semantics introduces inconsistency—native behaviour (keyboard interaction, states, events) stays the same while the announced role changes:
<!-- Wrong: role="switch" changes what AT announces, but the element still
behaves like a checkbox. Use the native checkbox if switch toggle
semantics aren't needed, or build a proper switch widget. -->
<input type="checkbox" role="switch" />
<!-- Right: native checkbox, no role override needed -->
<input type="checkbox" />
Only add a role attribute to a native element when you deliberately need different semantics and the element's behaviour genuinely matches that role.
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 levelSkip links let keyboard and screen reader users bypass repeated navigation blocks and jump directly to meaningful content. They are required on any page with a navigation block or other repeated content before the main content.
Place skip links as the first focusable element in <body>. They can be visually hidden and revealed on focus:
<body>
<a href="#main-content" class="skip-link">Skip to main content</a>
<!-- optional additional skip targets -->
<a href="#search" class="skip-link">Skip to search</a>
<header>...</header>
<nav>...</nav>
<main id="main-content" tabindex="-1">...</main>
</body>
.skip-link {
position: absolute;
transform: translateY(-100%);
}
.skip-link:focus {
transform: translateY(0);
}
Why tabindex="-1" on <main>: The <main> element is not natively focusable. Without tabindex="-1", activating the skip link scrolls to the element but does not move keyboard focus there in all browsers. Adding tabindex="-1" makes it programmatically focusable (reachable via the skip link or .focus()) without adding it to the natural tab order.
When to add more skip links: If the page has a prominent search bar, a sidebar, or a long secondary navigation, consider skip links to those targets too. The goal is reducing the number of Tab presses to reach primary content.
Sidebar layouts need a "skip to navigation" link: When a sidebar navigation is placed away from the top of the DOM (e.g., after <main> in source order, or deep within the layout), add a skip link pointing to the <nav> so keyboard users can reach it without tabbing through all main content first.
The primary skip link should target <main>: The first skip link should always point to <main id="main-content">. Additional skip links can target other meaningful landmarks or controls—a <search> element, a sidebar <nav>, or a prominent form—depending on the page's complexity.
Why this matters: Without skip links, keyboard users must tab through every navigation item on every page load. On a nav with 12 links, that's 12 extra keystrokes — on every page.
Use 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; must contain the primary <h1> |
aside | Tangentially related content | Content removable without changing the page's main story (sidebars, ads) |
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 |
<main> must contain the primary <h1>Screen reader users often jump directly to <main>. If the page <h1> sits in a <div> between <header> and <main>, these users land after the title and lose essential context. The <h1> (and any subtitle or intro copy introducing the page) belongs inside <main>:
<!-- Wrong: h1 is outside main -->
<header>...</header>
<div class="page-header"><h1>FAQ</h1></div>
<main>
<!-- screen reader users start here, after the title -->
</main>
<!-- Right: h1 is the first heading inside main -->
<header>...</header>
<main id="main-content" tabindex="-1">
<h1>FAQ</h1>
...
</main>
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.
<aside> vs <section>The test for <aside>: Would this content make sense if it were removed from the page entirely? Would the main content still be complete?
<aside> (removing it doesn't change the main message)<section> (removing it leaves the page feeling incomplete or breaks the intended flow)When in doubt: if the content serves the primary purpose of the page, it belongs in a labelled <section>, not <aside>.
<aside> is appropriate for pull quotes—a typographic device that highlights text from the article. However, do not use <blockquote> for a pull quote drawn from the page's own content. <blockquote> signals an external or distinct quotation. For a pull quote that restates something from the same article, use <p> (or styled text) inside <aside>:
<!-- Correct: pull quote from the article's own content -->
<aside aria-label="Pull quote">
<p>
"The biggest gains came not from new features, but from removing old ones."
</p>
</aside>
<!-- Use blockquote for genuine external quotations -->
<blockquote cite="https://example.com/source">
<p>Quote from an external source.</p>
</blockquote>
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.
When using CSS ::before or ::after to inject visual separators (e.g., breadcrumb ›), browsers automatically exclude generated content from the accessibility tree—no extra markup is required. Do not try to hide it with aria-hidden: "true" as a CSS property; that is invalid and has no effect. If injecting separators via HTML (not CSS), use <span aria-hidden="true"> on the HTML element.
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.
When the same action appears multiple times on a page (e.g., "Add to cart" on each product card, "Read more" on each article), each button needs a unique accessible name so screen reader users understand which item it acts on.
Approaches (choose the simplest):
<!-- Option 1: aria-label with full context -->
<button aria-label="Add Nike Pegasus 41 to cart">Add to cart</button>
<!-- Option 2: visually hidden text -->
<button>
Add to cart
<span class="visually-hidden">Nike Pegasus 41</span>
</button>
<!-- Option 3: aria-describedby pointing to the product heading -->
<article>
<h3 id="product-42">Nike Pegasus 41</h3>
...
<button aria-describedby="product-42">Add to cart</button>
</article>
The visible label should stay as "Add to cart" (sighted users understand context from position); the accessible name adds the product name for users who navigate by button list.
aria-disabled="true" communicates disabled state but does not prevent interaction. For buttons, disabled both communicates state and suppresses clicks and keyboard activation. For links, aria-disabled="true" alone is insufficient—it still receives focus and activates. Options:
<button disabled> instead of a link when the action is truly unavailablehref attribute to prevent activation (link becomes non-interactive)keydown/click events explicitly if you must keep the element focusableFor user dropdowns, action menus, and non-modal overlays, the Popover API (popover attribute) is the preferred modern approach — not custom ARIA widget patterns.
<!-- Trigger: button with popovertarget -->
<button popovertarget="user-menu">
<img src="avatar.png" alt="" />
<span>Alice</span>
</button>
<!-- Popover: browser manages show/hide, focus, and light-dismiss -->
<ul id="user-menu" popover>
<li><a href="/profile">Profile</a></li>
<li><a href="/settings">Settings</a></li>
<li><button>Sign out</button></li>
</ul>
The browser automatically handles aria-expanded on the invoking button and aria-details when the popover isn't immediately adjacent in the DOM. No manual ARIA attributes are needed on the trigger.
Why this is better than the ARIA menu pattern:
role="menu", role="menuitem", or role="none" needed — the list remains a semantic <ul> of links and buttonsHome, End, character navigation) that are easy to implement incorrectly and unfamiliar to many usersWhen ARIA menu patterns are appropriate: Only when you are building a true application menu (menubar, menuitem, submenu) that mirrors desktop application behaviour. Most website navigation and user dropdowns should use the Popover API or a simple disclosure pattern instead.
Use for progressive disclosure:
Not a replacement for a <button>-controlled disclosure widget when ARIA roles (e.g., role="menu", role="dialog") are required. User dropdowns, menus, and modal triggers need <button> so that the correct ARIA pattern can be applied. <details>/<summary> has its own implicit semantics and cannot carry aria-expanded or menu roles meaningfully.
Use fieldset and legend for thematic grouping, not layout:
When section+heading isn't enough: For groups of form controls, <fieldset>/<legend> provides grouping context to assistive technology that <section>/<h2> does not. Screen readers announce the legend before each field in the group, giving users persistent context. Use <section>/<h2> for non-form content regions; use <fieldset>/<legend> whenever the region contains a group of inputs.
Benefits:
Legends can be visually hidden while still providing accessible names.
<search> wraps the entire search/filter interface—not just the text input. If a toolbar contains a search input plus related filter selects, they belong together in one <search> or labelled <form>:
<!-- Correct: all filter controls share a single search landmark -->
<search aria-label="Filter employees">
<label for="q">Search</label>
<input type="search" id="q" name="q" />
<label for="dept">Department</label>
<select id="dept" name="dept">
...
</select>
<label for="status">Status</label>
<select id="status" name="status">
...
</select>
<button type="submit">Apply filters</button>
</search>
<!-- Wrong: only the text input is wrapped -->
<search>
<input type="search" />
</search>
<select>
...
</select>
<!-- orphaned filter control -->
Always use a label element. No exceptions.
aria-label when a proper label element worksWhy placeholders fail:
HTML's required attribute communicates required state to assistive technology, but sighted users need a visual convention too. Always pair required with a visible indicator:
<!-- Pattern: asterisk with legend explaining it -->
<fieldset>
<legend>
Contact details <span aria-hidden="true">*</span> required fields
</legend>
<label for="name">Full name <span aria-hidden="true">*</span></label>
<input type="text" id="name" required />
</fieldset>
The aria-hidden on the asterisk prevents screen readers from announcing "asterisk"—they already get the required state from the required attribute. The legend or a page-level note explains the convention to sighted users.
When inputs have format hints or helper text, associate them with the input via aria-describedby. This ensures screen readers announce the hint after the label, giving users the context they need before typing:
<label for="email">Email address</label>
<p id="email-hint" class="hint">We'll only use this to send your receipt.</p>
<input type="email" id="email" aria-describedby="email-hint" />
Multiple associations are allowed—comma-separated IDs work for both hint and error:
<input
type="email"
id="email"
aria-invalid="true"
aria-describedby="email-hint email-error"
/>
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:
<nav> or repeated header contentrole="list" on <ul>, role="presentation" on <img alt="">)role attribute changing a native element's semantics without matching behaviouraria-label duplicating visible text (AT would read it twice or render it confusing)role="menu", role="menuitem") used for a simple user dropdown (use Popover API instead)aria-disabled on <a> elements without preventing keyboard activation<search> or <form> grouping<section>/<h2> instead of <fieldset>/<legend>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