a11y-skill

name	a11y-skill
description	WCAG 2.1 AA accessibility mandates for the frontend. Use when implementing or reviewing user interface components, form inputs, modals, or motion effects.
hints	- Always use semantic HTML tags (like button, main, nav, section) instead of styled divs. - Ensure every interactive element is keyboard-focusable with visible focus-visible indicators. - Associate all input fields with clear label tags and connect error messages via aria-describedby. - Implement focus-traps for modals and popovers, restoring focus on close. - Audit color contrast ratios and respect prefers-reduced-motion media queries for transitions.

Accessibility (A11Y) Skill

Overview

User interfaces must meet WCAG 2.1 Level AA standards. Accessibility is a first-class citizen in modern interface design, ensuring that apps are robust, accessible, and compliant for all users, including those using assistive technologies.

Workflow

• Semantic HTML Only

  • Use <button> for actions, <a> for navigation.
  • Never use div or span for interactive elements without proper ARIA roles and keyboard listeners.
  • Maintain a logical heading hierarchy (h1 -> h2 -> h3).

• Interactive Elements

  • Every interactive element must be keyboard-reachable (Tab) and operable (Enter/Space).
  • Use aria-label for icon-only buttons.
  • Never remove focus outlines without providing a high-contrast :focus-visible alternative.

• Forms & Inputs

  • Every input must have an associated <label>.
  • Use aria-describedby to link error messages to their respective inputs.
  • Use aria-invalid="true" for fields with errors.

• Visual & Motion

  • Maintain a 4.5:1 contrast ratio for normal text.
  • Respect prefers-reduced-motion for all animations.
  • Do not rely on color alone to convey status (use icons or text labels).

• Focus Management

  • Modals must trap focus while open.
  • Focus must return to the triggering element upon modal closure.

Implementation Pattern (React)

<button
  aria-label="Close modal"
  className="focus-visible:ring-2 focus-visible:ring-dd-accent"
  onClick={onClose}
>
  <XIcon aria-hidden="true" />
</button>

When to Use

• Designing, building, or refactoring user interfaces, navigation menus, and page structures.
• Creating interactive components such as modals, dropdowns, popovers, or forms.
• Adding custom styling focus effects, animations, or state indicators.

When NOT to use:

• Developing purely headless CLI tools, server backend APIs, or cron jobs that lack user interfaces.
• Running internal unit tests that do not involve DOM rendering or browser-based UI.

Common Rationalizations

Rationalization	Reality
"Accessibility is a nice-to-have we can add later."	Retrofitting accessibility is extremely expensive as it requires changing DOM structures and component behaviors. Day-one accessibility ensures robust interfaces.
"A styled div with an onClick handler is good enough."	Styled divs lack default keyboard interactivity (Tab focus, Enter/Space activation) and screen reader support, completely blocking disabled users.
"Default browser focus outlines look ugly, so I'll disable them."	Disabling focus outlines makes the app unusable for keyboard-only users. Always replace default outlines with premium custom :focus-visible styles.

Red Flags

• Interactive elements constructed from <div> or <span> without ARIA roles, tabindex="0", or keyboard event listeners.
• Using outline: none or outline: 0 in CSS without providing a visible focus alternative.
• Icon-only buttons lacking aria-label or descriptive visually-hidden text.
• Form inputs without corresponding <label> tags or using placeholder attributes as the sole label.

Verification

After completing the UI implementation, verify:

• Tab key navigation succeeds through all interactive elements in logical order.
• No keyboard focus traps exist (user can navigate into and out of all controls).
• Screen reader roles and accessibility trees are checked (using Chrome DevTools or axe audits).
• All inputs have associated labels and announce error states correctly using ARIA attributes.
• Interactive modals restrict focus to their active contents and restore focus on exit.