Provides web accessibility best practices for semantic HTML, ARIA, keyboard navigation, color contrast, and screen reader patterns. Use when building UI components, reviewing accessibility, or when user mentions 'a11y', 'accessibility', 'ARIA', 'screen reader', 'keyboard navigation', 'WCAG'.
Provides web accessibility best practices for semantic HTML, ARIA, keyboard navigation, color contrast, and screen reader patterns. Use when building UI components, reviewing accessibility, or when user mentions 'a11y', 'accessibility', 'ARIA', 'screen reader', 'keyboard navigation', 'WCAG'.
type
skill
category
patterns
status
stable
origin
tibsfox
modified
false
first_seen
"2026-02-07T00:00:00.000Z"
first_path
examples/accessibility-patterns/SKILL.md
superseded_by
null
Accessibility Patterns
Reference guide for building inclusive, accessible web interfaces that comply with WCAG 2.1 AA standards.
Core Principles (POUR)
Principle
Meaning
Key Question
Perceivable
Content is available to all senses
Can users see, hear, or read it?
Operable
Interface works with all input methods
Can users navigate with keyboard only?
Understandable
Content and UI are predictable
Can users understand and recover from errors?
Robust
Works across assistive technologies
Does it work with screen readers and future tools?
Semantic HTML Reference
Use the right element for the job. Semantic HTML provides accessibility for free.
Document Structure
<header><!-- Site/section header, landmarks for screen readers --><nav><!-- Navigation links, announced as "navigation" --><main><!-- Primary content, skip-to target --><article><!-- Self-contained content (blog post, card) --><section><!-- Thematic grouping with heading --><aside><!-- Tangentially related (sidebar, callout) --><footer><!-- Site/section footer -->
Interactive Elements
Need
Use
NOT
Clickable action
<button>
<div onclick> or <span onclick>
Navigation link
<a href="...">
<div onclick="navigate()">
Text input
<input type="text">
<div contenteditable>
Selection
<select> + <option>
Custom dropdown without ARIA
Toggle
<input type="checkbox">
<div class="toggle">
Form group
<fieldset> + <legend>
<div class="form-group">
Heading Hierarchy
<!-- CORRECT: Logical hierarchy, no skipped levels --><h1>Page Title</h1><h2>Section</h2><h3>Subsection</h3><h3>Subsection</h3><h2>Another Section</h2><!-- WRONG: Skipped levels, multiple h1, heading for styling --><h1>Title</h1><h1>Another Title</h1><!-- Only one h1 per page --><h4>Jumped from h1 to h4</h4><!-- Skipped h2, h3 -->
ARIA Roles, States, and Properties
ARIA supplements HTML semantics. The first rule of ARIA: do not use ARIA if native HTML provides the semantics.
Landmark Roles
Most of these are already implied by semantic HTML.
For content that updates dynamically (notifications, status messages, chat).
<!-- Polite: announced after current speech finishes --><divaria-live="polite"aria-atomic="true">
3 items in your cart
</div><!-- Assertive: interrupts current speech (use sparingly) --><divaria-live="assertive"role="alert">
Error: Payment failed. Please try again.
</div><!-- Status: polite + role=status (form feedback, progress) --><divrole="status">
Saving... Done!
</div>
Politeness
When to Use
polite
Status updates, cart counts, non-urgent info
assertive
Errors, warnings, time-sensitive alerts
off
Disable announcements (default)
Keyboard Navigation
Focus Management Rules
Rule
Implementation
All interactive elements are focusable
Use native HTML elements or tabindex="0"
Focus order matches visual order
Source order = visual order, avoid CSS reordering
Focus is visible
Never outline: none without a visible alternative
No keyboard traps
User can always Tab away (except modal dialogs)
Skip links available
First focusable element skips to main content
Skip Link Pattern
<!-- First element in <body>, visually hidden until focused --><ahref="#main-content"class="skip-link">
Skip to main content
</a><!-- ... navigation ... --><mainid="main-content"tabindex="-1"><!-- Content starts here --></main>
Arrow keys to navigate, Enter to select, Escape to close
Dialogs
Escape to close, Tab trapped inside, focus on close or first element
Dropdowns
Arrow keys to navigate, Enter to select, Escape to close
Tab Trap for Modals
functiontrapFocus(dialog) {
const focusable = dialog.querySelectorAll(
'a[href], button:not([disabled]), input:not([disabled]), ' +
'select:not([disabled]), textarea:not([disabled]), [tabindex="0"]'
);
const first = focusable[0];
const last = focusable[focusable.length - 1];
dialog.addEventListener('keydown', (e) => {
if (e.key !== 'Tab') return;
if (e.shiftKey) {
if (document.activeElement === first) {
last.focus();
e.preventDefault();
}
} else {
if (document.activeElement === last) {
first.focus();
e.preventDefault();
}
}
});
first.focus();
}
Color Contrast Requirements
WCAG 2.1 AA Minimums
Content Type
Minimum Ratio
Example
Normal text (<18px / <14px bold)
4.5:1
#595959 on #FFFFFF = 7:1
Large text (>=18px / >=14px bold)
3:1
#767676 on #FFFFFF = 4.5:1
UI components & graphical objects
3:1
Borders, icons, focus indicators
Decorative / logos
No requirement
Brand logos are exempt
Testing Contrast
# Browser DevTools: Inspect element > Color picker shows ratio# Chrome: Lighthouse > Accessibility audit# Firefox: Accessibility Inspector > Check for issues
Do Not Rely on Color Alone
<!-- BAD: Color is the only indicator --><spanstyle="color: red;">Error in this field</span><!-- GOOD: Color + icon + text --><spanclass="error"><svgaria-hidden="true"><!-- error icon --></svg>
Error: Email address is required
</span><!-- BAD: Link distinguished only by color --><p>Read our <spanstyle="color: blue;">terms of service</span></p><!-- GOOD: Link has underline (and color) --><p>Read our <ahref="/terms">terms of service</a></p>
Form Accessibility
Labels and Instructions
<!-- Every input MUST have a label --><labelfor="email">Email address</label><inputtype="email"id="email"name="email"requiredaria-describedby="email-help"><pid="email-help">We will never share your email.</p><!-- Group related fields --><fieldset><legend>Shipping Address</legend><labelfor="street">Street</label><inputtype="text"id="street"name="street"><labelfor="city">City</label><inputtype="text"id="city"name="city"></fieldset>
Error Messages
<!-- Associate error with input --><labelfor="password">Password</label><inputtype="password"id="password"name="password"aria-invalid="true"aria-describedby="password-error"><pid="password-error"role="alert">
Password must be at least 8 characters.
</p>
Required Fields
<!-- Use both native and visual indicators --><labelfor="name">
Full name <spanaria-hidden="true">*</span></label><inputtype="text"id="name"name="name"requiredaria-required="true"><!-- Explain the asterisk at the form top --><p>Fields marked with <spanaria-hidden="true">*</span><spanclass="sr-only">asterisk</span> are required.</p>
Component Patterns
Accessible Button
<!-- Native button (best) --><buttontype="button"onclick="doAction()">
Save Changes
</button><!-- Icon-only button (needs label) --><buttontype="button"aria-label="Close dialog"><svgaria-hidden="true"focusable="false"><!-- X icon SVG --></svg></button><!-- Loading state --><buttontype="button"aria-disabled="true"aria-busy="true"><spanaria-hidden="true">Saving...</span><spanclass="sr-only">Saving changes, please wait</span></button>
<dialogid="confirm-dialog"aria-labelledby="dialog-title"aria-describedby="dialog-desc"><h2id="dialog-title">Confirm Deletion</h2><pid="dialog-desc">
This action cannot be undone. Are you sure?
</p><div><buttontype="button"autofocus>Cancel</button><buttontype="button"class="danger">Delete</button></div></dialog>
<!-- Provide context that's visually obvious but not to screen readers --><button><svgaria-hidden="true"><!-- trash icon --></svg><spanclass="sr-only">Delete item: Running Shoes</span></button>
Image Accessibility
Image Type
Alt Text Rule
Example
Informative
Describe the content
alt="Bar chart showing 40% growth in Q3"
Decorative
Empty alt
alt="" (NOT omitted, empty string)
Functional (in link/button)
Describe the action
alt="Search" on a magnifying glass icon
Complex (chart/diagram)
Brief alt + long description
alt="Sales data" aria-describedby="chart-desc"
Text in image
Reproduce the text
alt="Sale: 50% off all items"
<!-- Informative image --><imgsrc="team.jpg"alt="Our team of 12 engineers at the 2024 retreat"><!-- Decorative image (empty alt, not missing) --><imgsrc="divider.png"alt=""><!-- Complex image with long description --><imgsrc="architecture.png"alt="System architecture diagram"aria-describedby="arch-desc"><divid="arch-desc"><p>The system consists of three layers: a React frontend
communicating via REST API with a Node.js backend,
which connects to a PostgreSQL database...</p></div>
Common Anti-Patterns
Anti-Pattern
Problem
Fix
<div onclick> as button
Not focusable, no keyboard, no role
Use <button>
Missing alt on <img>
Screen reader reads filename
Add descriptive alt or alt=""
outline: none without replacement
Focus indicator invisible
Use custom :focus-visible styles
Color-only indication
Invisible to colorblind users
Add icon, text, or pattern
Auto-playing media
Disorienting, blocks screen readers
Require user interaction to play
tabindex > 0
Unpredictable focus order
Use 0 or -1 only
Missing form labels
Input purpose unknown to screen readers
Add <label> with for attribute
Using title as primary label
Not reliably announced
Use aria-label or visible label
Placeholder as label
Disappears on input, low contrast
Use visible <label> element
Mouse-only interactions (hover)
Inaccessible without mouse
Support focus and keyboard too
Missing language attribute
Wrong pronunciation by screen reader
Add lang="en" on <html>
ARIA overuse
More fragile than native HTML
Use semantic HTML first
Testing Checklist
Automated Testing
Run axe-core or Lighthouse accessibility audit
Validate HTML (invalid HTML breaks assistive tech)
Check color contrast ratios with automated tools
Run ESLint with eslint-plugin-jsx-a11y (React projects)
Manual Testing
Navigate entire page with keyboard only (Tab, Enter, Escape, Arrows)
Verify visible focus indicator on all interactive elements
Test with screen reader (VoiceOver, NVDA, or JAWS)
Zoom to 200% -- content reflows, nothing is cut off
Test with browser in high-contrast mode
Verify all images have appropriate alt text
Check that page has logical heading hierarchy
Confirm form errors are announced and associated with inputs
Test all modals/dialogs for focus trap and Escape to close
