Initial commit

2025-11-30 09:01:58 +08:00
commit aa33fffdfe
25 changed files with 4562 additions and 0 deletions
--- a/skills/specimin-ui-accessibility/SKILL.md
+++ b/skills/specimin-ui-accessibility/SKILL.md
@@ -0,0 +1,846 @@
+---
+name: "specimin-ui-accessibility"
+description: "Explicit accessibility enhancement and validation for generated UI code. Only invoke when user explicitly requests accessibility review, a11y enhancement, or WCAG compliance check."
+allowed-tools:
+  - run_terminal_cmd
+  - write
+  - read_file
+---
+
+**REQUIRES ui-generate to be completed first.**
+This skill performs deep accessibility enhancement and validation. **Manual testing is MANDATORY.**
+
+# UI Accessibility Enhancement Agent
+
+## Role
+Accessibility specialist ensuring WCAG 2.1 Level AA compliance through code enhancement and validation. **Critical**: Research shows 80%+ of AI-generated code has accessibility violations. This skill provides systematic fixes and mandatory manual testing checklist.
+
+## ⚠️ Critical Understanding
+
+**Why This Skill Exists**:
+> "Accessibility is by definition non-typical usage, therefore applying an average does not work."
+> — Research finding on AI-generated accessibility failures
+
+**Research Evidence**:
+- 80%+ of initial AI generations have semantic HTML violations
+- ChatGPT produced ZERO ARIA implementation in accessibility tests
+- Bard generated ARIA roles on wrong elements with broken references
+- Even accessibility-trained models produce WCAG-failing code
+- Automated tools catch only 60-70% of violations
+- **Manual validation with assistive technologies is MANDATORY**
+
+**This skill cannot fully automate accessibility**. It provides:
+1. Systematic code enhancements
+2. Automated audit (catches 60-70% of issues)
+3. **Mandatory manual testing checklist**
+
+## Process Flow
+
+### Stage 1: Load Generated Code
+
+1. Find current feature branch and generated files:
+```bash
+BRANCH=$(git branch --show-current)
+FEATURE_DIR=".specimin/ui/$BRANCH"
+```
+
+2. Read generation-report.md to identify:
+   - Files created/modified
+   - Components generated
+   - Known accessibility issues flagged
+
+3. Read all generated code files for analysis
+
+### Stage 2: Semantic HTML Audit
+
+**Check every element for semantic correctness**:
+
+#### Common Violations (Fix These)
+
+**Navigation Elements**:
+- ❌ `<div class="nav">`
+- ✅ `<nav aria-label="Main navigation">`
+
+**Buttons vs Links**:
+- ❌ `<div onClick={...}>` (not focusable, not keyboard accessible)
+- ❌ `<a onClick={...}>` (link semantics incorrect for actions)
+- ✅ `<button onClick={...}>` (semantic, focusable, keyboard accessible)
+- ✅ `<a href="/page">` (navigation only)
+
+**Headings**:
+- ❌ Skipping levels: h1 → h3 (violates heading hierarchy)
+- ❌ Using `<div class="text-2xl font-bold">` instead of headings
+- ✅ Proper hierarchy: h1 → h2 → h3 (logical nesting)
+- ✅ One h1 per page (page title)
+
+**Form Controls**:
+- ❌ `<input>` without `<label>`
+- ❌ Label not programmatically associated (visual only)
+- ✅ `<label for="email">` with `<input id="email">`
+- ✅ Or `<label><input></label>` (implicit association)
+
+**Landmark Regions**:
+- ❌ `<div class="main-content">`
+- ✅ `<main>` (primary content landmark)
+- ✅ `<aside>` (sidebar, complementary content)
+- ✅ `<footer>` (footer landmark)
+
+**Lists**:
+- ❌ `<div><div>Item 1</div><div>Item 2</div></div>`
+- ✅ `<ul><li>Item 1</li><li>Item 2</li></ul>`
+
+**Dialogs/Modals**:
+- ❌ `<div class="modal">`
+- ✅ `<dialog>` (native HTML5 dialog element, preferred)
+- ✅ Or `<div role="dialog" aria-modal="true">`
+
+### Stage 3: ARIA Implementation
+
+**Critical Principle**: Use ARIA **only when semantic HTML is insufficient**.
+
+> "First rule of ARIA: Don't use ARIA if you can use a native HTML element or attribute."
+> — W3C ARIA Authoring Practices
+
+#### When ARIA Is Needed
+
+**Dropdown Menus**:
+```html
+<!-- Button trigger -->
+<button
+  aria-haspopup="true"
+  aria-expanded="false"
+  aria-controls="menu-id"
+  id="menu-button">
+  Menu
+</button>
+
+<!-- Dropdown menu -->
+<div
+  role="menu"
+  aria-labelledby="menu-button"
+  id="menu-id"
+  hidden>
+  <button role="menuitem">Item 1</button>
+  <button role="menuitem">Item 2</button>
+</div>
+```
+
+**Tabs**:
+```html
+<div role="tablist" aria-label="Product details">
+  <button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">
+    Description
+  </button>
+  <button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2">
+    Reviews
+  </button>
+</div>
+
+<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
+  Description content
+</div>
+<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
+  Reviews content
+</div>
+```
+
+**Modal Dialogs**:
+```html
+<div
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="dialog-title"
+  aria-describedby="dialog-desc">
+  <h2 id="dialog-title">Confirm Action</h2>
+  <p id="dialog-desc">Are you sure you want to delete this item?</p>
+  <button>Cancel</button>
+  <button>Delete</button>
+</div>
+```
+
+**Live Regions** (status messages, notifications):
+```html
+<div role="status" aria-live="polite" aria-atomic="true">
+  Form submitted successfully
+</div>
+
+<div role="alert" aria-live="assertive">
+  Error: Please fix the highlighted fields
+</div>
+```
+
+**Hidden Content** (visually hidden but screen-reader accessible):
+```html
+<span class="sr-only">Opens in new window</span>
+<!-- Tailwind sr-only class: position: absolute; width: 1px; ... -->
+```
+
+#### Common ARIA Mistakes to Fix
+
+**Wrong Elements**:
+- ❌ `<li role="dialog">` (dialog role on list item)
+- ✅ Use correct element for role
+
+**Broken References**:
+- ❌ `aria-labelledby="nonexistent-id"` (ID doesn't exist)
+- ✅ Ensure all ARIA references point to valid IDs
+
+**Incomplete Patterns**:
+- ❌ `aria-expanded` attribute that never updates
+- ✅ Ensure state attributes change with UI state
+
+**Redundant ARIA**:
+- ❌ `<button role="button">` (redundant)
+- ✅ `<button>` (native semantics sufficient)
+
+### Stage 4: Keyboard Navigation Enhancement
+
+**Every interactive element must be keyboard accessible.**
+
+#### Focus Management
+
+**Tab Order**:
+- All interactive elements receive focus in logical order
+- Skip to main content link (first focusable element)
+- Tab through navigation → main content → footer
+- No focus traps (except intentional like modals)
+
+**Visible Focus Indicators**:
+```html
+<!-- Tailwind focus styles -->
+<button class="... focus:outline-none focus:ring-2 focus:ring-blue-500">
+  Click me
+</button>
+
+<!-- Custom focus (if needed) -->
+<a class="... focus:underline focus:ring-2">
+  Link
+</a>
+```
+
+#### Keyboard Event Handlers
+
+**Modals**:
+```javascript
+// Escape key closes modal
+onKeyDown={(e) => {
+  if (e.key === 'Escape') closeModal();
+}}
+
+// Focus trap inside modal (Tab cycles within)
+// Return focus to trigger when closed
+```
+
+**Dropdowns**:
+```javascript
+// Enter/Space opens dropdown
+// Arrow keys navigate items
+// Escape closes
+// Tab closes and moves focus
+```
+
+**Custom Components** (not native):
+```javascript
+// Enter and Space both activate
+onKeyDown={(e) => {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault();
+    handleActivate();
+  }
+}}
+```
+
+#### Framework-Specific Patterns
+
+**React**:
+```typescript
+import { useRef, useEffect } from 'react';
+
+// Focus management
+const modalRef = useRef<HTMLDialogElement>(null);
+
+useEffect(() => {
+  if (isOpen) {
+    modalRef.current?.focus();
+    // Trap focus logic
+  }
+}, [isOpen]);
+```
+
+**Phoenix LiveView**:
+```elixir
+# Focus on mount
+def mount(_params, _session, socket) do
+  {:ok, socket, temporary_assigns: [focus: "modal-id"]}
+end
+
+# HEEx template
+<div id={@focus} phx-hook="FocusOnMount">
+```
+
+**Vue**:
+```vue
+<script setup>
+import { ref, onMounted } from 'vue';
+
+const modalRef = ref(null);
+
+onMounted(() => {
+  if (isOpen.value) {
+    modalRef.value?.focus();
+  }
+});
+</script>
+```
+
+### Stage 5: Additional Accessibility Requirements
+
+#### Images and Media
+
+**Alt Text**:
+- ❌ `<img src="photo.jpg">` (no alt)
+- ❌ `<img src="logo.jpg" alt="logo">` (redundant)
+- ✅ `<img src="logo.jpg" alt="Company Name">` (descriptive)
+- ✅ `<img src="decorative.jpg" alt="">` (decorative image, empty alt)
+
+**Videos**:
+- Captions/subtitles for audio content
+- Transcripts available
+- Playback controls keyboard accessible
+
+#### Color and Contrast
+
+**Color Not Sole Indicator**:
+- ❌ Red text only to indicate errors
+- ✅ Red text + icon + explicit "Error:" label
+
+**Contrast Ratios** (WCAG AA):
+- Normal text: 4.5:1 minimum
+- Large text (18pt+ or 14pt bold+): 3:1 minimum
+- UI components and graphics: 3:1 minimum
+
+**Check**:
+- Tailwind default colors generally pass (gray-700+ on white)
+- Custom colors need manual verification
+- Use browser DevTools Accessibility checker
+
+#### Forms
+
+**Labels**:
+- Every input has associated label
+- Label text describes purpose clearly
+- Group related inputs with `<fieldset>` and `<legend>`
+
+**Validation**:
+- Error messages programmatically associated with inputs
+- `aria-invalid="true"` on invalid fields
+- `aria-describedby` pointing to error message ID
+
+**Required Fields**:
+```html
+<label for="email">
+  Email <span aria-label="required">*</span>
+</label>
+<input
+  type="email"
+  id="email"
+  required
+  aria-required="true"
+  aria-describedby="email-error">
+<span id="email-error" role="alert">
+  <!-- Error message inserted here -->
+</span>
+```
+
+#### Responsive and Zoom
+
+**Text Resize**:
+- Content readable at 200% zoom without horizontal scroll
+- No fixed pixel font sizes (use rem)
+- Avoid `user-scalable=no` in viewport meta
+
+**Touch Targets**:
+- Minimum 44x44 pixels (mobile)
+- Adequate spacing between interactive elements
+- Tailwind: `p-2` typically sufficient, `min-h-[44px]` if needed
+
+### Stage 6: Automated Accessibility Audit
+
+**Run conceptual equivalent of axe-core checks**:
+
+#### Checklist
+
+**Critical (Must Fix)**:
+- [ ] All images have alt attributes
+- [ ] Form inputs have labels
+- [ ] Buttons have accessible names
+- [ ] Links have discernible text
+- [ ] Page has `<html lang="...">` attribute
+- [ ] Page has meaningful `<title>`
+- [ ] Heading hierarchy valid (no skipping)
+- [ ] Color contrast sufficient (4.5:1 text, 3:1 UI)
+- [ ] No keyboard traps
+- [ ] ARIA references valid (IDs exist)
+
+**Serious (Should Fix)**:
+- [ ] Landmarks present (main, nav, footer)
+- [ ] Skip links available
+- [ ] Focus indicators visible
+- [ ] ARIA attributes correct for roles
+- [ ] Lists use semantic markup (ul/ol)
+- [ ] Tables have proper headers (if used)
+
+**Moderate (Consider)**:
+- [ ] Explicit language changes marked (`lang` attribute)
+- [ ] Abbreviations explained (first use)
+- [ ] Link text descriptive (not "click here")
+
+### Stage 7: Generate Accessibility Report
+
+Create accessibility-report.md documenting:
+
+**Audit Results**:
+- Violations found and fixed
+- Automated check results (pass/fail)
+- WCAG 2.1 Level AA compliance status
+
+**Enhancements Made**:
+- Semantic HTML improvements
+- ARIA additions
+- Keyboard navigation enhancements
+- Focus management implementations
+
+**Manual Testing Checklist** (MANDATORY):
+- [ ] Keyboard-only navigation test
+- [ ] Screen reader testing (NVDA/JAWS/VoiceOver)
+- [ ] Zoom to 200% test
+- [ ] Color contrast verification
+- [ ] Touch target size verification (mobile)
+
+**Known Limitations**:
+- Automated tools catch 60-70% of issues
+- Context-dependent problems require human judgment
+- Screen reader quirks across devices
+- Business logic validation
+
+### Stage 8: Present Manual Testing Checklist
+
+**Critical**: Show user this mandatory checklist:
+
+```
+## 🔴 MANDATORY Manual Accessibility Testing
+
+AI-generated code requires human validation. Complete ALL checks below:
+
+### Keyboard Navigation Test (30 minutes)
+- [ ] Unplug mouse (force keyboard-only)
+- [ ] Tab through entire interface
+- [ ] Verify logical tab order
+- [ ] Test all interactive elements (Enter/Space to activate)
+- [ ] Escape closes modals/dropdowns
+- [ ] No focus traps (except intentional)
+- [ ] Focus indicators clearly visible
+
+### Screen Reader Test (1 hour)
+**Windows** (NVDA - free):
+- [ ] Download NVDA (https://www.nvaccess.org/)
+- [ ] Navigate page with screen reader on
+- [ ] Verify all content announced
+- [ ] Check heading navigation (H key)
+- [ ] Check landmark navigation (D key)
+- [ ] Verify form labels read correctly
+- [ ] Test interactive widgets (modals, dropdowns, tabs)
+
+**Mac/iOS** (VoiceOver - built-in):
+- [ ] Enable VoiceOver (Cmd+F5)
+- [ ] Navigate with VO keys (Control+Option+arrows)
+- [ ] Verify rotor navigation (landmarks, headings)
+- [ ] Test on Safari (primary VO browser)
+
+**Basics to verify**:
+- Page title announced on load
+- Headings provide page structure
+- Buttons/links clearly identified
+- Form fields have labels
+- Error messages read aloud
+- Status updates announced (live regions)
+
+### Visual Test (15 minutes)
+- [ ] Zoom browser to 200% (Cmd/Ctrl + +)
+- [ ] No horizontal scroll appears
+- [ ] All content remains readable
+- [ ] No text overlap
+- [ ] Interactive elements still usable
+
+### Color Contrast Test (15 minutes)
+- [ ] Use browser DevTools Accessibility tab
+- [ ] Check all text meets 4.5:1 ratio (normal text)
+- [ ] Check 3:1 ratio for large text and UI components
+- [ ] Verify error states use more than color alone
+
+### Mobile/Touch Test (30 minutes)
+- [ ] Test on actual device (not just emulator)
+- [ ] All touch targets minimum 44x44 pixels
+- [ ] Adequate spacing between interactive elements
+- [ ] Pinch zoom works (not disabled)
+- [ ] Landscape and portrait orientations work
+
+### Total Time: ~2.5-3 hours
+This cannot be skipped. Accessibility cannot be automated away.
+```
+
+### Stage 9: Finalize
+
+**ONLY after user acknowledges manual testing requirement**:
+
+1. Write accessibility-report.md to feature directory
+2. Commit accessibility enhancements:
+```bash
+bash ${CLAUDE_PLUGIN_ROOT}/.claude-plugin/skills/specimin-ui-accessibility/scripts/save-accessibility.sh "$BRANCH"
+```
+
+3. Confirm to user:
+   "✓ Accessibility enhancements applied and committed.
+
+   ⚠️  **NEXT STEP REQUIRED**: Complete manual accessibility testing checklist.
+   See .specimin/ui/[branch]/accessibility-report.md for full checklist.
+
+   After testing complete, run `specimin:wrap` to create PR."
+
+## Output: Accessibility Report Format
+
+```markdown
+# Accessibility Report - [Feature Name]
+
+## Executive Summary
+- **WCAG Level**: AA (Target)
+- **Automated Compliance**: [X]% of checks passed
+- **Manual Testing**: ⚠️ REQUIRED (see checklist below)
+- **Critical Issues**: [N] found and fixed
+- **Status**: ✅ Ready for Manual Testing | ⚠️ Issues Remain | ❌ Blocked
+
+## Violations Found and Fixed
+
+### Critical (Blocking)
+
+#### 1. Non-Semantic Button Elements
+**Found**: `<div onClick={handleClick}>Submit</div>`
+**Issue**: Not keyboard accessible, no semantic meaning
+**WCAG**: 4.1.2 Name, Role, Value (Level A)
+**Fixed**: Changed to `<button onClick={handleClick}>Submit</button>`
+
+#### 2. Missing Form Labels
+**Found**: `<input type="email" placeholder="Email">`
+**Issue**: Screen readers cannot identify field purpose
+**WCAG**: 3.3.2 Labels or Instructions (Level A)
+**Fixed**: Added `<label for="email">Email</label>` with association
+
+#### 3. Skipped Heading Level
+**Found**: h1 → h3 (skipped h2)
+**Issue**: Breaks document structure for screen readers
+**WCAG**: 2.4.6 Headings and Labels (Level AA)
+**Fixed**: Changed to h2, adjusted visual styling
+
+### Serious (Should Fix)
+
+#### 4. Missing Landmark Regions
+**Found**: `<div class="main-content">`
+**Issue**: Screen reader users cannot navigate by landmarks
+**WCAG**: 4.1.2 Name, Role, Value (Level A)
+**Fixed**: Changed to `<main>` element
+
+#### 5. Incomplete ARIA Pattern
+**Found**: Dropdown with `aria-expanded` never updating
+**Issue**: Screen reader announces incorrect state
+**WCAG**: 4.1.2 Name, Role, Value (Level A)
+**Fixed**: Added state management to toggle `aria-expanded` on open/close
+
+### Moderate (Enhancements)
+
+#### 6. Generic Link Text
+**Found**: `<a href="/docs">Click here</a>`
+**Issue**: Not descriptive out of context
+**WCAG**: 2.4.4 Link Purpose (Level A)
+**Fixed**: Changed to `<a href="/docs">View documentation</a>`
+
+## Enhancements Applied
+
+### Semantic HTML Improvements
+- Replaced 8 div elements with semantic alternatives (nav, main, button)
+- Established proper heading hierarchy (h1 → h2 → h3)
+- Used list elements (ul/li) for navigation and feature lists
+
+### ARIA Additions
+- Modal dialog: Added `role="dialog"`, `aria-modal="true"`, `aria-labelledby`
+- Dropdown menu: Added `aria-haspopup`, `aria-expanded`, `aria-controls`
+- Live region: Added `role="status"` for form submission feedback
+- Hidden content: Added `aria-hidden="true"` to decorative elements
+
+### Keyboard Navigation
+- Focus indicators: Added `focus:ring-2 focus:ring-blue-500` to all interactive elements
+- Modal keyboard handling: Escape closes, focus trap implemented, focus restoration on close
+- Dropdown keyboard handling: Enter/Space opens, Arrow keys navigate, Escape closes
+
+### Focus Management
+**Modal open sequence**:
+1. Trap focus inside modal
+2. Focus first interactive element
+3. Tab cycles within modal
+4. Escape restores focus to trigger button
+
+**Implementation**:
+- React: useEffect + useRef pattern
+- Phoenix LiveView: phx-hook="FocusManagement"
+- Vue: onMounted + ref pattern
+
+## Automated Audit Results
+
+### axe-core Equivalent Checks
+
+✅ **Passed (35/40)**:
+- All images have alt attributes
+- Form inputs have associated labels
+- Color contrast meets WCAG AA (4.5:1)
+- HTML lang attribute present
+- Page title meaningful
+- No duplicate IDs
+- ARIA references valid
+- Buttons have accessible names
+- [... full list]
+
+❌ **Failed (0/40)**: None remaining
+
+⚠️ **Manual Review Needed (5/40)**:
+- Alt text quality (requires context judgment)
+- Heading structure appropriateness (requires content understanding)
+- Link text descriptiveness (requires context)
+- Form error message clarity (requires UX review)
+- Color not sole indicator (requires visual review)
+
+## Known Limitations
+
+### Automated Testing Boundaries
+- **Coverage**: Automated tools catch 60-70% of accessibility issues
+- **Context**: Cannot judge appropriateness of alt text, heading levels
+- **Screen Reader Quirks**: Differences between NVDA, JAWS, VoiceOver
+- **User Experience**: Cannot test actual navigation flows
+
+### Framework-Specific Considerations
+**Phoenix LiveView**:
+- Client-side JavaScript hooks used for focus management
+- Server-side validation messages need `phx-feedback-for` for proper timing
+- Live navigation requires `aria-live` regions for route changes
+
+**React**:
+- Focus management requires refs and useEffect
+- Router transitions need announcement to screen readers
+- State updates need `aria-live` for status messages
+
+### Business Logic Gaps
+- Form validation error messages (content not generated)
+- Loading states and spinners (design not provided)
+- Error recovery flows (business logic needed)
+
+## 🔴 MANDATORY Manual Testing Checklist
+
+**Estimated Time: 2.5-3 hours**
+
+AI-generated code CANNOT be shipped without human accessibility testing.
+
+### 1. Keyboard Navigation Test (30 min)
+
+**Setup**: Unplug mouse, use keyboard only
+
+- [ ] **Tab Order**: Logical progression through interface
+- [ ] **Skip Link**: "Skip to main content" link works (if present)
+- [ ] **Navigation**: Tab through all nav items, Enter/Space activates
+- [ ] **Forms**: Tab through fields, Space checks checkboxes, Enter submits
+- [ ] **Buttons**: Enter or Space activates all buttons
+- [ ] **Modals**: Escape closes, focus trapped inside when open
+- [ ] **Dropdowns**: Enter/Space opens, Escape closes, Arrow keys navigate (if applicable)
+- [ ] **Focus Indicators**: Always visible, never hidden by CSS
+- [ ] **No Traps**: Can Tab to and from every interactive element
+
+**Tools**: None required (keyboard only)
+
+### 2. Screen Reader Test (1 hour)
+
+**Windows - NVDA (Free)**:
+Download: https://www.nvaccess.org/download/
+
+- [ ] **Install NVDA**: Follow wizard, restart optional
+- [ ] **Launch NVDA**: Desktop shortcut or Ctrl+Alt+N
+- [ ] **Open Page**: Use Chrome or Firefox (best NVDA support)
+- [ ] **Listen to Page Load**: Page title announced
+- [ ] **Navigate by Headings**: Press H to jump between headings
+- [ ] **Navigate by Landmarks**: Press D to jump between regions (main, nav, etc.)
+- [ ] **Navigate by Elements**: Press B (buttons), K (links), F (forms)
+- [ ] **Test Form**: Arrow through fields, hear labels, submit, hear confirmation
+- [ ] **Test Interactive Widgets**: Modals, dropdowns, tabs (verify announcements)
+- [ ] **Verify Images**: Images announce alt text, decorative images skipped
+
+**Mac/iOS - VoiceOver (Built-in)**:
+- [ ] **Enable VO**: Cmd+F5 (Mac) or Settings > Accessibility > VoiceOver (iOS)
+- [ ] **Open Page**: Use Safari (best VO support)
+- [ ] **Navigate**: Control+Option+Arrow keys (Mac), swipe (iOS)
+- [ ] **Rotor Navigation**: Control+Option+U for landmarks/headings menu
+- [ ] **Test Interactive Elements**: Buttons, links, forms
+- [ ] **Verify Announcements**: All content understandable via audio only
+
+**What to Listen For**:
+- Clear, descriptive announcements (not "button button" or "link graphic")
+- Form labels read before input fields
+- Error messages announced immediately
+- Status updates announced (form submission, loading)
+- Modal open/close announced
+- All text content accessible (nothing skipped)
+
+### 3. Visual/Zoom Test (15 min)
+
+- [ ] **Zoom 200%**: Cmd/Ctrl and press + until 200%
+- [ ] **No Horizontal Scroll**: Content reflows, doesn't require side-scrolling
+- [ ] **Text Readable**: All text remains legible, no overlap
+- [ ] **Interactive Elements**: Buttons, links still clickable
+- [ ] **Layout Intact**: No broken layouts, content still usable
+
+**Tools**: Browser zoom (Cmd/Ctrl + +)
+
+### 4. Color Contrast Test (15 min)
+
+- [ ] **Open DevTools**: F12 or Right-click > Inspect
+- [ ] **Accessibility Tab**: Chrome DevTools > Accessibility pane
+- [ ] **Check Elements**: Inspect text elements, view contrast ratio
+- [ ] **Verify Ratios**: Normal text ≥4.5:1, large text ≥3:1, UI components ≥3:1
+- [ ] **Color Not Sole Indicator**: Errors use icon + text, not just red color
+
+**Tools**: Chrome DevTools Accessibility panel
+
+### 5. Mobile/Touch Test (30 min)
+
+- [ ] **Real Device**: Test on actual phone/tablet (emulator insufficient for touch)
+- [ ] **Touch Targets**: All buttons/links easily tappable (44x44px minimum)
+- [ ] **Spacing**: Adequate space between interactive elements (no mis-taps)
+- [ ] **Pinch Zoom**: Works (viewport doesn't disable)
+- [ ] **Orientation**: Portrait and landscape both work
+- [ ] **Screen Reader**: Test VoiceOver on iOS or TalkBack on Android
+- [ ] **Gestures**: Swipe navigation works with screen reader
+
+**Tools**: Physical mobile device
+
+## Testing Resources
+
+### Screen Readers
+- **NVDA (Windows, Free)**: https://www.nvaccess.org/
+- **JAWS (Windows, Paid)**: https://www.freedomscientific.com/products/software/jaws/
+- **VoiceOver (Mac/iOS, Built-in)**: Cmd+F5 or Settings > Accessibility
+- **TalkBack (Android, Built-in)**: Settings > Accessibility > TalkBack
+
+### Browser Tools
+- **Chrome DevTools**: Accessibility panel, Lighthouse audit
+- **Firefox DevTools**: Accessibility inspector
+- **axe DevTools**: Browser extension (free version available)
+- **WAVE**: Browser extension for visual accessibility review
+
+### Color Contrast Checkers
+- **WebAIM Contrast Checker**: https://webaim.org/resources/contrastchecker/
+- **Colour Contrast Analyser**: Desktop app (free)
+
+### Learning Resources
+- **WebAIM**: https://webaim.org/ (comprehensive guides)
+- **W3C ARIA Authoring Practices**: https://www.w3.org/WAI/ARIA/apg/
+- **A11y Project**: https://www.a11yproject.com/ (checklist and resources)
+
+## Sign-Off
+
+**Accessibility testing completed by**: ___________________
+**Date**: ___________________
+**Screen reader used**: ___________________
+**Devices tested**: ___________________
+
+**Issues found during manual testing**:
+- [ ] None - all tests passed
+- [ ] Issues found (list below):
+
+___________________________________________________________________
+___________________________________________________________________
+
+**Ready for production**: [ ] Yes [ ] No
+
+## Next Steps
+
+1. **Complete manual testing** using checklist above (~3 hours)
+2. **Document any issues** found during testing
+3. **Fix critical issues** before production deployment
+4. **Re-test** after fixes applied
+5. **Run `specimin:wrap`** to create PR when ready
+6. **Include accessibility testing notes** in PR description
+
+---
+
+## Appendix: WCAG 2.1 Level AA Compliance
+
+### Principles Covered
+
+**Perceivable**:
+- ✅ 1.1.1 Non-text Content (Alt text for images)
+- ✅ 1.3.1 Info and Relationships (Semantic HTML, ARIA)
+- ✅ 1.4.3 Contrast (Minimum) (4.5:1 for text)
+- ✅ 1.4.10 Reflow (No horizontal scroll at 200% zoom)
+- ✅ 1.4.11 Non-text Contrast (3:1 for UI components)
+
+**Operable**:
+- ✅ 2.1.1 Keyboard (All functionality via keyboard)
+- ✅ 2.1.2 No Keyboard Trap (Can Tab out of all elements)
+- ✅ 2.4.1 Bypass Blocks (Skip links, landmarks)
+- ✅ 2.4.3 Focus Order (Logical tab order)
+- ✅ 2.4.6 Headings and Labels (Descriptive, hierarchical)
+- ✅ 2.4.7 Focus Visible (Focus indicators present)
+
+**Understandable**:
+- ✅ 3.1.1 Language of Page (`<html lang="en">`)
+- ✅ 3.2.1 On Focus (No unexpected changes on focus)
+- ✅ 3.2.2 On Input (No unexpected changes on input)
+- ✅ 3.3.1 Error Identification (Errors clearly described)
+- ✅ 3.3.2 Labels or Instructions (Form fields labeled)
+
+**Robust**:
+- ✅ 4.1.2 Name, Role, Value (Semantic HTML, ARIA)
+- ✅ 4.1.3 Status Messages (Live regions for dynamic content)
+
+### Reference
+Full WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
+```
+
+---
+
+## Requirements
+
+**Do**:
+- Read all generated code files
+- Fix semantic HTML violations systematically
+- Add ARIA only when semantic HTML insufficient
+- Implement keyboard navigation for all interactive elements
+- Manage focus for modals and complex widgets
+- Run conceptual automated audit
+- Provide detailed manual testing checklist
+- **Emphasize that manual testing is MANDATORY**
+- Document all changes made
+- Explain why each change improves accessibility
+
+**Don't**:
+- Skip manual testing checklist (most critical output)
+- Add redundant ARIA (use semantic HTML first)
+- Assume automated tools catch all issues (only 60-70%)
+- Make accessibility fixes that break functionality
+- Use overly complex ARIA patterns when simple HTML works
+- Claim "accessibility complete" without manual testing
+
+**Research-backed insights**:
+- 80%+ of AI-generated code has accessibility violations
+- Two-stage approach (structure → accessibility) prevents deprioritization
+- Automated tools catch only 60-70% of violations
+- Manual testing with assistive technologies is MANDATORY
+- TetraLogical research: Even accessibility-trained models produce WCAG-failing code
+- "Accessibility is by definition non-typical usage, therefore applying an average does not work"
+- ChatGPT produced zero ARIA implementation in controlled tests
+- Bard generated ARIA roles on wrong elements with broken references
--- a/skills/specimin-ui-accessibility/scripts/save-accessibility.sh
+++ b/skills/specimin-ui-accessibility/scripts/save-accessibility.sh
@@ -0,0 +1,88 @@
+#!/bin/bash
+# save-accessibility.sh - Saves accessibility enhancements and report to feature branch
+# Usage: save-accessibility.sh <branch_name>
+
+set -e
+
+BRANCH_NAME="$1"
+
+if [ -z "$BRANCH_NAME" ]; then
+  # Try to get current branch if not provided
+  BRANCH_NAME=$(git branch --show-current)
+fi
+
+if [ -z "$BRANCH_NAME" ]; then
+  echo "Error: Could not determine branch name"
+  echo "Usage: save-accessibility.sh <branch_name>"
+  exit 1
+fi
+
+# Verify we're in a git repository
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  echo "Error: Not in a git repository"
+  exit 1
+fi
+
+# Verify branch exists
+if ! git rev-parse --verify "$BRANCH_NAME" > /dev/null 2>&1; then
+  echo "Error: Branch '$BRANCH_NAME' does not exist"
+  exit 1
+fi
+
+# Verify we're on the correct branch
+CURRENT_BRANCH=$(git branch --show-current)
+if [ "$CURRENT_BRANCH" != "$BRANCH_NAME" ]; then
+  echo "Error: Not on branch '$BRANCH_NAME' (currently on '$CURRENT_BRANCH')"
+  exit 1
+fi
+
+FEATURE_DIR=".specimin/ui/$BRANCH_NAME"
+
+# Verify feature directory exists
+if [ ! -d "$FEATURE_DIR" ]; then
+  echo "Error: Feature directory not found: $FEATURE_DIR"
+  echo "Run specimin:ui-understand first"
+  exit 1
+fi
+
+# Verify generation-report.md exists
+GENERATION_REPORT="$FEATURE_DIR/generation-report.md"
+if [ ! -f "$GENERATION_REPORT" ]; then
+  echo "Error: generation-report.md not found at $GENERATION_REPORT"
+  echo "Run specimin:ui-generate first"
+  exit 1
+fi
+
+# Check if accessibility report exists in /tmp
+REPORT_TEMP="/tmp/ui-accessibility-report.md"
+if [ ! -f "$REPORT_TEMP" ]; then
+  echo "Error: Accessibility report not found at $REPORT_TEMP"
+  echo "The skill should write the accessibility report to /tmp/ui-accessibility-report.md"
+  exit 1
+fi
+
+# Copy accessibility report to feature directory
+REPORT_DEST="$FEATURE_DIR/accessibility-report.md"
+cp "$REPORT_TEMP" "$REPORT_DEST"
+
+# Add all changes (accessibility enhancements + report)
+git add -A
+
+# Check if there are changes to commit
+if git diff --cached --quiet; then
+  echo "Warning: No changes to commit (accessibility enhancements may already be staged)"
+else
+  # Commit with descriptive message
+  git commit -m "Apply accessibility enhancements
+
+- Fixed semantic HTML violations
+- Added ARIA attributes where needed
+- Implemented keyboard navigation
+- Enhanced focus management
+- See accessibility-report.md for full details
+
+⚠️  MANUAL TESTING REQUIRED before production deployment"
+fi
+
+# Output success message with JSON
+echo "{\"feature_dir\": \"$FEATURE_DIR\", \"branch_name\": \"$BRANCH_NAME\", \"report_path\": \"$REPORT_DEST\"}"