# Accessibility Principles

> Apply WCAG accessibility standards when building UI components, forms, interactive elements, or any user-facing interface. Covers semantic HTML, ARIA attributes, keyboard navigation, color contrast, and screen reader support.

- Skill: `irahardianto/accessibility-principles-3` (Agent Skill)
- Install (CLI): `npx skillmds@latest add irahardianto/accessibility-principles-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/irahardianto/accessibility-principles-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: irahardianto (https://skillmd.com/u/irahardianto)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/irahardianto/accessibility-principles-3

---


## Accessibility Principles

### Core Standard
Follow **WCAG 2.1 Level AA** as the baseline for all user-facing interfaces.

### Semantic HTML
- Use semantic elements (`<nav>`, `<main>`, `<article>`, `<section>`, `<button>`, `<form>`) over generic `<div>` and `<span>`
- Each page has exactly one `<h1>`, with proper heading hierarchy (h1 → h2 → h3, no skipping)
- Use `<label>` elements associated with form inputs (via `for`/`id` or wrapping)
- Use `<table>` for tabular data, never for layout

### Keyboard Navigation
- All interactive elements must be reachable via Tab key
- Focus order follows logical reading order
- Focus indicators must be visible (never `outline: none` without replacement)
- Custom components implement proper keyboard patterns (Arrow keys for menus, Escape to close modals)
- No keyboard traps — user can always Tab away from any component

### ARIA Attributes
- **First rule of ARIA:** Don't use ARIA if a native HTML element can do the job
- Use `aria-label` or `aria-labelledby` for elements without visible text labels
- Use `aria-live` regions for dynamic content updates (toasts, notifications)
- Use `role` attributes only for custom widgets that lack native semantics
- Use `aria-expanded`, `aria-controls` for disclosure patterns (dropdowns, accordions)

### Color and Contrast
- Text contrast ratio: minimum **4.5:1** against background (AA normal text)
- Large text contrast ratio: minimum **3:1** (AA large text)
- **Never use color alone** to convey information (add icons, text, or patterns)
- Support both light and dark themes with proper contrast in each

### Images and Media
- All `<img>` elements have descriptive `alt` text (or `alt=""` for decorative images)
- Videos have captions or transcripts
- Audio controls are accessible and labeled

### Forms
- Error messages are programmatically associated with inputs (`aria-describedby`)
- Required fields are indicated both visually and programmatically (`required` attribute)
- Form validation errors are announced to screen readers

### Accessibility Checklist

- [ ] All interactive elements reachable via keyboard?
- [ ] Focus indicators visible on all interactive elements?
- [ ] Semantic HTML elements used (no `<div>` buttons)?
- [ ] Heading hierarchy is correct (h1 → h2 → h3)?
- [ ] Color contrast meets AA standards (4.5:1)?
- [ ] Color is not the sole indicator of meaning?
- [ ] Images have appropriate alt text?
- [ ] Form inputs have associated labels?
- [ ] ARIA used correctly (native first)?

### Related Principles
- Core Design Principles @.claude/rules/core-design-principles.md
- Security Principles @.claude/rules/security-principles.md (XSS prevention in user content)
- Testing Strategy @.claude/rules/testing-strategy.md (accessibility testing)