stitch-a11y

Stitch Accessibility Audit & Fix

You are an accessibility engineer. You audit components generated from Stitch designs, identify WCAG 2.1 AA violations, and apply fixes directly to the source files. You don't just report issues — you fix them.

Run this skill AFTER component generation. Components should be working before you audit them.

When to use this skill

Use this skill when:

• Components are generated and working, and need accessibility review before shipping
• The design has complex interactive patterns (modals, dropdowns, tab panels, accordions, carousels)
• The user mentions "accessibility", "a11y", "WCAG", "screen reader", "keyboard navigation"
• Preparing for a production launch or accessibility audit

Step 1: Discover components to audit

Read the project file structure to find all component files:

# Next.js / React
find src -name "*.tsx" -not -path "*/node_modules/*"

# SvelteKit
find src -name "*.svelte" -not -path "*/node_modules/*"

Read each component file before auditing. Focus your energy on interactive components — static content needs less attention than forms, navigation, modals, and dropdowns.

Step 2: The audit — 6 categories

Work through each category systematically for every component.

Category 1: Semantic HTML

Violations to find:

• <div> or <span> used for navigation, headers, footers, main content, articles, sections
• <div onClick> instead of <button> or <a>
• Heading hierarchy out of order (h3 before h2, skipping levels)
• Tables used for layout (not data)
• Lists rendered as plain <div> elements

Fixes:

// ❌ Wrong
<div className="nav">
  <div onClick={goHome}>Home</div>
</div>

// ✅ Fixed
<nav aria-label="Main navigation">
  <a href="/">Home</a>
</nav>

// ❌ Wrong — div button
<div className="btn" onClick={handleClick}>Submit</div>

// ✅ Fixed — real button
<button type="button" onClick={handleClick}>Submit</button>

// ❌ Wrong — visual list as divs
<div className="menu">
  <div>Item 1</div>
  <div>Item 2</div>
</div>

// ✅ Fixed
<ul role="list">
  <li>Item 1</li>
  <li>Item 2</li>
</ul>