Web Accessibility (WCAG 2 AA))

---
name: web-accessibility
description: Apply WCAG 2 Level AA accessibility standards to design systems, UI components, and web pages ,  contrast math with a runnable validator, design-token patterns that make color accessible by construction, typography and focus-state rules, and a semantics checklist.
license: MIT
metadata:
  author: raunakkathuria
  version: "1.0"
---

# Web Accessibility (WCAG 2 AA)

## intent

build accessibility into the design system from the token layer up, not audit it in after launch. make interfaces conform to WCAG 2.2 Level AA by validating color contrast as math (not judgment), locking in accessible token patterns before any component uses them, and checking semantics and keyboard navigation at the page level. use this skill when building or reviewing UI, choosing colors or type for a brand or design system, setting up design tokens, wiring accessibility checks into a build pipeline, or when the user mentions accessibility, a11y, WCAG, contrast, screen readers, or keyboard navigation.

## inputs

- **Node.js** ≥14 (for the contrast validator script)
- **design token config** (JSON or CSS Custom Properties defining color pairs, typography scales, and spacing)
- **UI components or pages** to validate (HTML, component code, design mockups)
- **design system** or style guide (existing palette, typography rules, focus states)
- **CI/build pipeline** (optional, for automating contrast checks on every commit)

**external connections / setup:**
- no external APIs required. all checks run locally.
- contrast validator script (included): `scripts/check-contrast.mjs` (Node.js, no dependencies beyond Node stdlib).
- optional: axe DevTools, Lighthouse CI, or NVDA/VoiceOver for manual screen-reader testing (not required for this skill, but recommended for full conformance).

## procedure

### phase 1: validate color tokens (top-down)

**step 1:** gather all foreground/background color pairs that will render as text or meaningful graphics (icons, chart marks, input borders, focus indicators).

- *input:* design tokens (CSS, JSON, or Figma variables); list of theme variants (light, dark, high-contrast).
- *output:* a map of all fg/bg pairs per theme.

**step 2:** run the contrast validator script on each pair.

- *input:* fg color (hex or rgb), bg color (hex or rgb), minimum ratio (4.5 for normal text, 3 for large text or non-text graphics), human-readable label.
- *command:* `node scripts/check-contrast.mjs --pair "#0f766e,#ffffff,4.5,primary text on white"`
- *output:* pass/fail verdict; computed contrast ratio (e.g. "5.2:1, PASS").

**step 3:** batch-validate a whole palette from a JSON file.

- *input:* JSON file with structure: `{ "theme": { "pairs": [{"fg": "#...", "bg": "#...", "min": 4.5, "label": "..."}, ...] } }`
- *command:* `node scripts/check-contrast.mjs contrast-pairs.json`
- *output:* per-pair pass/fail; summary report; exit code non-zero if any fail.

**step 4:** wire the validator into CI/build.

- *input:* build script (`npm run build`, GitHub Actions, GitLab CI, etc.) and the JSON palette file.
- *action:* add `node scripts/check-contrast.mjs contrast-pairs.json || exit 1` to your pre-commit hook, build step, or CI job.
- *output:* build fails if any contrast pair fails; passes only if all pairs pass.

### phase 2: design token patterns that guarantee accessibility

**step 5:** split fill roles from text roles for brand colors.

- *input:* a vibrant brand color (e.g. teal `#14b8a6`).
- *action:* define two tokens: one for fills/borders/focus rings (`--color-primary`), one for text on light backgrounds (`--color-primary-text`). the text version must be darker (same hue family, darker value).
- *pattern:*
  ```css
  --color-primary:      #14b8a6;  /* fills, borders, focus rings ,  never text on light */
  --color-primary-text: #0f766e;  /* dark enough to be text (≥4.5:1 on white) */

• output: two tokens per brand color; both pre-validated for their use cases.

step 6: theme-tune semantic colors (success, warning, error).

• input: semantic intent (success, warning, error) and multiple theme targets (light, dark, high-contrast).
• action: define separate tokens per theme instead of one global set. use bright ramps (e.g. #f59e0b amber, #ef4444 red) for dark themes; use darker ramps (e.g. #b45309, #dc2626) for light themes.
• pattern:

  /* light theme */
  --color-success: #16a34a;
  --color-warning: #b45309;
  --color-error: #dc2626;
  
  /* dark theme */
  --color-success: #86efac;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  

• output: semantic colors that pass 4.5:1 in every theme without needing to remember which is which.

step 7: establish a floor for subtle text (placeholder, hint, caption).

• input: current palette; list of text levels (body, subtle, caption, placeholder).
• action: identify the lightest gray that meets 4.5:1 on white (around #767676 or darker). use this as the floor for all text; do not use mid-grays like #9ca3af for body or hint text.
• output: a --color-text-subtle or similar token locked at or below the AA floor.

phase 3: typography and scaling

step 8: define font sizes and line heights in relative units.

• input: design system typographic scale (px values).
• action: convert all font sizes to rem or em, based on a 16px root (html { font-size: 1rem }). set line-height ≥1.5 for body copy; paragraph spacing larger than line spacing.
• pattern:

  html { font-size: 1rem; } /* 16px base, not 62.5% tricks */
  
  body {
    font-size: 1rem;
    line-height: 1.6;
  }
  
  h1 {
    font-size: 2.5rem;
    line-height: 1.2;
  }
  

• output: stylesheet that survives browser zoom and text-resize to 200% without content loss.

step 9: pair color with additional cues (icon, weight, underline, text).

• input: any element where meaning is conveyed by color (links in prose, status indicators, chart lines).
• action: add a non-color cue (e.g. underline on links, icon on status badges, dashed vs. solid line).
• output: visual meaning survives grayscale and color-blind views.

phase 4: interactive states and focus

step 10: add :focus-visible with 3:1 contrast.

• input: every interactive element (<button>, <a>, <input>, etc.).
• action: define :focus-visible { outline: 2px solid <focus-color>; outline-offset: 2px; }. validate the focus color against the surrounding surface (e.g. blue outline on a white page = 3:1 minimum).
• pattern:

  button:focus-visible {
    outline: 2px solid #0f766e;
    outline-offset: 2px;
  }
  

• output: every interactive element visibly focused; outline never removed without a replacement.

step 11: validate hover and active colors.

• input: all state colors (hover, active, disabled, focus).
• action: add each state color pair to the contrast config; validate before shipping. a link that darkens on hover must pass both in resting state and in hover state.
• output: state colors added to contrast-pairs.json and validated in CI.

step 12: enforce target size ≥24×24 CSS px.

• input: all clickable/tappable elements (buttons, links, icon buttons, checkboxes).
• action: apply min-width/min-height or padding to ensure 24px minimum on all sides. use 44px for primary controls and mobile targets.
• pattern:

  button, a, input[type="checkbox"] {
    min-width: 24px;
    min-height: 24px;
    /* or use padding to achieve this */
  }
  

• output: every interactive target ≥24×24 px; no motor-control failures.

step 13: gate animation behind prefers-reduced-motion.

• input: any non-essential animation (transitions, keyframe animations).
• action: wrap in @media (prefers-reduced-motion: no-preference) { animation: ... } or provide a toggle.
• pattern:

  @media (prefers-reduced-motion: no-preference) {
    button { transition: background-color 200ms; }
  }
  

• output: animations disabled by default; enabled only if user has not requested reduced motion.

phase 5: semantics and keyboard navigation

step 14: run the semantics checklist per component and page.

• input: component or page HTML/code.
• action: for each item, verify:
  • images: every <img> has alt text that describes what the image does in context; decorative images use alt="".
  • headings: page has exactly one <h1>; heading levels do not skip (h1 → h2/h3, not h1 → h4); heading hierarchy matches content structure.
  • real elements: buttons, links, and form controls use semantic HTML (<button>, <a href>, <label for>, <input>), not styled <div>s.
  • form labels: every input has a <label> with matching for attribute or wrapped around the input; error messages identified by text and visually, not color alone.
  • keyboard navigation: all interactive elements reachable via Tab; Tab order logical (left-to-right, top-to-bottom, or per content flow); no keyboard traps (element focus cannot be escaped with Tab or arrow keys); skip link on page-level navigation.
  • state marking: current page marked with aria-current="page"; expanded/collapsed state marked with aria-expanded; disabled buttons marked disabled or aria-disabled.
  • page metadata: <html lang="en"> (or appropriate language code); <title> descriptive and unique per page.
• output: checklist pass/fail per item; list of fixes required.

step 15: keyboard walk-through.

• input: built component or page; browser; keyboard (no mouse).
• action: start at the page top. use Tab to navigate forward, Shift+Tab backward, arrow keys for lists/menus, Enter/Space for buttons, Escape for modals. verify every interactive element is reachable, operable, and that focus returns to a sensible location after closing a modal or dropdown.
• output: walk-through report: all reachable, all operable, no focus traps.

decision points

if color fails 4.5:1 on white:

• darken the color (stay in the same hue family) until it passes, or
• pair it with a lighter background (e.g. light teal fill instead of white), or
• use it for fills/icons only, not text on light backgrounds.

if a semantic color (success, warning, error) fails in light theme:

• do not brighten it to pass (bright reds/ambers fail harder on white). instead, define a separate darker token for the light theme (e.g. --color-error-light: #dc2626) and use it conditionally.

if focus outline is hard to see against the background:

• try a higher-contrast color or a thicker outline (3px instead of 2px), or
• add a contrasting inner border (outline plus box-shadow) to make the focus ring "pop".

if a page element is not keyboard-reachable:

• ensure it is a semantic interactive element (<button>, <a href>, <input>, etc.) or has tabindex="0", or
• use JavaScript to make a <div> behave as a button (role="button", keypress handler for Enter/Space), but prefer semantic HTML.

if the user mentions "we'll fix accessibility later":

• remind them that fixing a token now fixes every component that uses it (one change, infinite scale). fixing accessibility after launch means fixing every page independently (one change per page, forever). build it in.

if automated checkers pass but the product still feels broken:

• automated tools catch roughly one-third to one-half of WCAG failures (the mechanical ones: contrast, focus visibility, heading structure). keyboard walk-throughs and screen-reader testing (VoiceOver on macOS/iOS, NVDA on Windows) catch the rest (content semantics, tab order, state announcements, alt text quality). do both.

if contrast validators conflict (e.g. different tools give different ratios for the same color):

• use the WCAG formula (relative luminance, then ratio = (L + 0.05) / (l + 0.05)). implement it once (the included script does). trust your script, not eyeballing or tools with different math.

output contract

tokens validated and locked:

• JSON file (contrast-pairs.json or equivalent) with all fg/bg pairs per theme, each with computed contrast ratio and pass/fail status.
• CSS file defining all color tokens, typography tokens, and state tokens, with no pair falling below the minimum for its use case.
• CI/build job that runs contrast checks and exits non-zero on failure.

components with accessibility guarantees:

• focus-visible outline on all interactive elements, with 3:1 contrast verified.
• target size ≥24×24 CSS px on all clickable/tappable elements.
• hover/active state colors validated for contrast.
• animation gated behind prefers-reduced-motion.

pages passing semantics:

• one <h1> per page; heading order correct; real semantic elements throughout.
• every image with appropriate alt text; every input with a label.
• full keyboard walk-through complete with no unreachable or trapped elements.
• <html lang>, page <title>, and aria-current="page" (or equivalent state markers) in place.

sign-off artifacts (optional but recommended):

• accessibility checklist (per component, per page) with sign-off date.
• keyboard walk-through report (manual; list of tested elements and outcomes).
• screen-reader testing report (VoiceOver or NVDA; at least one full page walk-through).

outcome signal

• build passes: npm run build succeeds only if all contrast pairs pass the validator. no surprise failures in production.
• focus is visible: tab through any interactive element in the design system or app; a 2px+ outline appears with clear contrast against the background. outline is never removed.
• keyboard-only user can navigate: without a mouse, reach and operate every button, link, form field, and modal on a page. focus never gets stuck. tab order is logical.
• color is not the only cue: links have underlines or icons; status badges have text or icons; data viz lines are solid vs. dashed, not just different colors.
• type survives zoom and resize: browser zoom to 200% and browser text-size to largest; page layout does not break, no text is cut off, line height and paragraph spacing allow content to breathe.
• semantic HTML in place: browser devtools show <button>, <a>, <label>, <h1>-<h6>, real <form> and <input> elements, not styled <div>s with click handlers.
• screen reader announces intent: use VoiceOver (macOS), NVDA (Windows), or Narrator (Windows 10+) to navigate one page. heading structure, button labels, form errors, and state changes are all announced clearly. alt text on images sounds natural and contextual.
• no "we'll fix it later": accessibility is part of the token/component definition, not a backlog item. it was checked before merge, not after launch.

---

credits: original skill authored by raunakkathuria (clawhub). enriched per implexa quality standards with explicit procedure steps, decision points, edge cases, and outcome signals. ```