# Accessibility Principles

> WCAG accessibility: semantic HTML, ARIA, keyboard nav, contrast, screen readers. For all user-facing interfaces.

- Skill: `irahardianto/accessibility-principles` (Agent Skill)
- Install (CLI): `npx skillmds@latest add irahardianto/accessibility-principles`
- Raw SKILL.md: https://api.skillmd.com/api/skills/irahardianto/accessibility-principles/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-17
- Page: https://skillmd.com/skills/irahardianto/accessibility-principles

---


## Accessibility Principles

Baseline: **WCAG 2.1 Level AA**.

### Semantic HTML
- Use `<nav>`, `<main>`, `<article>`, `<section>`, `<button>`, `<form>` over `<div>`/`<span>`
- One `<h1>` per page, proper hierarchy (no skipping)
- `<label>` associated with inputs (for/id or wrapping)
- `<table>` for data only, never layout

### Keyboard
- All interactive elements Tab-reachable
- Logical focus order
- Visible focus indicators (never `outline: none` without replacement)
- Custom components: arrows for menus, Escape for modals
- No keyboard traps

### ARIA
- First rule: don't use ARIA if native HTML suffices
- `aria-label`/`aria-labelledby` for elements without visible text
- `aria-live` for dynamic updates (toasts, notifications)
- `role` only for custom widgets lacking native semantics
- `aria-expanded`, `aria-controls` for disclosures

### Color & Contrast
- Text: min **4.5:1** (AA normal), **3:1** (AA large)
- Never color alone for meaning (add icons/text/patterns)
- Light + dark themes with proper contrast

### Images & Media
- `alt` text on all `<img>` (`alt=""` for decorative)
- Video captions/transcripts
- Accessible audio controls

### Forms
- Errors associated with inputs (`aria-describedby`)
- Required: visual + programmatic (`required`)
- Validation errors announced to screen readers

### Checklist
- [ ] Keyboard reachable
- [ ] Visible focus indicators
- [ ] Semantic HTML (no div buttons)
- [ ] Heading hierarchy correct
- [ ] Contrast AA (4.5:1)
- [ ] Color not sole indicator
- [ ] Images have alt text
- [ ] Form inputs labeled
- [ ] ARIA correct (native first)

### Related
- Core Design GEMINI.md § Core Design Principles
- Security GEMINI.md § Security Principles (XSS)
- Testing GEMINI.md § Testing Strategy (a11y testing)