cairnquire/.project/milestones/milestone-05-search-ui.md

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

  • Search UI (input, results) - basic implementation
  • Flexsearch or Pagefind integration
  • Index sync from server on load
  • Incremental index updates via WebSocket

• 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 (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

: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:

<button class="btn btn-primary">Click me</button>

.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