Theme Editor P1: User workflows, inspector mode, and WCAG 2.2 AA accessibility

THEME_EDITOR_P1_QUICK_REFERENCE.md

@@ -0,0 +1,280 @@
+# Theme Editor P1 - Quick Reference Card
+
+## 🎨 Color Schemes (8 Presets)
+
+```typescript
+import { DEFAULT_COLOR_SCHEMES, ColorScheme } from '@/lib/storefront/color-schemes';
+
+// Apply a color scheme
+const scheme = DEFAULT_COLOR_SCHEMES.find(s => s.id === 'modern-blue');
+updateTheme({ colors: scheme.colors });
+
+// Categories: 'Modern' | 'Vibrant' | 'Luxury'
+// All schemes meet WCAG AA contrast (4.5:1)
+```
+
+## ✍️ Typography Presets (6 Pairings)
+
+```typescript
+import { DEFAULT_TYPOGRAPHY_PRESETS, TypographyPreset } from '@/lib/storefront/typography-presets';
+
+// Apply a typography preset
+const preset = DEFAULT_TYPOGRAPHY_PRESETS.find(p => p.id === 'modern-sans');
+updateTheme({ typography: preset.settings });
+
+// Calculate heading sizes
+const sizes = calculateHeadingSizes(16, 1.25);
+// Returns: { h1: 31, h2: 25, h3: 20, h4: 16, h5: 13, h6: 10 }
+```
+
+## 📦 Section Registry (9 Sections)
+
+```typescript
+import { SECTION_REGISTRY, SectionMetadata } from '@/lib/storefront/section-registry';
+
+// Get all sections
+const allSections = SECTION_REGISTRY;
+
+// Filter by category
+const commerceSections = filterByCategory('Commerce');
+
+// Search by keyword
+const results = searchSections('product');
+
+// Categories: 'Header' | 'Commerce' | 'Marketing' | 'Social' | 'Content'
+```
+
+## 🔍 Inspector Mode
+
+### Enable/Disable
+```typescript
+// Parent editor window
+window.postMessage({
+  type: 'STORMCOM_SET_INSPECTOR',
+  enabled: true,
+}, window.location.origin);
+```
+
+### Handle Section Selection
+```typescript
+// Listen for section selection
+window.addEventListener('message', (event) => {
+  if (event.data.type === 'STORMCOM_SELECT_SECTION') {
+    const sectionId = event.data.sectionId;
+    // Navigate to section settings
+  }
+});
+```
+
+### Keyboard Shortcuts
+- `Click` - Select section
+- `Enter` - Select hovered section
+- `Esc` - Exit inspector mode
+
+## ♿ Accessibility Features
+
+### Skip Links
+```html
+<!-- Hidden until focused -->
+<a href="#editor-toolbar">Skip to toolbar</a>
+<a href="#editor-sidebar">Skip to sections</a>
+<a href="#preview-pane">Skip to preview</a>
+```
+
+### Keyboard Shortcuts
+```typescript
+const SHORTCUTS = {
+  'Ctrl+S': 'Save changes',
+  'Ctrl+Z': 'Undo',
+  'Ctrl+Shift+Z': 'Redo',
+  'Ctrl+I': 'Toggle inspector',
+  'Esc': 'Close modal/Exit mode',
+  '?': 'Show shortcuts',
+};
+```
+
+### Live Announcements
+```typescript
+// Announce to screen readers
+setAnnouncement('Theme applied successfully');
+```
+
+### ARIA Labels
+```html
+<!-- Color scheme button -->
+<button
+  aria-label="Apply Modern Blue color scheme"
+  aria-pressed={isActive}
+>
+  Modern Blue
+</button>
+
+<!-- Slider with value -->
+<input
+  type="range"
+  aria-label="Base font size"
+  aria-valuetext="16 pixels"
+/>
+```
+
+## 🧪 Testing Checklist
+
+### Unit Tests
+```typescript
+// Color schemes
+expect(DEFAULT_COLOR_SCHEMES).toHaveLength(8);
+
+// Typography presets
+expect(DEFAULT_TYPOGRAPHY_PRESETS).toHaveLength(6);
+
+// Section registry
+expect(SECTION_REGISTRY).toHaveLength(9);
+```
+
+### Integration Tests
+```typescript
+// Apply color scheme
+render(<ColorSchemeSelector />);
+fireEvent.click(screen.getByLabelText('Apply Modern Blue'));
+expect(mockUpdate).toHaveBeenCalledWith({ colors: expect.objectContaining({ primary: '#3b82f6' }) });
+```
+
+### Playwright E2E
+```typescript
+// Inspector workflow
+await page.click('[aria-label="Toggle inspector mode"]');
+await page.frameLocator('iframe').locator('[data-section-id="hero"]').click();
+await expect(page.locator('text=Hero Section Settings')).toBeVisible();
+```
+
+### Accessibility Audit
+```typescript
+import { checkA11y } from 'axe-playwright';
+await checkA11y(page, null, { runOnly: { type: 'tag', values: ['wcag2aa'] } });
+```
+
+## 📐 Component Usage
+
+### ColorSchemeSelector
+```typescript
+<ColorSchemeSelector
+  currentColors={theme.colors}
+  onColorChange={(colors) => updateTheme({ colors })}
+/>
+```
+
+### TypographyPresetSelector
+```typescript
+<TypographyPresetSelector
+  currentSettings={theme.typography}
+  onSettingsChange={(settings) => updateTheme({ typography: settings })}
+/>
+```
+
+### AddSectionModalEnhanced
+```typescript
+<AddSectionModalEnhanced
+  open={isOpen}
+  onOpenChange={setIsOpen}
+  disabledSections={currentSections}
+  onAddSection={(sectionId) => addSection(sectionId)}
+/>
+```
+
+### InspectorOverlay
+```typescript
+// Auto-enabled when inspector mode is active
+// Renders in preview iframe
+<InspectorOverlay />
+```
+
+### AccessibilityEnhancements
+```typescript
+// Renders globally in editor layout
+<AccessibilityEnhancements
+  onNavigate={(target) => scrollToSection(target)}
+/>
+```
+
+## 🎯 PostMessage Protocol
+
+### Messages Sent (Parent → Preview)
+```typescript
+// Update theme
+window.postMessage({
+  type: 'STORMCOM_UPDATE_CONFIG',
+  config: storefrontConfig,
+}, '*');
+
+// Toggle inspector
+window.postMessage({
+  type: 'STORMCOM_SET_INSPECTOR',
+  enabled: true,
+}, '*');
+```
+
+### Messages Received (Preview → Parent)
+```typescript
+// Section selected
+{
+  type: 'STORMCOM_SELECT_SECTION',
+  sectionId: 'hero',
+}
+```
+
+## 🚀 Performance Tips
+
+1. **Debounce Updates**: Wait 300ms before sending PostMessage
+2. **Memoize Selectors**: Use React.memo for preset selectors
+3. **CSS Variables**: Fast theme updates via custom properties
+4. **Lazy Load**: Only render inspector when active
+5. **Efficient Queries**: Filter registry data client-side
+
+## 📚 File Locations
+
+| Component | Path |
+|-----------|------|
+| Color Schemes | `src/lib/storefront/color-schemes.ts` |
+| Typography | `src/lib/storefront/typography-presets.ts` |
+| Registry | `src/lib/storefront/section-registry.ts` |
+| Color Selector | `src/components/dashboard/storefront/editor/color-scheme-selector.tsx` |
+| Typography Selector | `src/components/dashboard/storefront/editor/typography-preset-selector.tsx` |
+| Add Section Modal | `src/components/dashboard/storefront/editor/add-section-modal-enhanced.tsx` |
+| Inspector Overlay | `src/components/storefront/inspector-overlay.tsx` |
+| Accessibility | `src/components/dashboard/storefront/editor/accessibility-enhancements.tsx` |
+
+## 🐛 Common Issues
+
+### Inspector not working
+- Check iframe origin matches parent origin
+- Verify data-section-id attributes on sections
+- Check PostMessage event listeners
+
+### Color scheme not applying
+- Verify PostMessage sent to preview iframe
+- Check CSS variable names match
+- Verify theme.colors structure
+
+### Keyboard shortcuts not working
+- Check for input/textarea focus
+- Verify event.preventDefault() called
+- Check keyboard event bubbling
+
+### Screen reader announcements not working
+- Verify live region has role="status"
+- Check aria-live="polite" attribute
+- Ensure announcement text changes
+
+## 📖 Further Reading
+
+- [Full Implementation Doc](./THEME_EDITOR_P1_IMPLEMENTATION.md)
+- [WCAG 2.2 Guidelines](https://www.w3.org/WAI/WCAG22/quickref/)
+- [Next.js 16 Docs](https://nextjs.org/docs)
+- [shadcn-ui Docs](https://ui.shadcn.com/)
+- [PostMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage)
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: February 14, 2026  
+**Status**: ✅ P1 Complete