# Milestone 5: Search & UI Polish

**Duration:** 2 weeks  
**Goal:** Fast search, design system, responsive layout, and performance optimization

## Tasks

### Week 9: Search Implementation

- [x] Server-side search index
  - [x] FTS5 virtual table setup
  - [x] Index population from documents
  - [x] Incremental index updates on file changes
  - [x] Search query endpoint
   
- [x] Client-side search
  - [x] Search UI (input, results) - basic implementation
  - [ ] Flexsearch or Pagefind integration
  - [ ] Index sync from server on load
  - [ ] Incremental index updates via WebSocket
    
- [x] Search features
  - [x] Full-text content search
  - [ ] Tag filtering
  - [x] Title search (boosted) — via document title in macOS popover (`632621b`)
  - [ ] Recent results caching
  - [x] Search suggestions (autocomplete) — link autocomplete in editor (`4655008`); global search autocomplete pending

### Week 10: Design System & Performance

- [x] Design system
  - [x] CSS custom properties for theming (`site.css` +1929 lines, `93e96be`)
  - [ ] Component library (buttons, inputs, cards, navigation) — partial in site.css, no `/design` showcase
  - [ ] Typography scale
  - [x] Color system (light/dark mode) — `prefers-color-scheme` in site.css
  - [ ] Spacing scale
  - [ ] `/design` route for browser-based design tool
  
- [x] Responsive layout
  - [x] Mobile-first CSS (`mobile.js` +86, site.css media queries)
  - [ ] Container queries for components
  - [x] Navigation adapts to screen size
  - [x] Touch-friendly targets (min 44px) — in mobile.css
  - [ ] Print styles for documents
  
- [x] Performance optimization
  - [ ] Bundle analysis and optimization
  - [ ] Lazy loading for non-critical components
  - [ ] Image optimization (if applicable)
  - [ ] CSS critical path extraction
  - [x] Service worker for offline caching (`sw.js` updates, `archive.js`)
  
- [x] Accessibility
  - [ ] ARIA labels on interactive elements
  - [x] Keyboard navigation (`keyboard-nav.js` +471 lines)
  - [ ] Focus management
  - [ ] Color contrast compliance (WCAG AA)
  - [ ] Screen reader testing

## Acceptance Criteria

### Functional
- [x] Search returns results in <50ms after initial sync (server-side FTS5)
- [ ] 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
