wicked-garden 12.27.0

package/skills/product/accessibility/refs/audit-report-results.md

@@ -0,0 +1,276 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Accessibility Audit Report: Results & Recommendations
+
+Test results by component, automated scan results, screen reader testing, keyboard navigation, recommendations, and checklists.
+
+## Test Results by Component
+
+### Navigation
+
+**Status**: ⚠ Issues
+
+**Issues:**
+- Missing skip link (Issue #5)
+- Dropdown not keyboard accessible (Issue #7)
+
+**Recommendations:**
+1. Add skip navigation link
+2. Implement ARIA menu pattern for dropdown
+
+---
+
+### Forms
+
+**Status**: ✗ Fail
+
+**Issues:**
+- Missing labels (Issue #2)
+- Error messages not associated with fields (Issue #8)
+- No error summary
+
+**Recommendations:**
+1. Associate all labels with inputs
+2. Use aria-describedby for error messages
+3. Add error summary with role="alert" at top of form
+
+---
+
+## Automated Scan Results
+
+### axe DevTools Summary
+
+**Violations**: [Count]
+**Passes**: [Count]
+**Incomplete**: [Count requiring manual review]
+
+**Top Violations:**
+1. [Rule name]: [Count] instances
+2. [Rule name]: [Count] instances
+
+**Export**: [Link to full axe report JSON]
+
+---
+
+### Lighthouse Accessibility Score
+
+**Score**: [0-100]
+
+**Opportunities:**
+- [Lighthouse suggestion 1]
+- [Lighthouse suggestion 2]
+
+---
+
+## Screen Reader Testing
+
+### VoiceOver + Safari (macOS)
+
+**Primary Flow**: ✓ Pass
+**Issues Encountered:**
+- [Issue description]
+
+**Notable Behaviors:**
+- [Positive or negative behavior]
+
+---
+
+### NVDA + Firefox (Windows)
+
+**Primary Flow**: ⚠ Issues
+**Issues Encountered:**
+- [Issue description]
+
+**Notable Behaviors:**
+- [Positive or negative behavior]
+
+---
+
+## Keyboard Navigation Testing
+
+**Overall**: [✓ Pass | ⚠ Issues | ✗ Fail]
+
+**Tab Order**: [✓ Logical | ⚠ Some issues | ✗ Broken]
+**Focus Indicators**: [✓ Visible | ⚠ Inconsistent | ✗ Missing]
+**Keyboard Traps**: [✓ None found | ✗ Found]
+
+**Issues:**
+1. [Issue description with location]
+2. [Issue description with location]
+
+**Flows Tested:**
+- ✓ Navigate homepage
+- ✗ Complete checkout (Issue #12 - modal keyboard trap)
+- ⚠ Submit contact form (Issue #8 - unclear error handling)
+
+---
+
+## Recommendations
+
+### Immediate Actions (P0)
+
+Must be fixed before launch or next release.
+
+1. **Add alt text to all images**
+   - Effort: 2-4 hours
+   - Files affected: [List]
+   - Assigned to: [Developer]
+
+2. **Fix form label associations**
+   - Effort: 3-5 hours
+   - Files affected: [List]
+   - Assigned to: [Developer]
+
+3. **Fix keyboard trap in modal**
+   - Effort: 4-6 hours
+   - Files affected: Modal.tsx
+   - Assigned to: [Developer]
+
+### High Priority (P1)
+
+Should be fixed within 2-4 weeks.
+
+1. **Improve color contrast**
+   - Effort: 2-3 hours
+   - Update design tokens
+   - Assigned to: [Designer/Developer]
+
+2. **Add ARIA to custom components**
+   - Effort: 6-8 hours
+   - Components: Dropdown, Tabs, Accordion
+   - Assigned to: [Developer]
+
+### Medium Priority (P2)
+
+Fix within 1-2 months.
+
+1. **Add skip navigation link**
+2. **Improve heading structure**
+3. **Add landmark regions**
+
+### Low Priority (P3)
+
+Nice to have improvements.
+
+1. **Add ARIA live regions for dynamic content**
+2. **Improve focus management on route changes**
+
+---
+
+## Design System Recommendations
+
+If fixing individual issues keeps recurring, consider systematic improvements:
+
+1. **Create accessible component library**
+   - Build once, use everywhere
+   - Include ARIA patterns by default
+   - Document keyboard interactions
+
+2. **Establish design tokens for color contrast**
+   - Pre-approved color combinations
+   - Automated contrast checking in CI
+
+3. **Add accessibility linting**
+   - eslint-plugin-jsx-a11y
+   - Pre-commit hooks
+   - CI pipeline checks
+
+4. **Developer training**
+   - WCAG overview
+   - Screen reader basics
+   - Keyboard navigation patterns
+
+---
+
+## Testing Checklist for Future Releases
+
+Use this checklist for ongoing accessibility testing:
+
+### Automated
+```
+□ Run axe DevTools on all pages
+□ Run Lighthouse audit
+□ Check color contrast with automated tool
+□ Validate HTML (duplicate IDs, nesting issues)
+```
+
+### Manual
+```
+□ Keyboard navigation test (10 min)
+□ Screen reader spot check (15 min)
+□ Test primary user flow with eyes closed
+□ Review code for semantic HTML
+□ Check ARIA usage
+```
+
+### Before Release
+```
+□ All Critical (P0) issues resolved
+□ All Major (P1) issues resolved or scheduled
+□ Keyboard navigation works for all user flows
+□ Screen reader can complete primary actions
+□ Color contrast meets WCAG AA
+□ Forms are fully accessible
+```
+
+---
+
+## Resources
+
+### Tools
+- **axe DevTools**: Browser extension
+- **Lighthouse**: Built into Chrome DevTools
+- **WAVE**: https://wave.webaim.org/
+- **Color Contrast Analyzer**: https://www.tpgi.com/color-contrast-checker/
+
+### Guidelines
+- **WCAG 2.1**: https://www.w3.org/WAI/WCAG21/quickref/
+- **WebAIM**: https://webaim.org/
+- **A11Y Project**: https://www.a11yproject.com/
+
+### Training
+- **Deque University**: https://dequeuniversity.com/
+- **WebAIM Training**: https://webaim.org/training/
+- **A11ycasts**: https://www.youtube.com/playlist?list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g
+
+---
+
+## Appendix
+
+### A. Full Issue List (CSV)
+
+Export all issues as CSV for tracking:
+
+```
+ID,Severity,WCAG,Issue,Location,Status,Assignee,Due Date
+1,Critical,1.1.1,Missing alt text,Header.tsx:45,Open,Jane,2026-02-01
+2,Critical,1.3.1,Form labels missing,ContactForm.tsx,Open,John,2026-02-01
+...
+```
+
+### B. Code Snippets
+
+[Include longer code examples if needed]
+
+### C. Screenshots
+
+[Attach screenshots showing issues visually]
+
+### D. Automated Report Files
+
+- axe-results.json
+- lighthouse-report.html
+- pa11y-output.txt
+
+---
+
+## Sign-off
+
+**Auditor**: [Name]
+**Date**: [YYYY-MM-DD]
+**Next Audit**: [Recommended date - typically after fixes or quarterly]
+
+**Notes:**
+[Any additional context or observations]

package/skills/product/accessibility/refs/common-violations-html-css.md

@@ -0,0 +1,270 @@
+---
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+# Common Accessibility Violations: HTML & CSS
+
+Quick reference for the most frequent WCAG violations with before/after examples. Covers images, forms, contrast, semantics, and focus.
+
+## 1. Missing Alternative Text
+
+**WCAG**: 1.1.1 Non-text Content (Level A)
+**Impact**: Screen readers can't describe images
+
+### Images Without Alt
+
+```html
+<!-- ✗ VIOLATION -->
+<img src="product.jpg">
+
+<!-- ✓ FIX -->
+<img src="product.jpg" alt="Red wireless headphones">
+```
+
+### Decorative Images
+
+```html
+<!-- ✗ VIOLATION - Unnecessary alt text -->
+<img src="decorative-border.png" alt="border">
+
+<!-- ✓ FIX - Empty alt for decorative images -->
+<img src="decorative-border.png" alt="">
+```
+
+### Background Images with Content
+
+```html
+<!-- ✗ VIOLATION - Text in background image -->
+<div style="background-image: url('hero-with-text.jpg')"></div>
+
+<!-- ✓ FIX - Add ARIA label or visible text -->
+<div style="background-image: url('hero-with-text.jpg')"
+     role="img"
+     aria-label="Welcome to our store - Shop now for 50% off">
+</div>
+```
+
+### Icon Buttons
+
+```html
+<!-- ✗ VIOLATION -->
+<button><i class="icon-trash"></i></button>
+
+<!-- ✓ FIX -->
+<button aria-label="Delete item">
+  <i class="icon-trash" aria-hidden="true"></i>
+</button>
+```
+
+## 2. Form Controls Without Labels
+
+**WCAG**: 1.3.1 Info and Relationships, 3.3.2 Labels or Instructions (Level A)
+**Impact**: Users don't know what to enter
+
+### Missing Label
+
+```html
+<!-- ✗ VIOLATION -->
+<input type="text" placeholder="Enter email">
+
+<!-- ✓ FIX -->
+<label for="email">Email address</label>
+<input type="text" id="email" placeholder="e.g., user@example.com">
+```
+
+### Visual Label Without Association
+
+```html
+<!-- ✗ VIOLATION - Label not programmatically associated -->
+<span>Username</span>
+<input type="text" name="username">
+
+<!-- ✓ FIX -->
+<label for="username">Username</label>
+<input type="text" id="username" name="username">
+```
+
+### Radio Buttons Without Fieldset
+
+```html
+<!-- ✗ VIOLATION - No grouping -->
+<label><input type="radio" name="size" value="s"> Small</label>
+<label><input type="radio" name="size" value="m"> Medium</label>
+<label><input type="radio" name="size" value="l"> Large</label>
+
+<!-- ✓ FIX -->
+<fieldset>
+  <legend>Select size</legend>
+  <label><input type="radio" name="size" value="s"> Small</label>
+  <label><input type="radio" name="size" value="m"> Medium</label>
+  <label><input type="radio" name="size" value="l"> Large</label>
+</fieldset>
+```
+
+### Hidden Label (Visual Design)
+
+```html
+<!-- ✗ VIOLATION - No label at all -->
+<input type="search" placeholder="Search">
+
+<!-- ✓ GOOD - Visible label -->
+<label for="search">Search</label>
+<input type="search" id="search">
+
+<!-- ✓ ACCEPTABLE - Visually hidden label -->
+<label for="search" class="sr-only">Search</label>
+<input type="search" id="search" placeholder="Search products">
+
+<style>
+.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;
+}
+</style>
+```
+
+## 3. Low Color Contrast
+
+**WCAG**: 1.4.3 Contrast (Minimum) (Level AA)
+**Impact**: Text hard to read for low vision users
+
+### Insufficient Contrast
+
+```html
+<!-- ✗ VIOLATION - 2.5:1 contrast -->
+<p style="color: #999; background: #fff;">Gray text</p>
+
+<!-- ✓ FIX - 4.7:1 contrast -->
+<p style="color: #666; background: #fff;">Dark gray text</p>
+```
+
+**Minimum ratios:**
+- Normal text: 4.5:1
+- Large text (18pt+ or 14pt+ bold): 3:1
+- UI components and graphics: 3:1
+
+### Common Color Pairs
+
+```css
+/* ✗ VIOLATIONS */
+color: #777; background: #fff;     /* 4.4:1 - barely fails */
+color: #999; background: #fff;     /* 2.8:1 - clear fail */
+color: #0066ff; background: #fff;  /* 4.3:1 - fails for normal text */
+
+/* ✓ PASSES */
+color: #666; background: #fff;     /* 4.7:1 */
+color: #595959; background: #fff;  /* 7:1 */
+color: #0052cc; background: #fff;  /* 4.5:1 */
+color: #fff; background: #0066ff;  /* 4.5:1 (white on blue) */
+```
+
+### Placeholder Contrast
+
+```css
+/* ✗ VIOLATION - Default browser placeholders often fail */
+::placeholder {
+  color: #ccc; /* Too light */
+}
+
+/* ✓ FIX */
+::placeholder {
+  color: #757575; /* 4.6:1 contrast */
+}
+```
+
+## 4. Non-Semantic HTML
+
+**WCAG**: 4.1.2 Name, Role, Value (Level A)
+**Impact**: Screen readers announce incorrect element type
+
+### Div/Span as Button
+
+```html
+<!-- ✗ VIOLATION -->
+<div onclick="submit()">Submit</div>
+
+<!-- ✓ FIX - Use semantic button -->
+<button onclick="submit()">Submit</button>
+
+<!-- ✓ ACCEPTABLE - If div required, add role and keyboard -->
+<div role="button" tabindex="0"
+     onclick="submit()"
+     onkeydown="if(event.key==='Enter'||event.key===' ')submit()">
+  Submit
+</div>
+```
+
+### Non-Semantic Lists
+
+```html
+<!-- ✗ VIOLATION -->
+<div>Item 1</div>
+<div>Item 2</div>
+<div>Item 3</div>
+
+<!-- ✓ FIX -->
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+  <li>Item 3</li>
+</ul>
+```
+
+### Non-Semantic Headings
+
+```html
+<!-- ✗ VIOLATION -->
+<div class="heading-large">Page Title</div>
+<div class="heading-medium">Section Title</div>
+
+<!-- ✓ FIX -->
+<h1>Page Title</h1>
+<h2>Section Title</h2>
+```
+
+## 5. Missing Focus Indicators
+
+**WCAG**: 2.4.7 Focus Visible (Level AA)
+**Impact**: Keyboard users can't see where they are
+
+### Removed Outline
+
+```css
+/* ✗ VIOLATION */
+*:focus {
+  outline: none;
+}
+
+/* ✓ FIX - Custom accessible focus */
+*:focus-visible {
+  outline: 2px solid #0066cc;
+  outline-offset: 2px;
+}
+```
+
+### Invisible Focus on Custom Components
+
+```css
+/* ✗ VIOLATION - Focus blends in */
+.button {
+  background: #0066cc;
+  color: white;
+}
+.button:focus {
+  background: #0052cc; /* Too similar */
+}
+
+/* ✓ FIX - Clear focus state */
+.button:focus-visible {
+  outline: 2px solid white;
+  outline-offset: 2px;
+  box-shadow: 0 0 0 4px #0066cc;
+}
+```