196 lines
5.4 KiB
Markdown
196 lines
5.4 KiB
Markdown
# 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
|