developer-ai 1.0.0

package/skills/accessibility/SKILL.md

@@ -0,0 +1,496 @@
+---
+name: accessibility
+description: Guide for building accessible web applications. Use when implementing UI components, reviewing for accessibility compliance, or fixing accessibility issues. Covers WCAG guidelines, ARIA attributes, keyboard navigation, and testing tools.
+---
+
+# Accessibility Skill
+
+This skill provides guidance for building inclusive web applications that work for everyone.
+
+## Overview
+
+Accessibility (a11y) ensures your application is usable by people with disabilities. This skill covers WCAG guidelines, semantic HTML, ARIA, and testing approaches.
+
+## WCAG Principles (POUR)
+
+| Principle | Description |
+|-----------|-------------|
+| **Perceivable** | Information must be presentable in ways users can perceive |
+| **Operable** | UI components must be operable by all users |
+| **Understandable** | Information and UI must be understandable |
+| **Robust** | Content must work with current and future technologies |
+
+## Semantic HTML
+
+### Use Appropriate Elements
+
+```html
+<!-- BAD: Div soup -->
+<div class="header">
+  <div class="nav">
+    <div class="link" onclick="navigate()">Home</div>
+  </div>
+</div>
+<div class="main-content">
+  <div class="article">
+    <div class="title">Article Title</div>
+  </div>
+</div>
+<div class="footer">Copyright 2024</div>
+
+<!-- GOOD: Semantic elements -->
+<header>
+  <nav>
+    <a href="/">Home</a>
+  </nav>
+</header>
+<main>
+  <article>
+    <h1>Article Title</h1>
+  </article>
+</main>
+<footer>Copyright 2024</footer>
+```
+
+### Heading Hierarchy
+
+```html
+<!-- BAD: Skipped levels, wrong order -->
+<h1>Page Title</h1>
+<h3>Section</h3>
+<h2>Subsection</h2>
+
+<!-- GOOD: Logical hierarchy -->
+<h1>Page Title</h1>
+<h2>Section</h2>
+<h3>Subsection</h3>
+<h3>Another Subsection</h3>
+<h2>Next Section</h2>
+```
+
+### Buttons vs Links
+
+```html
+<!-- Links: Navigation -->
+<a href="/products">View Products</a>
+
+<!-- Buttons: Actions -->
+<button type="button" onclick="openModal()">Open Settings</button>
+
+<!-- BAD: Div as button -->
+<div class="button" onclick="submit()">Submit</div>
+
+<!-- BAD: Link as button -->
+<a href="#" onclick="submit()">Submit</a>
+```
+
+## ARIA Attributes
+
+### When to Use ARIA
+
+```
+First rule of ARIA: Don't use ARIA if native HTML works.
+```
+
+### Common ARIA Attributes
+
+```html
+<!-- Labels -->
+<button aria-label="Close modal">×</button>
+<input type="search" aria-label="Search products">
+
+<!-- Descriptions -->
+<input 
+  type="password" 
+  aria-describedby="password-help"
+>
+<p id="password-help">Must be at least 8 characters</p>
+
+<!-- States -->
+<button aria-pressed="true">Bold</button>
+<button aria-expanded="false" aria-controls="menu">Menu</button>
+<div id="menu" hidden>...</div>
+
+<!-- Live Regions -->
+<div aria-live="polite" aria-atomic="true">
+  Cart updated: 3 items
+</div>
+
+<!-- Roles -->
+<div role="alert">Error: Invalid email</div>
+<nav role="navigation" aria-label="Main">...</nav>
+```
+
+### ARIA for Custom Components
+
+```html
+<!-- Custom checkbox -->
+<div 
+  role="checkbox"
+  aria-checked="false"
+  tabindex="0"
+  onkeydown="handleKeydown(event)"
+  onclick="toggle()"
+>
+  Accept terms
+</div>
+
+<!-- Custom dropdown -->
+<div class="dropdown">
+  <button
+    aria-haspopup="listbox"
+    aria-expanded="false"
+    aria-controls="options"
+  >
+    Select option
+  </button>
+  <ul 
+    id="options"
+    role="listbox"
+    aria-label="Options"
+    hidden
+  >
+    <li role="option" aria-selected="false">Option 1</li>
+    <li role="option" aria-selected="false">Option 2</li>
+  </ul>
+</div>
+```
+
+## Keyboard Navigation
+
+### Focus Management
+
+```javascript
+// Focus first element in modal when opened
+function openModal() {
+  modal.hidden = false;
+  modal.querySelector('[autofocus], button, [href], input').focus();
+}
+
+// Return focus when modal closes
+let previousFocus;
+
+function openModal() {
+  previousFocus = document.activeElement;
+  modal.hidden = false;
+  // Focus first element
+}
+
+function closeModal() {
+  modal.hidden = true;
+  previousFocus.focus();
+}
+```
+
+### Focus Trap
+
+```javascript
+function trapFocus(element) {
+  const focusableElements = element.querySelectorAll(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+  );
+  const firstElement = focusableElements[0];
+  const lastElement = focusableElements[focusableElements.length - 1];
+
+  element.addEventListener('keydown', (e) => {
+    if (e.key !== 'Tab') return;
+
+    if (e.shiftKey) {
+      if (document.activeElement === firstElement) {
+        e.preventDefault();
+        lastElement.focus();
+      }
+    } else {
+      if (document.activeElement === lastElement) {
+        e.preventDefault();
+        firstElement.focus();
+      }
+    }
+  });
+}
+```
+
+### Skip Links
+
+```html
+<body>
+  <a href="#main-content" class="skip-link">
+    Skip to main content
+  </a>
+  
+  <header>...</header>
+  <nav>...</nav>
+  
+  <main id="main-content" tabindex="-1">
+    <!-- Main content -->
+  </main>
+</body>
+
+<style>
+.skip-link {
+  position: absolute;
+  top: -40px;
+  left: 0;
+  padding: 8px;
+  background: white;
+  z-index: 100;
+}
+
+.skip-link:focus {
+  top: 0;
+}
+</style>
+```
+
+## Forms
+
+### Labels
+
+```html
+<!-- Explicit label -->
+<label for="email">Email</label>
+<input type="email" id="email" name="email">
+
+<!-- Implicit label -->
+<label>
+  Email
+  <input type="email" name="email">
+</label>
+
+<!-- With required indicator -->
+<label for="email">
+  Email <span aria-hidden="true">*</span>
+</label>
+<input 
+  type="email" 
+  id="email" 
+  required
+  aria-required="true"
+>
+```
+
+### Error Messages
+
+```html
+<label for="email">Email</label>
+<input 
+  type="email" 
+  id="email"
+  aria-invalid="true"
+  aria-describedby="email-error"
+>
+<p id="email-error" role="alert">
+  Please enter a valid email address
+</p>
+```
+
+### Form Groups
+
+```html
+<fieldset>
+  <legend>Shipping Address</legend>
+  
+  <label for="street">Street</label>
+  <input type="text" id="street" name="street">
+  
+  <label for="city">City</label>
+  <input type="text" id="city" name="city">
+</fieldset>
+```
+
+## Images
+
+### Alt Text
+
+```html
+<!-- Informative image -->
+<img src="chart.png" alt="Sales increased 25% in Q4 2024">
+
+<!-- Decorative image -->
+<img src="decoration.png" alt="" role="presentation">
+
+<!-- Complex image -->
+<figure>
+  <img src="chart.png" alt="Bar chart showing quarterly sales">
+  <figcaption>
+    Q1: $100k, Q2: $150k, Q3: $200k, Q4: $250k
+  </figcaption>
+</figure>
+
+<!-- Icon buttons -->
+<button aria-label="Delete item">
+  <img src="trash.svg" alt="">
+</button>
+```
+
+## Color & Contrast
+
+### Contrast Requirements
+
+| Element | WCAG AA | WCAG AAA |
+|---------|---------|----------|
+| Normal text | 4.5:1 | 7:1 |
+| Large text (18px+) | 3:1 | 4.5:1 |
+| UI components | 3:1 | - |
+
+### Don't Rely on Color Alone
+
+```html
+<!-- BAD: Color only -->
+<span style="color: red">Error</span>
+<span style="color: green">Success</span>
+
+<!-- GOOD: Color + text/icon -->
+<span style="color: red">❌ Error: Invalid email</span>
+<span style="color: green">✓ Success: Account created</span>
+```
+
+## React Accessibility
+
+### Accessible Components
+
+```jsx
+// Accessible Button
+function IconButton({ icon, label, onClick }) {
+  return (
+    <button onClick={onClick} aria-label={label}>
+      {icon}
+    </button>
+  );
+}
+
+// Accessible Modal
+function Modal({ isOpen, onClose, title, children }) {
+  const modalRef = useRef();
+  
+  useEffect(() => {
+    if (isOpen) {
+      modalRef.current.focus();
+    }
+  }, [isOpen]);
+  
+  if (!isOpen) return null;
+  
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="modal-title"
+      ref={modalRef}
+      tabIndex={-1}
+    >
+      <h2 id="modal-title">{title}</h2>
+      {children}
+      <button onClick={onClose}>Close</button>
+    </div>
+  );
+}
+```
+
+### Managing Focus
+
+```jsx
+function SearchForm() {
+  const inputRef = useRef();
+  const [results, setResults] = useState([]);
+  
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    const data = await search(inputRef.current.value);
+    setResults(data);
+    // Announce results
+  };
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      <label htmlFor="search">Search</label>
+      <input
+        ref={inputRef}
+        id="search"
+        type="search"
+        aria-describedby="search-hint"
+      />
+      <p id="search-hint">Press Enter to search</p>
+      
+      <div role="region" aria-live="polite">
+        {results.length} results found
+      </div>
+      
+      <ul>
+        {results.map(item => (
+          <li key={item.id}>{item.name}</li>
+        ))}
+      </ul>
+    </form>
+  );
+}
+```
+
+## Testing Accessibility
+
+### Automated Testing
+
+```javascript
+// jest-axe
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+it('has no accessibility violations', async () => {
+  const { container } = render(<MyComponent />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+### Manual Testing Checklist
+
+- [ ] Navigate with keyboard only (Tab, Enter, Space, Arrows)
+- [ ] Test with screen reader (VoiceOver, NVDA)
+- [ ] Zoom to 200% - content still usable
+- [ ] Check color contrast with tools
+- [ ] Disable CSS - content still readable
+- [ ] Test with reduced motion preference
+
+### Browser Extensions
+
+- **axe DevTools** - Automated a11y testing
+- **WAVE** - Visual accessibility feedback
+- **Lighthouse** - Built into Chrome DevTools
+
+## Accessibility Checklist
+
+### Structure
+- [ ] Semantic HTML used
+- [ ] Heading hierarchy correct
+- [ ] Landmarks defined (header, nav, main, footer)
+- [ ] Skip links provided
+
+### Forms
+- [ ] All inputs have labels
+- [ ] Required fields marked
+- [ ] Error messages associated
+- [ ] Form groups used for related fields
+
+### Images & Media
+- [ ] Images have alt text
+- [ ] Decorative images have empty alt
+- [ ] Videos have captions
+- [ ] Audio has transcripts
+
+### Interaction
+- [ ] All interactive elements keyboard accessible
+- [ ] Focus visible and logical
+- [ ] Focus trapped in modals
+- [ ] Touch targets at least 44x44px
+
+### Content
+- [ ] Color contrast meets WCAG AA
+- [ ] Information not conveyed by color alone
+- [ ] Text resizable to 200%
+- [ ] Language attribute set
+
+### ARIA
+- [ ] ARIA labels where needed
+- [ ] Live regions for dynamic content
+- [ ] States communicated (expanded, selected, etc.)