Accessibility guidelines

Never use a <div> or <span> where a semantic element exists.

ARIA patterns

ARIA attributes supplement semantic HTML — they don't replace it. Add roles, states, and properties only when no native HTML equivalent exists or when a custom component requires additional context for assistive technology.

• <aria-label> : Use when visible label text is absent or insufficient.
• <aria-describedby> : Links an element to supplementary description text.
• <aria-expanded> : Required on toggles, accordions, and disclosure widgets.
• <aria-live> : Applied to regions that update dynamically without a page reload. Use polite by default; assertive only for critical alerts.
• <role="alert"> : For time-sensitive error messages and status updates.

The first rule of ARIA: If a native HTML element or attribute achieves the required behavior, use it. ARIA is for functionality that native HTML cannot express — not a styling layer, not a redundancy, not a substitute for correct markup. Overuse of ARIA creates maintenance overhead and introduces inconsistencies that assistive technologies handle unpredictably.

Keyboard navigation

Every interactive element is reachable and operable by keyboard alone. Tab order follows the visual reading order. Focus indicators are always visible — never suppressed with <outline: none> without a custom replacement.

• Tab / Shift+Tab: Move between focusable elements.
• Enter / Space: Activate buttons and interactive controls.
• Arrow keys: Navigate within components — menus, tabs, radio groups.
• Escape: Close modals, dropdowns, and overlays. Return focus to the triggering element.

Modal dialogs trap focus within the dialog until closed. Focus returns to the element that opened the dialog.

Color and contrast

Text and interactive elements meet a minimum 4.5:1 contrast ratio against their backgrounds. Large text — 18pt regular or 14pt bold — meets a 3:1 minimum. UI components and focus indicators also meet the 3:1 threshold against adjacent colors.

Color is never the sole means of conveying information. Error states use both color and a text label or icon. Charts and data visualizations include pattern or label differentiation in addition to color coding.

Images and media

Every <img> element requires an alt attribute without exception. Whether that attribute contains descriptive text or is intentionally empty depends on a single question: does this image convey information a non-visual user would otherwise miss?

Informational images add meaning not present in surrounding text. Describe the content and function concisely. "Bar chart showing Q3 revenue by region" — not "chart image" or "image of chart." Never prefix alt text with "image of" or "photo of"; screen readers announce the element type automatically.

Redundant images duplicate information already in adjacent text. A portrait photo beside a byline, a product shot described in the copy below it — these get alt="". Repeating the caption as alt text creates the same information twice for screen reader users.

Decorative images exist for visual atmosphere only. Stock photography used as a page header, background textures, ornamental dividers — these get alt="". They contribute nothing to comprehension and should be silent.

The decorative and redundant categories both use alt="". The distinction matters for editorial judgment, not implementation.

Complex images — charts, diagrams, infographics — require two layers: a brief alt description identifying what the image is, plus a caption or linked long description covering the detail a sighted user would read from the visual itself.

Video: Captions required for all spoken content. Transcripts provided when video serves as primary content.

Audio: Transcripts required.

Forms

Every input has a visible, persistent label — not placeholder text alone. Placeholder text disappears on focus and fails contrast requirements in most browsers. Error messages identify the specific field and explain how to correct it. Required fields are marked in both the label and the input's ARIA attributes.

Testing methods

Accessibility review combines automated scanning with manual testing across real assistive technology.