home / skills / nickcrew / claude-cortex / accessibility-audit

accessibility-audit skill

safe

/skills/accessibility-audit

This skill provides fast accessibility triage for pages, components, or PRs to surface WCAG 2.2 AA issues early.

npx playbooks add skill nickcrew/claude-cortex --skill accessibility-audit

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.0 KB

---
name: accessibility-audit
description: Fast, high-signal accessibility triage for pages, components, or PRs targeting WCAG 2.2 AA compliance.
keywords:
  - accessibility
  - a11y
  - wcag
  - audit
  - compliance
triggers:
  - accessibility check
  - a11y audit
  - wcag compliance
  - screen reader
  - keyboard navigation
---

# Accessibility Audit Skill

Fast, high-signal accessibility triage for pages, components, or PRs. This is a lightweight check, not a full compliance audit.

## When to Use This Skill

- Quick accessibility triage before releases
- Component-level a11y verification
- PR review for accessibility regressions
- Smoke checks for WCAG compliance
- Validating keyboard navigation on new features

## Quick Audit Checklist

### 1. Automated Snapshot (Recommended)

Run one of these automated tools first:
- `npx @axe-core/cli <url>` - Quick axe-core scan
- `npx pa11y <url> --standard WCAG2AA` - Pa11y audit
- Lighthouse Accessibility score (Chrome DevTools > Lighthouse > Accessibility)

### 2. Keyboard Basics

| Check | Expected |
|-------|----------|
| All interactive elements reachable via Tab | Yes |
| Focus indicator always visible | Yes |
| No keyboard traps | Yes |
| Logical tab order | Yes |
| Skip link works for long pages | Yes |

### 3. Semantics and Labels

| Check | Expected |
|-------|----------|
| Single, descriptive H1 | Yes |
| Logical heading order (no large jumps) | Yes |
| Form inputs have visible labels or aria-label | Yes |
| Buttons and links have clear names | Yes |
| Images have meaningful alt text (or empty for decorative) | Yes |

### 4. Visual Contrast

| Element | Minimum Ratio |
|---------|---------------|
| Normal text | 4.5:1 |
| Large text (18pt+ or 14pt bold+) | 3:1 |
| UI components (inputs, buttons, focus rings) | 3:1 |

### 5. Motion and Updates

| Check | Expected |
|-------|----------|
| Respects `prefers-reduced-motion` | Yes |
| Dynamic updates announced (aria-live) | Yes |

## Output Format

After running the audit, report findings as:

```markdown
## Accessibility Audit: [Component/Page Name]

### Result: [Pass | Needs Fixes | Escalate to Full Audit]

### Findings

| Severity | Issue | Location | Fix Guidance |
|----------|-------|----------|--------------|
| Critical | [Description] | [Selector/Line] | [How to fix] |
| Major | [Description] | [Selector/Line] | [How to fix] |
| Minor | [Description] | [Selector/Line] | [How to fix] |

### Escalation Recommendation
[If applicable, explain why a full audit is needed]
```

## Escalate to Full Audit When

- New or changed navigation structure
- Complex forms or authentication flows
- Custom widgets or advanced interactions (modals, accordions, tabs)
- Public releases or compliance requirements
- Significant page structure changes
- Failed automated scans with multiple critical issues

## Notes

- This smoke check targets **WCAG 2.2 AA** by default
- If a different compliance level is required, state it explicitly
- Automated tools catch ~30-40% of issues; manual testing is essential
- Test with actual screen readers (VoiceOver, NVDA) for comprehensive coverage

Overview

This skill provides a fast, high-signal accessibility triage for pages, components, or pull requests targeting WCAG 2.2 AA. It is a lightweight smoke check to surface obvious regressions and priorities, not a replacement for a full compliance audit. The focus is actionable findings and clear escalation guidance.

How this skill works

The skill combines an automated snapshot scan with focused manual checks: keyboard navigation, semantic structure, labels, visual contrast, and motion/updates. It produces a concise report that classifies findings by severity and gives concrete fix guidance and escalation recommendations. Use it as a quick gate in development, PR review, or release smoke testing.

When to use it

Quick triage before releases or deployments
Component-level verification during development
Pull request review to catch accessibility regressions
Smoke checks to validate WCAG 2.2 AA conformance baseline
Validating keyboard navigation for new interactive features

Best practices

Run an automated tool first (axe-cli, pa11y, or Lighthouse) and include results in the report
Confirm keyboard access, visible focus, and absence of traps manually
Check semantic headings, form labels, and clear link/button names
Measure contrast ratios for text and UI elements against WCAG thresholds
Test dynamic updates with aria-live and respect prefers-reduced-motion
Escalate to a full audit for complex interactions, navigation, or public releases

Example use cases

Run a quick audit on a feature branch to prevent accessibility regressions before merging
Validate a new component library release for keyboard focus and labeling issues
Smoke test a staging page after visual redesign to ensure contrast and headings remain accessible
Triage automated scan failures and prioritize fixes by severity
Decide whether to schedule a full audit when custom widgets or complex flows are introduced

FAQ

Is this a full accessibility audit?

No. This skill performs a high-signal smoke triage to surface common and high-impact issues. A full audit with assistive-technology testing is required for compliance.

Which automated tools does it recommend?

It recommends axe-core CLI, Pa11y with WCAG2AA standard, and Lighthouse accessibility scoring as starting points.