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:

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

Fixes:

// ❌ Wrong

  Home

// ✅ Fixed

  Home

// ❌ Wrong — div button
Submit

// ✅ Fixed — real button
Submit

// ❌ Wrong — visual list as divs

  Item 1
  Item 2

// ✅ Fixed

  Item 1
  Item 2

Category 2: ARIA attributes

Only add ARIA where semantic HTML doesn't provide sufficient information. Remember: no ARIA is better than bad ARIA.

Violations to find:

• Icon-only buttons with no accessible name
• Multiple ` landmarks with no aria-label`
• Multiple `` elements
• Status/live regions that update dynamically but have no aria-live
• Interactive elements missing aria-expanded, aria-haspopup, aria-controls

Fixes:

// Icon-only button

  

// Multiple nav regions
...
...
...

// Dropdown toggle

  Account

  Profile

// Live status region

  {statusMessage}

Category 3: Keyboard navigation

Every interactive element must be operable by keyboard. Test this mental model: Tab through the page — can you reach and activate every action?

Violations to find:

• Custom interactive elements that don't receive Tab focus
• tabIndex={-1} used where focus should be reachable
• tabIndex={1} or higher (breaks natural tab order)
• Modal open — focus not moved into modal
• Modal closed — focus not returned to trigger
• Dropdown closed with Escape — focus not returned

Fixes:

// Focus management for modal — React
import { useEffect, useRef } from 'react'

export function Modal({ isOpen, onClose, children }: ModalProps) {
  const modalRef = useRef(null)
  const triggerRef = useRef(null)

  useEffect(() => {
    if (isOpen) {
      // Move focus into modal when it opens
      modalRef.current?.focus()
    }
  }, [isOpen])

  function handleClose() {
    onClose()
    // Return focus to trigger when modal closes
    triggerRef.current?.focus()
  }

  return (
    <>
       setIsOpen(true)}>
        Open Modal
      
      {isOpen && (
        
          Modal Title
          {children}
          Close
        
      )}
    
  )
}

// Keyboard handler for custom interactive elements
 {
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault()
      handleAction()
    }
  }}
>
  Custom button behavior

  let dialogEl = $state()
  let triggerEl = $state()
  let isOpen = $state(false)

  function openDialog() {
    isOpen = true
    // tick() ensures DOM is updated before focusing
    tick().then(() => dialogEl?.focus())
  }

  function closeDialog() {
    isOpen = false
    triggerEl?.focus()  // Return focus to trigger
  }

Open

{#if isOpen}
   e.key === 'Escape' && closeDialog()}
  >
    Close
  
{/if}

Category 4: Focus visibility

Every interactive element must have a visible focus indicator. Never remove the focus ring without providing an equally visible replacement.

Violations to find:

• outline: none or outline: 0 without a custom focus style
• .focus:outline-none in Tailwind without focus-visible:ring-*
• Focus styles that only appear on click, not keyboard focus

Fixes:

In CSS:

/* Never this */
*:focus { outline: none; }

/* Always this — uses :focus-visible to show only on keyboard focus */
*:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
  border-radius: 2px;
}

In Tailwind:

// ❌ Wrong

// ✅ Fixed

Category 5: Images and media

Violations to find:

• ` or without alt` attribute
• Meaningful images with alt=""
• Decorative images with descriptive alt text (adds noise to screen readers)
• Icons without accessible labels when used as interactive elements
• Video without captions

Fixes:

// Meaningful image

// Decorative image — empty alt so screen readers skip it

// Icon in a button — hide icon, label the button

  

// Icon with adjacent text — hide the icon (it's redundant)

  
  Save changes

Category 6: Color and contrast

Check these without automated tools by reasoning about the design:

Violations to find:

• Muted text (--color-text-muted) on a muted background (--color-surface) — often fails 4.5:1
• Primary color on white at small sizes — verify it passes 4.5:1
• Disabled state text that's too light to read even as a hint
• Relying on color alone to convey meaning (error states, required fields)

Fixes:

// Add non-color indicator for errors

{hasError && (
  
    {/* Icon + text — not color alone */}
    
    Please enter a valid email address
  
)}

// Required field indicator

  Email
   *
  (required)

Step 3: The sr-only utility class

Add this to your global CSS if it's not there already. You'll use it frequently:

/* Visually hidden, but readable by screen readers */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

/* Skip link — visible on focus for keyboard users */
.skip-link {
  position: absolute;
  left: -9999px;
  top: auto;
  width: 1px;
  height: 1px;
  overflow: hidden;
}
.skip-link:focus {
  position: fixed;
  top: 1rem;
  left: 1rem;
  width: auto;
  height: auto;
  padding: 0.5rem 1rem;
  background: var(--color-primary);
  color: var(--color-primary-fg);
  border-radius: var(--radius-md);
  font-weight: 600;
  z-index: 9999;
}

Step 4: Skip navigation link

Add a skip link as the first element in every page layout. This lets keyboard users jump past the navigation:

// app/layout.tsx or +layout.svelte — first child of 

  Skip to main content

// The target

  {children}

Step 5: Generate the audit report

After fixing, create accessibility-audit.md summarizing what was found and fixed:

# Accessibility Audit Report

**Date:** [date]
**WCAG Target:** 2.1 AA
**Components audited:** [list]

## Issues Found & Fixed

### Critical (would block screen reader users)
- [Component]: [issue] → [fix applied]

### Important (keyboard navigation issues)
- [Component]: [issue] → [fix applied]

### Minor (improvements to quality of life)
- [Component]: [issue] → [fix applied]

## Remaining Recommendations

[Any issues that require design changes or user testing to resolve]

## How to test

1. Tab through the entire page — every interactive element should be reachable
2. Activate with Enter/Space — all buttons and links should work
3. Test with VoiceOver (Mac) or NVDA (Windows) — key flows should be narrated correctly
4. Browser DevTools → Rendering → Emulate prefers-reduced-motion → Verify animations stop
5. axe DevTools extension for automated checks

Troubleshooting

| Issue | Fix | |-------|-----| | aria-labelledby points to wrong ID | Ensure IDs are unique across the page | | Focus trap locking keyboard in modal | Implement proper Tab/Shift+Tab cycling within modal bounds | | Screen reader announcing redundant info | Add aria-hidden="true" to decorative elements | | Multiple violations in one component | Fix semantic HTML first — ARIA issues often cascade from it | | Skip link not showing | Ensure :focus state overrides the off-screen positioning |

References

• resources/audit-checklist.md — Quick reference checklist for pre-ship review

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gabelul
• Source: gabelul/stitch-kit
• License: Apache-2.0
• Homepage: https://booplex.com/projects/stitch-kit-design-intelligence-for-ai-agents

Install and usage instructions live in the source repository linked above.