Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

accessible-html

Use whenever writing, editing, or reviewing markup or UI code — HTML, JSX/TSX, Vue/Svelte/Angular templates, web components, email HTML, or CSS that affects text size, color, focus, motion, layout order, or hit area. Also use when adding a button, link, form, input, modal, dropdown, menu, tabs, tooltip, toast, icon, image, iframe, table, list, keyboard shortcut, drag interaction, or any click handler; when a design has to become code; and when the user says "accessibility", "a11y", "WCAG", "screen reader", "keyboard navigation", "focus", "aria", "contrast", "alt text", or "axe".

AlemTuzlak · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add AlemTuzlak/skills --skill accessible-html

About this skill


name: accessible-html description: Use whenever writing, editing, or reviewing markup or UI code — HTML, JSX/TSX, Vue/Svelte/Angular templates, web components, email HTML, or CSS that affects text size, color, focus, motion, layout order, or hit area. Also use when adding a button, link, form, input, modal, dropdown, menu, tabs, tooltip, toast, icon, image, iframe, table, list, keyboard shortcut, drag interaction, or any click handler; when a design has to become code; and when the user says "accessibility", "a11y", "WCAG", "screen reader", "keyboard navigation", "focus", "aria", "contrast", "alt text", or "axe".

accessible-html

Accessible markup is not a pass you make later. It is how you write the markup the first time. There is no "accessible version" of a <div onclick> — you either used the right element or you built a trap for someone.

One rule above all: use the native HTML element that already does the job. Native elements ship focus, keyboard handling, state, and a role for free. Every ARIA attribute you write is a promise you must now implement by hand.

Target WCAG 2.2 Level AA unless told otherwise. That is the normal legal and contractual bar.

Non-negotiables (every file, every time)

Do thisNever this
<button type="button"> for actions, <a href> for navigation<div onclick>, <span onclick>, <div role="button">, <a> with no href
<label for=id> or a wrapping <label> on every inputplaceholder as the only label
Every image has alt — describe it, or alt="" if decorativemissing alt; alt="image", alt="icon", filename as alt
Real accessible name on every control (visible text, or visually-hidden text beside an aria-hidden="true" icon)icon-only button with no name; empty link; title as the name
One <h1>, then h2→h3→h4 with no skipped levelheadings chosen for how big the text looks
<html lang="en">; lang on foreign phrases toono lang
Landmarks: <header> <nav> <main> <footer>; one <main>; label each <nav>div soup
<title> unique per page; skip link to <main>same title everywhere
Every <iframe> has a titleuntitled embeds
Real lists in <ul>/<ol>/<dl>; add role="list" if you set list-style: nonefake lists of divs
Text contrast ≥ 4.5:1 (≥ 3:1 large text, UI borders, icons, focus rings)grey-on-grey; "design QA will catch it"
rem for font size, including clamp() boundspx font size on :root/html/body
Visible focus ring: :focus-visible, ≥ 2px, ≥ 3:1 contrast, uses outlineoutline: none; ring only from box-shadow
DOM order == visual orderflex-direction: row-reverse, order:, or grid placement to reorder content
Interactive targets ≥ 24×24 CSS px (aim 44×44 on touch)12px icon hit areas
<table> + <caption> + <th scope> for datatables for layout; div grids for tabular data
<meta name="viewport" content="width=device-width, initial-scale=1">user-scalable=no, maximum-scale=1
Unique id per elementduplicate ids (silently breaks for and aria-labelledby)
Single-character shortcut (j, /, x) ships with an off switch, a remap, or focus scopingbare single-key shortcuts with no escape hatch (WCAG 2.1.4, Level A)

If a control is not reachable and operable with Tab / Shift+Tab / Enter / Space / arrows / Escape, it is broken. A keyboard user cannot use your feature at all — that is not a "nice to have".

Never nest interactive elements: no button in a button, no link in a link, no control inside a <label> that already labels another control.

The four rules of ARIA

  1. Native element first. Always. <button> over role="button".
  2. Do not change native semantics. Wrap instead: <div role="tab"><h3>…</h3></div>, not <h3 role="tab">.
  3. Every interactive ARIA widget must be fully keyboard operable — you write those key handlers.
  4. Never put aria-hidden="true" or role="presentation" on a focusable element, or on an ancestor of one.

No ARIA is better than bad ARIA. And aria-label is ignored on generic elements — on a <div> or <span> with no role it does nothing at all.

Naming things

  • Visible text is the best accessible name. Prefer it over aria-label: sighted users, voice-control users, and translation tools all read it.
  • Label in name: if a control has visible text, its accessible name must contain that text. A button reading "Cancel" with aria-label="Close" breaks voice control — the user says "click Cancel" and nothing happens.
  • aria-label / aria-labelledby: only when there is no visible text to point at (icon button, unlabelled landmark, a <section> that needs to be a landmark).
  • aria-describedby for hints. aria-errormessage + aria-invalid="true" for errors.
  • title is not an accessible name. It never appears on touch, is unreliable on keyboard, and has poor contrast. Use a real label.
  • Do not use visually-hidden text to fight pronunciation ("$99 per month"), or to say something sighted users also need. If the text is needed, show it.
  • Same link text to different destinations is a bug. "Read more about accessible design", not "Read more". Say when a link opens a new tab.

Do not surprise the user

  • No change of context on focus or on input. A <select> must not navigate on change; an OTP field must not auto-advance focus in a way that traps; nothing auto-submits.
  • No autofocus. No stealing focus on load.
  • Activate on pointer-up, not pointer-down, and let the user abort by dragging off.
  • Session timeouts must be extendable, and warn before expiring.
  • Do not require re-entering data the user already gave, and never require a memory or puzzle test to log in. Do not block paste in password fields.
  • Errors: text, not colour alone. Say what to do. Move focus to the error summary or first bad field.

Read-first gate

**If your task mat

Read the complete source ↗