# Stitch A11y

> Audits Stitch-generated components for WCAG 2.1 AA accessibility issues and applies fixes — semantic HTML, ARIA attributes, keyboard navigation, focus management, and screen reader support.

- **Type:** Skill
- **Install:** `agentstack add skill-gabelul-stitch-kit-stitch-a11y`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gabelul](https://agentstack.voostack.com/s/gabelul)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [gabelul](https://github.com/gabelul)
- **Source:** https://github.com/gabelul/stitch-kit/tree/main/skills/stitch-a11y
- **Website:** https://booplex.com/projects/stitch-kit-design-intelligence-for-ai-agents

## Install

```sh
agentstack add skill-gabelul-stitch-kit-stitch-a11y
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:
```bash
# 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:**
```tsx
// ❌ 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:**
```tsx
// 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:**
```tsx
// 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

```

```svelte

  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:
```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:
```tsx
// ❌ 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:**
```tsx
// 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:**
```tsx
// 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:

```css
/* 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:

```tsx
// 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:

```markdown
# 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](https://github.com/gabelul)
- **Source:** [gabelul/stitch-kit](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gabelul-stitch-kit-stitch-a11y
- Seller: https://agentstack.voostack.com/s/gabelul
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.