docs: add project planning documents

2026-04-28 23:59:45 -04:00
commit 8e6646499f
16 changed files with 2343 additions and 0 deletions
--- a/docs/milestones/milestone-05-search-ui.md
+++ b/docs/milestones/milestone-05-search-ui.md
@@ -0,0 +1,195 @@
+# Milestone 5: Search & UI Polish
+
+**Duration:** 2 weeks  
+**Goal:** Fast search, design system, responsive layout, and performance optimization
+
+## Tasks
+
+### Week 9: Search Implementation
+
+- [ ] Server-side search index
+  - FTS5 virtual table setup
+  - Index population from documents
+  - Incremental index updates on file changes
+  - Search query endpoint
+  
+- [ ] Client-side search
+  - Flexsearch or Pagefind integration
+  - Index sync from server on load
+  - Incremental index updates via WebSocket
+  - Search UI (input, results, filters)
+  
+- [ ] Search features
+  - Full-text content search
+  - Tag filtering
+  - Title search (boosted)
+  - Recent results caching
+  - Search suggestions (autocomplete)
+
+### Week 10: Design System & Performance
+
+- [ ] Design system
+  - CSS custom properties for theming
+  - Component library (buttons, inputs, cards, navigation)
+  - Typography scale
+  - Color system (light/dark mode)
+  - Spacing scale
+  - `/design` route for browser-based design tool
+  
+- [ ] Responsive layout
+  - Mobile-first CSS
+  - Container queries for components
+  - Navigation adapts to screen size
+  - Touch-friendly targets (min 44px)
+  - Print styles for documents
+  
+- [ ] Performance optimization
+  - Bundle analysis and optimization
+  - Lazy loading for non-critical components
+  - Image optimization (if applicable)
+  - CSS critical path extraction
+  - Service worker for offline caching
+  
+- [ ] Accessibility
+  - ARIA labels on interactive elements
+  - Keyboard navigation
+  - Focus management
+  - Color contrast compliance (WCAG AA)
+  - Screen reader testing
+
+## Acceptance Criteria
+
+### Functional
+- [ ] Search returns results in <50ms after initial sync
+- [ ] Search works offline after first load
+- [ ] Search supports exact phrases (quoted)
+- [ ] Tag filtering narrows search results
+- [ ] `/design` route displays all components with editable CSS
+- [ ] Dark mode toggles correctly (no flash)
+- [ ] All pages responsive down to 320px width
+- [ ] Keyboard navigation works throughout app
+
+### Non-Functional
+- [ ] Lighthouse score >90 on all metrics
+- [ ] Bundle size <100KB gzipped (JS + CSS)
+- [ ] Time to Interactive <200ms
+- [ ] No layout shift during hydration
+- [ ] CSS custom properties work without JS
+
+### Performance Targets
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Initial Page Load | <100ms | TTFB + FCP |
+| Time to Interactive | <200ms | Hydration complete |
+| Search Query | <50ms | Client-side after sync |
+| Bundle Size | <100KB | Gzipped JS + CSS |
+| Lighthouse Performance | >90 | Chrome DevTools |
+| Accessibility | >90 | Lighthouse a11y |
+
+## Design System Specification
+
+### CSS Custom Properties
+
+```css
+:root {
+  /* Colors */
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+  --color-text: #1f2937;
+  --color-text-muted: #6b7280;
+  --color-background: #ffffff;
+  --color-surface: #f9fafb;
+  --color-border: #e5e7eb;
+  
+  /* Typography */
+  --font-sans: system-ui, -apple-system, sans-serif;
+  --font-mono: ui-monospace, monospace;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  
+  /* Spacing */
+  --space-1: 0.25rem;
+  --space-2: 0.5rem;
+  --space-4: 1rem;
+  --space-8: 2rem;
+  
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
+  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
+  
+  /* Radii */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-text: #f9fafb;
+    --color-text-muted: #9ca3af;
+    --color-background: #111827;
+    --color-surface: #1f2937;
+    --color-border: #374151;
+  }
+}
+```
+
+### Component Examples
+
+**Button:**
+```html
+<button class="btn btn-primary">Click me</button>
+```
+
+```css
+.btn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-2) var(--space-4);
+  border-radius: var(--radius-md);
+  font-size: var(--text-base);
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.btn-primary {
+  background: var(--color-primary);
+  color: white;
+  border: none;
+}
+
+.btn-primary:hover {
+  background: var(--color-primary-hover);
+}
+```
+
+## Deliverables
+
+1. Design system documentation
+2. Component showcase at `/design`
+3. Performance audit report
+4. Accessibility audit report
+5. Search API documentation
+
+## Risk Mitigation
+
+| Risk | Mitigation |
+|------|-----------|
+| Bundle size exceeds target | Tree-shaking, code splitting, lazy loading |
+| Search index too large for client | Pagination, server-side fallback, index pruning |
+| Design system inconsistent | CSS custom properties, component tests, design tokens |
+| Mobile layout issues | Test on real devices, container queries, touch targets |
+
+## Definition of Done
+
+- [ ] All acceptance criteria pass
+- [ ] Lighthouse audit green on all metrics
+- [ ] Manual testing on Chrome, Firefox, Safari, Edge
+- [ ] Mobile testing on iOS Safari and Android Chrome
+- [ ] Screen reader tested (VoiceOver, NVDA)
+- [ ] Performance benchmarks documented
+- [ ] Design system reviewed by team