# 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