| name | ss-a11y |
| description | Audit a component or page for accessibility issues and fix them |
| argument-hint | [file-path] |
| allowed-tools | Read, Write, Edit, Grep, Glob |
Accessibility Audit
Registry-first artifact boundary
When .styleseed/project.json and .styleseed/artifacts/index.json exist, resolve the requested artifact ID first, then read only .styleseed/bundles/<artifact-id>.md and .styleseed/manifests/<artifact-id>.json. Never fall back to the global legacy bundle for a registry project. Legacy projects may use .styleseed/effective-rules.md only when no registry exists.
When NOT to use
- For general design system compliance review → use
/ss-review
- For Nielsen UX heuristics → use
/ss-audit
- For non-StyleSeed code (no
data-slot, no semantic tokens) — assumes StyleSeed conventions
- For runtime testing — this is a static code audit, not a screen-reader simulation
Target: $ARGUMENTS
Audit Criteria
WCAG 2.2 AA Compliance
1. Perceivable
- Color contrast: Text must meet 4.5:1 (normal) or 3:1 (large/bold text)
- Check
text-muted-foreground (#717182) on bg-background (#FFFFFF) = 4.6:1 (passes)
- Check
text-brand on white (verify contrast with your skin's brand color)
- Flag any custom colors that don't meet ratio
- Non-text contrast: UI controls/graphics must meet 3:1
- Text alternatives: All
<img> need alt, icons need aria-label when meaningful
- Color independence: Don't convey info by color alone (add icons/text)
2. Operable
3. Understandable
- Labels: Form inputs must have visible labels or
aria-label
- Error messages: Form errors must be programmatically associated (
aria-describedby)
- Language:
<html lang="en"> (or appropriate language code for your project)
4. Robust
- Semantic HTML: Use appropriate elements (
<button>, <nav>, <main>, <header>)
- ARIA: Use Radix UI components (they handle ARIA automatically)
- Roles: Custom interactive elements need proper
role attributes
Design System Token Reference
| Token | Minimum Contrast | Note |
|---|
--foreground | 7:1+ | Body text — verify with your skin |
--muted-foreground | 4.5:1+ | Secondary text — verify with your skin |
--brand | 4.5:1+ | Accent — verify with your skin's brand color |
--destructive | 4.5:1+ | Error — verify with your skin |
--success | 3:1+ | Large text/icons only — verify with your skin |
--warning | 4.5:1+ | Warning text — some skins need a darker variant |
Output
- Issues found: List with severity (Critical/Major/Minor)
- Auto-fixes: Apply fixes directly where possible
- Manual review needed: Flag items that need human judgment