@zoyth/simple-site-framework 1.0.0

package/docs/accessibility/keyboard-navigation.md

@@ -0,0 +1,263 @@
+# Keyboard Navigation Guide
+
+All Simple Site Framework components support full keyboard navigation. This guide covers keyboard patterns and testing.
+
+## Standard Keyboard Controls
+
+### Tab Navigation
+- **Tab**: Move focus forward through interactive elements
+- **Shift + Tab**: Move focus backward
+- **Enter/Space**: Activate buttons, links, and controls
+- **Escape**: Close modals, menus, and dropdowns
+
+### Component-Specific
+- **Arrow Keys**: Navigate within lists, menus, tabs, and carousels
+- **Home/End**: Jump to first/last item in lists
+- **Page Up/Down**: Scroll or navigate in long lists
+
+## Component Keyboard Patterns
+
+### Button
+```tsx
+<Button onClick={handleClick}>
+  Submit
+</Button>
+```
+- **Tab**: Focus the button
+- **Enter/Space**: Activate the button
+
+### Modal
+```tsx
+<Modal isOpen={isOpen} onClose={handleClose}>
+  {/* Modal content */}
+</Modal>
+```
+- **Tab**: Cycle through focusable elements inside modal
+- **Shift + Tab**: Cycle backward
+- **Escape**: Close modal
+- Focus is **trapped** inside modal while open
+- Focus **returns** to trigger when closed
+
+### Tabs
+```tsx
+<Tabs tabs={tabs} value={activeTab} onValueChange={setActiveTab} />
+```
+- **Tab**: Focus the tab list
+- **Arrow Left/Right**: Navigate between tabs
+- **Home**: Jump to first tab
+- **End**: Jump to last tab
+- **Enter/Space**: Activate selected tab
+
+### Select/Dropdown
+```tsx
+<Select options={options} value={value} onChange={setValue} />
+```
+- **Tab**: Focus the select
+- **Enter/Space/Arrow Down**: Open dropdown
+- **Arrow Up/Down**: Navigate options
+- **Home/End**: Jump to first/last option
+- **Enter/Space**: Select option
+- **Escape**: Close without selecting
+- **Type ahead**: Jump to option starting with typed character
+
+### Accordion
+```tsx
+<FAQAccordion items={faqItems} />
+```
+- **Tab**: Focus accordion header
+- **Enter/Space**: Toggle section
+- **Arrow Down**: Move to next header
+- **Arrow Up**: Move to previous header
+- **Home**: Jump to first header
+- **End**: Jump to last header
+
+### Carousel/Slider
+```tsx
+<TestimonialCarousel testimonials={items} />
+```
+- **Tab**: Focus carousel controls
+- **Arrow Left/Right**: Navigate slides
+- **Space/Enter**: Pause/play autoplay
+
+### Multi-Step Form
+```tsx
+<MultiStepForm>
+  {/* Form steps */}
+</MultiStepForm>
+```
+- **Tab**: Navigate through form fields
+- **Enter**: Submit step or form
+- **Arrow Keys**: Navigate between radio buttons/checkboxes in groups
+
+## Focus Management
+
+### Skip Links
+Allow keyboard users to skip repetitive navigation:
+
+```tsx
+import { SkipLink } from '@zoyth/simple-site-framework'
+
+<SkipLink href="#main">
+  Skip to main content
+</SkipLink>
+<SkipLink href="#nav">
+  Skip to navigation
+</SkipLink>
+```
+
+### Focus Trap (Modals/Dialogs)
+Keep focus inside modal until closed:
+
+```tsx
+import { useFocusTrap } from '@zoyth/simple-site-framework'
+
+function Modal({ isOpen, children }) {
+  const trapRef = useFocusTrap(isOpen)
+
+  return (
+    <div ref={trapRef} role="dialog">
+      {children}
+    </div>
+  )
+}
+```
+
+### Focus Return
+Return focus to trigger element after modal closes:
+
+```tsx
+import { useFocusReturn } from '@zoyth/simple-site-framework'
+
+function Modal() {
+  const returnRef = useFocusReturn()
+
+  return <div ref={returnRef}>{/* content */}</div>
+}
+```
+
+## Testing Keyboard Navigation
+
+### Manual Testing Checklist
+1. **Unplug your mouse** (or don't touch it)
+2. **Tab through entire page**
+   - Can you reach all interactive elements?
+   - Is tab order logical?
+   - Is focus visible on all elements?
+3. **Open and close all modals/menus**
+   - Does Escape close them?
+   - Does focus stay trapped inside?
+   - Does focus return when closed?
+4. **Submit all forms**
+   - Can you fill out and submit with only keyboard?
+   - Are errors announced?
+5. **Navigate all components**
+   - Do tabs work with arrows?
+   - Do dropdowns work as expected?
+   - Do carousels respond to arrows?
+
+### Automated Testing
+```tsx
+import { testKeyboardNav } from '@zoyth/simple-site-framework/testing'
+
+describe('Button', () => {
+  it('should activate on Enter and Space', () => {
+    const onClick = jest.fn()
+    const { getByRole } = render(<Button onClick={onClick}>Click</Button>)
+
+    testKeyboardNav(getByRole('button'), {
+      enter: onClick,
+      space: onClick
+    })
+  })
+})
+```
+
+## Common Keyboard Traps (and How to Avoid)
+
+### ❌ Keyboard Trap
+```tsx
+// BAD: Focus gets stuck in modal
+<div onClick={() => setOpen(false)}>
+  <input /> {/* Focus can't reach close button */}
+</div>
+```
+
+### ✅ Proper Modal
+```tsx
+// GOOD: Use framework Modal with focus trap
+<Modal isOpen={isOpen} onClose={() => setOpen(false)}>
+  <input />
+  <Button onClick={() => setOpen(false)}>Close</Button>
+</Modal>
+```
+
+### ❌ Missing Tab Index
+```tsx
+// BAD: Custom div button not keyboard accessible
+<div onClick={handleClick}>Click me</div>
+```
+
+### ✅ Semantic Button
+```tsx
+// GOOD: Use semantic button or framework Button
+<Button onClick={handleClick}>Click me</Button>
+```
+
+### ❌ No Escape to Close
+```tsx
+// BAD: No way to close with keyboard
+<div className="modal">
+  <button onClick={handleClose}>×</button>
+</div>
+```
+
+### ✅ Escape Handler
+```tsx
+// GOOD: Escape key closes modal
+<Modal onClose={handleClose} isOpen={isOpen}>
+  {/* content */}
+</Modal>
+```
+
+## Focus Indicator Best Practices
+
+### Visible Focus
+All framework components have visible focus indicators:
+```css
+/* Default focus ring */
+.button:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+```
+
+### Custom Focus Styles
+Override in your theme:
+```tsx
+const theme = {
+  colors: {
+    focusRing: '#FF7800',
+  },
+  // ...
+}
+```
+
+### Never Remove Focus
+```css
+/* ❌ NEVER DO THIS */
+*:focus {
+  outline: none;
+}
+
+/* ✅ Style it, but keep it visible */
+*:focus-visible {
+  outline: 2px solid blue;
+  outline-offset: 2px;
+}
+```
+
+## Resources
+
+- [WebAIM Keyboard Testing](https://webaim.org/articles/keyboard/)
+- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
+- [Framework Component Guides](./components/)

package/docs/accessibility/overview.md

@@ -0,0 +1,122 @@
+# Accessibility Overview
+
+The Simple Site Framework is built with accessibility as a core principle, ensuring that all components meet WCAG 2.1 Level AA standards by default.
+
+## Our Commitment
+
+- **Semantic HTML**: All components use proper HTML5 semantic elements
+- **Keyboard Navigation**: Full keyboard support for all interactive elements
+- **Screen Reader Support**: ARIA attributes and announcements where needed
+- **Color Contrast**: AA-compliant color ratios (4.5:1 for text, 3:1 for UI)
+- **Focus Management**: Clear focus indicators and logical focus order
+- **Responsive**: Touch targets meet minimum 44x44px on mobile
+
+## WCAG 2.1 AA Compliance
+
+All framework components are designed to meet:
+- **Perceivable**: Content visible to all users
+- **Operable**: Interface usable via keyboard and other input methods
+- **Understandable**: Clear labels, instructions, and error messages
+- **Robust**: Compatible with assistive technologies
+
+## Quick Start
+
+### 1. Use Semantic Components
+```tsx
+// Good - semantic and accessible
+<Button onClick={handleClick}>Submit</Button>
+
+// Avoid - div buttons need extra work
+<div onClick={handleClick}>Submit</div>
+```
+
+### 2. Add ARIA Labels
+```tsx
+<Button
+  icon={<Icons.Search />}
+  iconOnly
+  aria-label="Search"
+/>
+```
+
+### 3. Test with Keyboard
+All interactive elements should work with:
+- `Tab` - Navigate forward
+- `Shift + Tab` - Navigate backward
+- `Enter/Space` - Activate buttons
+- `Escape` - Close modals/menus
+- `Arrow keys` - Navigate within components
+
+### 4. Check Color Contrast
+Use our built-in utilities or browser DevTools to verify:
+- Normal text: 4.5:1 minimum
+- Large text (18pt+): 3:1 minimum
+- UI components: 3:1 minimum
+
+## Testing Tools
+
+### Development
+> **Note**: The `A11yChecker` component is planned for v0.2.0 and not yet available.
+
+For now, use these external tools for accessibility testing:
+
+### Automated Testing
+- **axe DevTools**: Browser extension for automated accessibility testing
+- **WAVE**: Browser extension for manual testing
+- **Lighthouse**: Chrome DevTools accessibility audit
+- **axe-core**: Can be integrated into your test suite
+
+### Screen Reader Testing
+- **Windows**: NVDA (free) or JAWS
+- **macOS**: VoiceOver (built-in)
+- **Mobile**: TalkBack (Android), VoiceOver (iOS)
+
+## Common Patterns
+
+### Skip Links
+```tsx
+import { SkipLink } from '@zoyth/simple-site-framework'
+
+<SkipLink href="#main">Skip to main content</SkipLink>
+```
+
+### Screen Reader Announcements
+```tsx
+import { useA11y } from '@zoyth/simple-site-framework'
+
+const { announce } = useA11y()
+
+const handleSubmit = async () => {
+  await submitForm()
+  announce('Form submitted successfully')
+}
+```
+
+### Focus Management
+```tsx
+import { useFocusTrap } from '@zoyth/simple-site-framework'
+
+function Modal({ isOpen }) {
+  const trapRef = useFocusTrap(isOpen)
+
+  return (
+    <div ref={trapRef} role="dialog" aria-modal="true">
+      {/* Modal content */}
+    </div>
+  )
+}
+```
+
+## Resources
+
+- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/)
+- [A11y Project Checklist](https://www.a11yproject.com/checklist/)
+- [WebAIM Resources](https://webaim.org/resources/)
+- [Component A11y Guides](./components/)
+
+## Need Help?
+
+- Review component-specific guides in [./components/](./components/)
+- Check the [accessibility checklist](./wcag-compliance.md)
+- Test with [keyboard navigation guide](./keyboard-navigation.md)
+- Verify with [screen reader testing guide](./screen-readers.md)

package/docs/accessibility/screen-readers.md

@@ -0,0 +1,311 @@
+# Screen Reader Testing Guide
+
+Testing with screen readers is essential to ensure your site is accessible to users with visual impairments.
+
+## Screen Reader Software
+
+### Windows
+**NVDA (Free, Open Source)**
+- Download: https://www.nvaccess.org/
+- Most popular free option
+- Good compatibility with modern web standards
+
+**JAWS (Commercial)**
+- Most widely used by professionals
+- Expensive ($1000+)
+- Very thorough testing tool
+
+### macOS
+**VoiceOver (Built-in)**
+- Cmd + F5 to toggle on/off
+- Free and pre-installed
+- Good for basic testing
+
+### Mobile
+**iOS VoiceOver**
+- Settings → Accessibility → VoiceOver
+- Triple-click home button shortcut
+
+**Android TalkBack**
+- Settings → Accessibility → TalkBack
+- Volume keys shortcut
+
+## Quick Start with NVDA (Windows)
+
+### Basic Controls
+- **NVDA + Space**: Toggle browse/focus mode
+- **↓**: Read next item
+- **↑**: Read previous item
+- **Tab**: Navigate to next focusable element
+- **NVDA + T**: Read window title
+- **NVDA + B**: Read entire page
+- **Insert**: NVDA modifier key
+
+### Testing Workflow
+1. Start NVDA
+2. Open your site
+3. Press **NVDA + B** to read entire page
+4. Use **↓** to navigate item by item
+5. Use **Tab** to jump between interactive elements
+6. Listen for:
+   - Clear labels and descriptions
+   - Proper heading hierarchy
+   - Form field labels
+   - Button text
+   - Image alt text
+   - Error messages
+
+## Quick Start with VoiceOver (macOS)
+
+### Basic Controls
+- **Cmd + F5**: Toggle VoiceOver on/off
+- **VO + →**: Next item (VO = Ctrl + Option)
+- **VO + ←**: Previous item
+- **VO + Cmd + H**: Next heading
+- **VO + Cmd + Shift + H**: Previous heading
+- **VO + U**: Open rotor (navigation menu)
+- **Tab**: Next focusable element
+
+### Testing Workflow
+1. Press **Cmd + F5** to start
+2. Open your site
+3. Press **VO + A** to read entire page
+4. Use **VO + →** to navigate
+5. Press **VO + U** for rotor navigation
+6. Test interactions with **VO + Space**
+
+## What to Listen For
+
+### ✅ Good Screen Reader Experience
+- **Descriptive labels**: "Submit contact form" not just "Submit"
+- **Clear headings**: "Contact Us - heading level 2"
+- **Form labels**: "Email address, edit text, required"
+- **Error messages**: "Email address, invalid format, edit text"
+- **State changes**: "Loading complete" announcements
+- **Alt text**: "Company logo" not "image-logo-final-v2.png"
+
+### ❌ Poor Screen Reader Experience
+- "Button" with no label
+- "Image" with no alt text
+- "Required" not announced
+- "Edit text" with no label
+- No headings or all h1s
+- Silent state changes
+- "Click here" links
+
+## Component Testing Examples
+
+### Button
+```tsx
+<Button onClick={handleSubmit}>Submit Form</Button>
+```
+**Reads**: "Submit Form, button"
+
+### Icon Button
+```tsx
+<Button icon={<Icons.Search />} iconOnly aria-label="Search">
+```
+**Reads**: "Search, button"
+
+### Form Field
+```tsx
+<FormField
+  name="email"
+  label="Email Address"
+  required
+  error={errors.email}
+>
+  <input type="email" {...register('email')} />
+</FormField>
+```
+**Reads**: "Email Address, edit text, required"
+**If error**: "Email Address, invalid format, edit text, required"
+
+### Modal
+```tsx
+<Modal isOpen={true} title="Confirm Action">
+  <p>Are you sure?</p>
+</Modal>
+```
+**Reads**: "Confirm Action, dialog"
+**Announces**: When modal opens, focus moves and title is read
+
+### Live Region (Toast)
+```tsx
+toast.success('Form submitted successfully')
+```
+**Announces**: "Form submitted successfully" (polite)
+
+### Loading State
+```tsx
+<Button loading={true}>Submit</Button>
+```
+**Reads**: "Submit, button, busy"
+
+## ARIA Attributes and What They Do
+
+### aria-label
+Provides accessible name when visible text isn't enough:
+```tsx
+<Button icon={<Icons.Close />} aria-label="Close dialog" />
+```
+**Reads**: "Close dialog, button"
+
+### aria-labelledby
+References another element for label:
+```tsx
+<div role="dialog" aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Confirm Delete</h2>
+</div>
+```
+**Reads**: "Confirm Delete, dialog"
+
+### aria-describedby
+Provides additional description:
+```tsx
+<input
+  id="password"
+  type="password"
+  aria-describedby="password-hint"
+/>
+<p id="password-hint">
+  Must be at least 8 characters
+</p>
+```
+**Reads**: "Password, edit text. Must be at least 8 characters"
+
+### aria-live
+Announces dynamic content changes:
+```tsx
+<div aria-live="polite" aria-atomic="true">
+  {statusMessage}
+</div>
+```
+**Announces**: When statusMessage changes
+
+### aria-hidden
+Hides decorative content:
+```tsx
+<span aria-hidden="true">★</span>
+<span className="sr-only">5 out of 5 stars</span>
+```
+**Reads**: "5 out of 5 stars" (star icon ignored)
+
+## Common Screen Reader Issues
+
+### Issue: Button Reads as "Button" Only
+**Problem**: No accessible text
+```tsx
+<button onClick={handleClick}>
+  <Icon name="trash" />
+</button>
+```
+**Fix**: Add aria-label
+```tsx
+<Button
+  icon={<Icons.Trash />}
+  iconOnly
+  aria-label="Delete item"
+/>
+```
+
+### Issue: Form Field Not Associated with Label
+**Problem**: Label not programmatically connected
+```tsx
+<label>Email</label>
+<input type="email" />
+```
+**Fix**: Use for/id or nest input
+```tsx
+<FormField name="email" label="Email">
+  <input type="email" />
+</FormField>
+```
+
+### Issue: State Changes Not Announced
+**Problem**: Loading/success state is visual only
+```tsx
+<button disabled={isLoading}>
+  {isLoading ? 'Loading...' : 'Submit'}
+</button>
+```
+**Fix**: Use aria-busy or toast announcement
+```tsx
+<Button loading={isLoading}>Submit</Button>
+```
+
+### Issue: Modal Focus Not Managed
+**Problem**: Focus doesn't move to modal
+```tsx
+<div className={isOpen ? 'modal' : 'modal hidden'}>
+  {/* content */}
+</div>
+```
+**Fix**: Use framework Modal
+```tsx
+<Modal isOpen={isOpen} onClose={handleClose}>
+  {/* content */}
+</Modal>
+```
+
+## Testing Checklist
+
+- [ ] All buttons and links have accessible text
+- [ ] All form fields have associated labels
+- [ ] Required fields are announced as required
+- [ ] Form errors are announced clearly
+- [ ] Headings create logical document outline
+- [ ] Images have descriptive alt text (or alt="" if decorative)
+- [ ] Modals announce when opened
+- [ ] Focus moves logically through page
+- [ ] State changes (loading, success, error) are announced
+- [ ] Skip links work
+- [ ] Data tables have proper headers
+- [ ] Live regions announce dynamic content
+
+## Framework Utilities for Screen Readers
+
+### useA11y Hook
+```tsx
+import { useA11y } from '@zoyth/simple-site-framework'
+
+const { announce } = useA11y()
+
+const handleSubmit = async () => {
+  await submitForm()
+  announce('Form submitted successfully', 'polite')
+}
+```
+
+### A11yAnnouncer Component
+```tsx
+import { A11yAnnouncer } from '@zoyth/simple-site-framework'
+
+<A11yAnnouncer
+  message={statusMessage}
+  politeness="polite" // or "assertive"
+/>
+```
+
+### Screen Reader Only Text
+```tsx
+// Visible to screen readers, hidden visually
+<span className="sr-only">Required field</span>
+```
+
+## Resources
+
+- [NVDA User Guide](https://www.nvaccess.org/files/nvda/documentation/userGuide.html)
+- [VoiceOver Guide](https://www.apple.com/voiceover/info/guide/)
+- [WebAIM Screen Reader Testing](https://webaim.org/articles/screenreader_testing/)
+- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
+
+## Pro Tips
+
+1. **Test early and often** - Don't wait until the end
+2. **Listen to the full page** - Navigate start to finish
+3. **Test forms completely** - Fill out, submit, handle errors
+4. **Test all interactive elements** - Buttons, links, modals, etc.
+5. **Test with real users** - Nothing beats actual screen reader users
+6. **Keep it simple** - Don't over-use ARIA, semantic HTML is often enough
+7. **Test on mobile** - VoiceOver/TalkBack usage is common