accessibility-principles

name	accessibility-principles
description	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.
user-invocable	false

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)