Danilo Reyes
2f096d0265
- Introduced export schema for JSON data structure. - Created renderer contract detailing canvas/SVG rendering requirements. - Defined IndexedDB storage schema and migration strategies. - Documented data model including entities and relationships. - Developed implementation plan outlining execution flow and project structure. - Provided quickstart guide for development environment setup. - Compiled research documentation on performance, accessibility, and theming. - Established feature specification with user scenarios and functional requirements.
80 lines
4.6 KiB
Markdown
80 lines
4.6 KiB
Markdown
# Research — GlowTrack
|
||
|
||
## Decisions
|
||
- Framework: SvelteKit + TypeScript with `@sveltejs/adapter-static` (no backend)
|
||
- Storage: IndexedDB via `idb`; JSON import/export with versioning
|
||
- Visualization: Lightweight Canvas/SVG hybrid renderer optimized for mobile
|
||
- Styling: Tailwind CSS with CSS variables; color-blind friendly palettes
|
||
- Accessibility: Target WCAG AA; keyboard-first interactions
|
||
- PWA: SvelteKit service worker with minimal runtime cache for full offline
|
||
- Tooling/Reproducibility: Nix flake provides devShell and build
|
||
- CI: Nix build + Vitest unit tests + Playwright smoke tests
|
||
- Hosting: GitHub Pages or Netlify (static hosting) from Nix build output
|
||
|
||
## Rationales
|
||
- SvelteKit offers SSR/SSG flexibility and first-class PWA support while remaining light for static export
|
||
- `idb` simplifies IndexedDB usage and supports versioned migrations for local-first data
|
||
- Canvas/SVG hybrid provides high-performance drawing with crisp glyph overlays and accessibility-friendly fallbacks
|
||
- Tailwind accelerates consistent UI while CSS variables enable theming and low-cost runtime adjustments
|
||
- Keeping everything client-side preserves privacy and enables offline-by-default usage
|
||
- Nix ensures reproducible dev environments and CI builds across machines
|
||
|
||
## Alternatives Considered
|
||
- React/Vite: viable but SvelteKit yields smaller bundles and simpler reactivity
|
||
- LocalStorage/WebSQL: insufficient for structured data and migrations; IndexedDB preferred
|
||
- Pure Canvas or pure SVG: hybrid approach chosen to balance performance with resolution-independent elements
|
||
- Service worker libraries (e.g., Workbox): SvelteKit’s built-in SW is sufficient given minimal caching needs
|
||
|
||
## Open Questions (Resolved by requirements/spec)
|
||
- Export format: PNG at screen resolution for sharing/wallpaper
|
||
- Sharing: JSON export/import only; no hosted links or image sharing by app
|
||
- Tile visual rules: Base hue by mood; net habit score controls luminance; negative = static overlay; glyph counts
|
||
|
||
---
|
||
|
||
## Additional Research Backlog (Prioritized)
|
||
|
||
1) Canvas/SVG performance on mobile (P1)
|
||
- Goal: 60 fps for 150–365 tiles with glow/overlay; define rendering budget and fallbacks
|
||
- Deliverable: Benchmark results, thresholds, viz package notes
|
||
- Method: Build FPS harness; test mid/low-end Android + iOS
|
||
|
||
2) IndexedDB schema + import/migration performance (P1)
|
||
- Goal: Reliable imports for multi-year datasets; smooth migrations; responsive UI
|
||
- Deliverable: Import chunk size, transaction strategy, migration template, storage footprint
|
||
- Method: Seed 3-year dataset; time import/migration; measure DB size/quota
|
||
|
||
3) Accessibility palettes and glyph legibility (P1)
|
||
- Goal: WCAG AA contrast; color-blind safe palettes; legible glyphs at small sizes
|
||
- Deliverable: Approved palettes, CSS vars, glyph sizing spec
|
||
- Method: Simulators + Axe checks; user testing if possible
|
||
|
||
4) PWA SW update + offline write safety (P1)
|
||
- Goal: Safe app update with pending writes and schema changes
|
||
- Deliverable: SW update policy, cache versioning, migration + rollback checklist
|
||
- Method: Offline simulation during schema bump; verify no data loss
|
||
|
||
5) PNG export fidelity and limits (P2)
|
||
- Goal: Fast, reliable PNG export with crisp glyphs; cap size to prevent OOM
|
||
- Deliverable: Use toBlob/toDataURL guidance, max dimensions, UX for progress/errors
|
||
- Method: Export month/year grids; measure time/memory/file size
|
||
|
||
6) Keyboard-first grid navigation + SR UX (P2)
|
||
- Goal: Intuitive keyboard nav with correct ARIA; SR speaks mood and counts
|
||
- Deliverable: Roving tabindex model, ARIA roles/labels, SR strings
|
||
- Method: Prototype navigation + Playwright+Axe tests
|
||
|
||
7) Tailwind + CSS variables theming (P2)
|
||
- Goal: Minimal CSS output with dynamic theming; safe class generation
|
||
- Deliverable: Theming tokens and example; purge-safe patterns
|
||
- Method: Prototype theme switcher; inspect bundle size
|
||
|
||
### Active Research Tasks (links)
|
||
- 01: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/01-viz-performance.md
|
||
- 02: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/02-indexeddb-imports-migrations.md
|
||
- 03: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/03-a11y-palettes-glyphs.md
|
||
- 04: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/04-pwa-sw-offline-safety.md
|
||
- 05: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/05-png-export-fidelity.md
|
||
- 06: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/06-keyboard-sr-grid.md
|
||
- 07: /home/jawz/Development/Projects/GlowTrack/specs/001-glowtrack-a-mood/research/07-tailwind-css-vars.md
|