diff --git a/docs/ACCESSIBILITY_QUICK_REFERENCE.md b/docs/ACCESSIBILITY_QUICK_REFERENCE.md new file mode 100644 index 000000000..7ae5eb3c3 --- /dev/null +++ b/docs/ACCESSIBILITY_QUICK_REFERENCE.md @@ -0,0 +1,507 @@ +# Accessibility Quick Reference Guide + +**Status**: Implementation Guide for WCAG AA Compliance +**Target**: All MetaBuilder developers + +--- + +## One-Minute Summary + +MetaBuilder components must be: +1. **Keyboard accessible** - All interactions via keyboard +2. **Screen reader friendly** - Clear semantic HTML + ARIA labels +3. **Visually clear** - 4.5:1 contrast, visible focus indicators +4. **Error handling** - Clear messages with `role="alert"` + +--- + +## Essential Patterns + +### ✅ Button Component +```tsx +// GOOD + + +// GOOD - Visible text + + +// BAD - Icon only, no label + +``` + +### ✅ Form Input +```tsx +// GOOD + + +{error && ( + +)} + +// BAD - No label + + +// BAD - Placeholder instead of label + +``` + +### ✅ Link Text +```tsx +// GOOD - Descriptive +Learn about MetaBuilder + +// GOOD - Icon + text + + Next + +// BAD - Generic "click here" +Click here + +// BAD - No text + + + +``` + +### ✅ Keyboard Navigation +```tsx +// GOOD - Handle Escape to close + + {/* useEffect to handle Escape key */} + useEffect(() => { + const handler = (e: KeyboardEvent) => { + if (e.key === 'Escape') onClose() + } + document.addEventListener('keydown', handler) + return () => document.removeEventListener('keydown', handler) + }, [onClose]) + + +// GOOD - Tab order with arrow keys (tabs) +` | +| `aria-labelledby` | Link element to heading | `
` | +| `aria-describedby` | Add description | `` | +| `aria-invalid` | Mark invalid input | `` | +| `aria-required` | Mark required field | `` | +| `aria-hidden` | Hide from screen readers | `