Skip to content

SKILL.md

Latest commit

 

History

History
68 lines (51 loc) · 3.94 KB

SKILL.md

File metadata and controls

68 lines (51 loc) · 3.94 KB
Raw
name audit-accessibility
description Audit a feature for WCAG 2.1 AA compliance using POUR principles when the user asks to check accessibility, audit a11y, or verify WCAG compliance
owner chalk
version 1.0.0
metadata-version 1
allowed-tools Read, Glob, Grep, Write
argument-hint [feature or component to audit for accessibility]

Audit Accessibility

Overview

Generate a WCAG 2.1 AA compliance audit for a specific feature or component, organized by the POUR principles (Perceivable, Operable, Understandable, Robust). Produces a concrete checklist with testing instructions, keyboard navigation paths, screen reader expectations, and color contrast requirements.

Workflow

  1. Read feature context -- Scan .chalk/docs/product/ for the PRD describing the feature. Check .chalk/docs/engineering/ for component architecture and any existing a11y guidelines. Read the source code for the feature's UI components to understand the actual implementation.

  2. Parse the audit target -- Extract from $ARGUMENTS the feature, page, or component to audit. If unspecified, ask the user to name a specific feature -- auditing the entire application at once produces shallow results.

  3. Determine the next file number -- Read filenames in .chalk/docs/engineering/ to find the highest numbered file. The next number is highest + 1.

  4. Audit Perceivable -- Check:

    • All images have meaningful alt text (decorative images use alt="")
    • Color is not the only means of conveying information
    • Text meets contrast ratios (4.5:1 for normal text, 3:1 for large text)
    • Content is readable at 200% zoom
    • Media has captions or transcripts

  5. Audit Operable -- Check:

    • All interactive elements are reachable via keyboard (Tab, Shift+Tab, Enter, Space, Escape, Arrow keys)
    • Document the expected keyboard navigation path through the feature
    • Focus order matches visual order
    • No keyboard traps
    • Focus indicators are visible
    • Touch targets are at least 44x44 CSS pixels

  6. Audit Understandable -- Check:

    • Form inputs have visible labels (not just placeholders)
    • Error messages identify the field and describe how to fix the error
    • Consistent navigation and naming patterns
    • Language is set on the page element

  7. Audit Robust -- Check:

    • Semantic HTML elements used appropriately (buttons, links, headings, landmarks)
    • ARIA roles, states, and properties are correct and necessary
    • Components work with major screen readers (VoiceOver, NVDA, JAWS)
    • No ARIA is better than bad ARIA

  8. Write the file -- Save to .chalk/docs/engineering/<n>_a11y_audit_<feature-slug>.md.

  9. Confirm -- Share the file path and highlight the highest-severity issues that block users from completing tasks.

Output

  • File: .chalk/docs/engineering/<n>_a11y_audit_<feature-slug>.md
  • Format: Plain markdown with POUR-organized checklist, each item marked pass/fail/needs-review with specific testing instructions
  • First line: # Accessibility Audit: <Feature Name>

Anti-patterns

  • Checklist without testing instructions -- "Check color contrast" is not actionable. Specify which elements, what the current ratio is, and what the target ratio should be.
  • ARIA overuse -- Adding role="button" to a <button> is redundant. Adding ARIA to fix semantic HTML problems is treating symptoms. Prefer native HTML elements.
  • Keyboard testing only with Tab -- Many components require Arrow keys (tabs, menus, radio groups), Escape (modals, dropdowns), Space (checkboxes), and Enter (buttons, links). Document the full expected keyboard interaction model.
  • Ignoring screen reader output -- An element can be technically accessible but produce nonsensical screen reader output. Specify what the screen reader should announce for each interactive element.
  • Treating a11y as a one-time audit -- Note which checks should be automated in CI and which require manual testing on each release.