@zoyth/simple-site-framework 1.0.0

package/docs/features/accessibility/color-contrast.md

@@ -0,0 +1,155 @@
+# Color Contrast
+
+Ensure text and interactive elements meet contrast requirements.
+
+## WCAG Contrast Requirements
+
+### AA (Minimum)
+
+| Element | Ratio Required |
+|---------|---------------|
+| Normal text (< 18px) | 4.5:1 |
+| Large text (>= 18px bold, >= 24px) | 3:1 |
+| UI components and graphical objects | 3:1 |
+
+### AAA (Enhanced)
+
+| Element | Ratio Required |
+|---------|---------------|
+| Normal text | 7:1 |
+| Large text | 4.5:1 |
+
+## Framework Theme Defaults
+
+The default theme colors are designed to meet WCAG AA:
+
+```typescript
+theme: {
+  primary: '#0066CC',    // Tested against white background
+  secondary: '#FF6600',  // Tested against white background
+  text: '#1a1a1a',       // High contrast on white
+  background: '#ffffff',
+}
+```
+
+## Checking Contrast
+
+### Browser DevTools
+
+1. Open DevTools > Elements
+2. Select a text element
+3. Click the color swatch in Styles
+4. DevTools shows contrast ratio and pass/fail
+
+### Online Tools
+
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- [Coolors Contrast Checker](https://coolors.co/contrast-checker)
+
+### Programmatic Checks
+
+```typescript
+// Calculate contrast ratio
+function getContrastRatio(color1: string, color2: string): number {
+  const lum1 = getLuminance(color1);
+  const lum2 = getLuminance(color2);
+  const lightest = Math.max(lum1, lum2);
+  const darkest = Math.min(lum1, lum2);
+  return (lightest + 0.05) / (darkest + 0.05);
+}
+```
+
+## Common Contrast Issues
+
+### Light Gray Text
+
+```css
+/* ❌ Fails - 2.4:1 ratio */
+color: #999999;
+background: #ffffff;
+
+/* ✅ Passes - 4.6:1 ratio */
+color: #767676;
+background: #ffffff;
+```
+
+### Colored Backgrounds
+
+```css
+/* ❌ May fail - check contrast */
+color: #ffffff;
+background: #66ccff;
+
+/* ✅ Better - darker background */
+color: #ffffff;
+background: #0066cc;
+```
+
+### Placeholder Text
+
+```css
+/* Input placeholders need 4.5:1 too */
+/* ❌ Too light */
+::placeholder { color: #cccccc; }
+
+/* ✅ Sufficient contrast */
+::placeholder { color: #767676; }
+```
+
+## Focus Indicators
+
+Focus indicators must be visible against all backgrounds:
+
+```css
+/* Framework default focus styles */
+:focus-visible {
+  outline: 2px solid #0066CC;
+  outline-offset: 2px;
+}
+```
+
+Ensure the focus indicator has at least 3:1 contrast against adjacent colors.
+
+## Theme Customization
+
+When customizing theme colors, verify contrast:
+
+```typescript
+// ✅ Good - verify before setting
+const theme = {
+  primary: '#0055AA',      // 7.1:1 on white ✅
+  primaryText: '#ffffff',   // Check against primary bg
+  text: '#333333',          // 12.6:1 on white ✅
+  mutedText: '#666666',     // 5.7:1 on white ✅
+};
+
+// ❌ Bad - insufficient contrast
+const theme = {
+  primary: '#99ccff',      // 1.8:1 on white ❌
+  text: '#aaaaaa',          // 2.3:1 on white ❌
+};
+```
+
+## Dark Mode Considerations
+
+If implementing dark mode:
+
+- Light text on dark backgrounds still needs 4.5:1
+- Test both themes for contrast compliance
+- Shadows and borders may need adjustment
+- Images with text overlays need extra care
+
+## Best Practices
+
+- Test all color combinations in your design
+- Don't rely on color alone to convey information (use icons, patterns, or text)
+- Test with color blindness simulators
+- Provide sufficient contrast for all text sizes
+- Check contrast of error states, hover states, and disabled states
+- Verify contrast on actual devices (screens vary)
+
+## See Also
+
+- [WCAG Compliance](../../accessibility/wcag-compliance.md)
+- [Focus Management](./focus-management.md)
+- [Testing](./testing.md)

package/docs/features/accessibility/focus-management.md

@@ -0,0 +1,187 @@
+# Focus Management
+
+Handle keyboard focus for accessible navigation.
+
+## Focus Indicators
+
+All interactive elements must have visible focus indicators:
+
+```css
+/* Framework default */
+:focus-visible {
+  outline: 2px solid #0066CC;
+  outline-offset: 2px;
+}
+
+/* Never remove outlines without replacement */
+/* ❌ Bad */
+:focus { outline: none; }
+
+/* ✅ Good - custom focus style */
+:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.5);
+}
+```
+
+## Focus Trapping
+
+### Modal Focus Trap
+
+The Modal component automatically traps focus:
+
+```typescript
+import { Modal } from '@zoyth/simple-site-framework/components';
+
+<Modal isOpen={isOpen} onClose={handleClose}>
+  {/* Focus is trapped within the modal */}
+  <h2>Modal Title</h2>
+  <p>Content</p>
+  <Button onClick={handleClose}>Close</Button>
+</Modal>
+```
+
+When a modal opens:
+1. Focus moves to first focusable element inside
+2. Tab cycles through modal elements only
+3. Shift+Tab cycles backward
+4. Escape closes the modal
+5. Focus returns to the element that opened it
+
+### ExitIntentModal
+
+Same focus trapping behavior:
+
+```typescript
+<ExitIntentModal isOpen={showModal} onClose={() => setShowModal(false)}>
+  <h2>Wait! Before you go...</h2>
+  <Button>Get 10% Off</Button>
+</ExitIntentModal>
+```
+
+## Focus Restoration
+
+After closing a modal or dropdown, focus should return to the trigger:
+
+```typescript
+function MenuButton() {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const [isOpen, setIsOpen] = useState(false);
+
+  function handleClose() {
+    setIsOpen(false);
+    // Return focus to trigger
+    buttonRef.current?.focus();
+  }
+
+  return (
+    <>
+      <button ref={buttonRef} onClick={() => setIsOpen(true)}>
+        Open Menu
+      </button>
+      {isOpen && <Menu onClose={handleClose} />}
+    </>
+  );
+}
+```
+
+## Skip Links
+
+Allow keyboard users to skip past navigation:
+
+```typescript
+// Framework includes skip link functionality
+<a href="#main-content" className="sr-only focus:not-sr-only">
+  Skip to main content
+</a>
+
+<nav>...</nav>
+
+<main id="main-content">
+  {/* Page content */}
+</main>
+```
+
+## Focus Order
+
+Ensure logical tab order matches visual order:
+
+```typescript
+// ✅ Good - natural DOM order matches visual layout
+<header>
+  <nav>
+    <a href="/">Home</a>
+    <a href="/about">About</a>
+    <a href="/contact">Contact</a>
+  </nav>
+</header>
+<main>...</main>
+<footer>...</footer>
+
+// ❌ Bad - tabIndex overrides break natural order
+<div tabIndex={3}>Third visually, first by tab</div>
+<div tabIndex={1}>First visually, third by tab</div>
+```
+
+### tabIndex Guidelines
+
+| Value | Behavior |
+|-------|----------|
+| `0` | Element is focusable in natural DOM order |
+| `-1` | Focusable programmatically, not by Tab key |
+| `> 0` | Avoid - breaks natural order |
+
+## Managing Focus on Route Changes
+
+In single-page applications, manage focus when content changes:
+
+```typescript
+'use client';
+import { useEffect, useRef } from 'react';
+import { usePathname } from 'next/navigation';
+
+export function FocusManager() {
+  const pathname = usePathname();
+  const mainRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    // Move focus to main content on route change
+    mainRef.current?.focus();
+  }, [pathname]);
+
+  return <main ref={mainRef} tabIndex={-1}>{/* content */}</main>;
+}
+```
+
+## Roving tabIndex
+
+For component groups (tabs, toolbars), use roving tabIndex:
+
+```typescript
+// Only one item in the group is tabbable at a time
+// Arrow keys move focus within the group
+
+<div role="tablist">
+  <button role="tab" tabIndex={activeTab === 0 ? 0 : -1}>Tab 1</button>
+  <button role="tab" tabIndex={activeTab === 1 ? 0 : -1}>Tab 2</button>
+  <button role="tab" tabIndex={activeTab === 2 ? 0 : -1}>Tab 3</button>
+</div>
+```
+
+The Tabs component implements this pattern automatically.
+
+## Best Practices
+
+- Never remove focus indicators without providing a visible alternative
+- Use `:focus-visible` instead of `:focus` to avoid showing outlines on mouse clicks
+- Always return focus to the trigger when closing overlays
+- Keep tab order logical and predictable
+- Use `tabIndex={-1}` for programmatic focus targets
+- Avoid positive `tabIndex` values
+- Test entire pages with keyboard-only navigation
+
+## See Also
+
+- [Keyboard Navigation](../../accessibility/keyboard-navigation.md)
+- [ARIA Support](./aria-support.md)
+- [Modal Component](../../components/ui/Modal.md)

package/docs/features/accessibility/testing.md

@@ -0,0 +1,196 @@
+# Accessibility Testing
+
+Test your site for accessibility compliance.
+
+## Automated Testing
+
+### axe-core
+
+Run automated accessibility audits:
+
+```bash
+npm install -D @axe-core/react
+```
+
+```typescript
+// Enable in development
+if (process.env.NODE_ENV === 'development') {
+  const axe = require('@axe-core/react');
+  const React = require('react');
+  const ReactDOM = require('react-dom');
+  axe(React, ReactDOM, 1000);
+}
+```
+
+### eslint-plugin-jsx-a11y
+
+Catch accessibility issues at lint time:
+
+```bash
+npm install -D eslint-plugin-jsx-a11y
+```
+
+```json
+// .eslintrc.json
+{
+  "extends": ["plugin:jsx-a11y/recommended"]
+}
+```
+
+Catches issues like:
+- Missing alt text on images
+- Missing labels on form inputs
+- Invalid ARIA attributes
+- Incorrect role usage
+
+### Lighthouse
+
+Built into Chrome DevTools:
+
+1. Open DevTools > Lighthouse
+2. Check "Accessibility"
+3. Run audit
+4. Review results and recommendations
+
+## Manual Testing
+
+Automated tools catch ~30% of accessibility issues. Manual testing is essential.
+
+### Keyboard Testing
+
+Test every page with keyboard only:
+
+1. Unplug your mouse
+2. Navigate using Tab, Shift+Tab, Enter, Space, Escape, Arrow keys
+3. Verify:
+   - [ ] Can reach all interactive elements
+   - [ ] Focus indicator is visible
+   - [ ] Tab order is logical
+   - [ ] Modals trap focus
+   - [ ] Focus returns after closing overlays
+   - [ ] No keyboard traps
+
+### Screen Reader Testing
+
+Test with actual screen readers:
+
+| Platform | Screen Reader | Browser |
+|----------|--------------|---------|
+| macOS | VoiceOver | Safari |
+| Windows | NVDA (free) | Firefox |
+| Windows | JAWS | Chrome/Edge |
+| iOS | VoiceOver | Safari |
+| Android | TalkBack | Chrome |
+
+#### VoiceOver Quick Start (macOS)
+
+1. Press `Cmd + F5` to enable VoiceOver
+2. Use `VO + Right Arrow` to move forward (`VO` = Ctrl + Option)
+3. Use `VO + Left Arrow` to move backward
+4. Press `VO + Space` to activate
+5. Press `Cmd + F5` again to disable
+
+#### What to Check
+
+- [ ] Page title is announced on load
+- [ ] Headings create a logical outline
+- [ ] Images have descriptive alt text
+- [ ] Form labels are associated with inputs
+- [ ] Error messages are announced
+- [ ] Dynamic content changes are announced
+- [ ] Navigation landmarks are present
+
+### Zoom Testing
+
+1. Zoom to 200% (Cmd/Ctrl + =)
+2. Verify no content is cut off
+3. Verify no horizontal scrolling on main content
+4. Zoom to 400% for WCAG AAA
+
+### Color Testing
+
+Test for color blindness:
+
+- Chrome DevTools > Rendering > Emulate vision deficiencies
+- Select each deficiency type and verify usability
+- Ensure information isn't conveyed by color alone
+
+## Testing Checklist
+
+### Per Component
+
+- [ ] Keyboard accessible
+- [ ] Screen reader announces correctly
+- [ ] ARIA attributes present and valid
+- [ ] Focus management works
+- [ ] Color contrast passes 4.5:1
+
+### Per Page
+
+- [ ] Single `<h1>` element
+- [ ] Heading hierarchy is logical (no skipped levels)
+- [ ] All images have alt text
+- [ ] All form inputs have labels
+- [ ] Language attribute set on `<html>`
+- [ ] Landmark regions present (banner, nav, main, contentinfo)
+- [ ] Skip link works
+- [ ] Page title is descriptive
+
+### Per Site
+
+- [ ] Consistent navigation across pages
+- [ ] Error pages are accessible
+- [ ] 404 page is accessible
+- [ ] All PDF/document downloads are accessible
+- [ ] Video content has captions
+- [ ] Audio content has transcripts
+
+## CI/CD Integration
+
+### axe in Tests
+
+```typescript
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+it('has no accessibility violations', async () => {
+  const { container } = render(<HeroSection heading="Test" />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+### Pa11y in CI
+
+```bash
+npm install -D pa11y
+
+# Test a URL
+npx pa11y http://localhost:3000
+```
+
+Add to CI pipeline:
+
+```yaml
+# .github/workflows/a11y.yml
+- name: Accessibility test
+  run: npx pa11y http://localhost:3000 --threshold 0
+```
+
+## Reporting Issues
+
+When you find an accessibility issue:
+
+1. **What**: Describe the specific failure
+2. **Where**: Page URL and element location
+3. **WCAG Criterion**: Which guideline is violated
+4. **Impact**: Who is affected and how
+5. **Fix**: Suggested remediation
+
+## See Also
+
+- [WCAG Compliance](../../accessibility/wcag-compliance.md)
+- [Keyboard Navigation](../../accessibility/keyboard-navigation.md)
+- [Screen Readers](../../accessibility/screen-readers.md)
+- [ARIA Support](./aria-support.md)

package/docs/features/analytics/README.md

@@ -0,0 +1,51 @@
+# Analytics
+
+Integrated analytics and tracking for conversion optimization.
+
+## Overview
+
+Simple Site Framework provides built-in analytics integration for tracking user behavior, conversions, and running A/B tests:
+
+- Google Analytics 4 (GA4) integration
+- Google Tag Manager (GTM) support
+- Event tracking utilities
+- A/B testing framework
+- Conversion tracking
+- Privacy-compliant tracking
+
+## Quick Start
+
+```typescript
+import { AnalyticsTracker } from '@zoyth/simple-site-framework/components';
+
+// Add to root layout
+<AnalyticsTracker gtmId="GTM-XXXXXXX" />
+```
+
+Track events:
+
+```typescript
+'use client';
+import { trackEvent, trackCTAClick } from '@zoyth/simple-site-framework/client';
+
+// Track custom event
+trackEvent('button_click', { location: 'hero' });
+
+// Track CTA click
+trackCTAClick('signup', 'hero');
+```
+
+## Topics
+
+- [Setup](./setup.md) - Initial analytics configuration
+- [Tracking Events](./tracking-events.md) - Event tracking patterns
+- [A/B Testing](./ab-testing.md) - Running A/B tests
+- [Conversion Tracking](./conversion-tracking.md) - Track goals and conversions
+- [Custom Events](./custom-events.md) - Define custom events
+- [Privacy](./privacy.md) - GDPR and privacy compliance
+
+## See Also
+
+- [Analytics Setup Guide](../../guides/analytics-setup.md)
+- [AnalyticsTracker Component](../../components/AnalyticsTracker.md)
+- [TrackedLink Component](../../components/TrackedLink.md)