diff --git a/CLAUDE.md b/CLAUDE.md index 842bc58..9ff3477 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,6 +20,8 @@ See @AGENTS.md for project overview, architecture rules, and the AI developer pr - **[docs/IMPLEMENTATION-PLAN.md](docs/IMPLEMENTATION-PLAN.md)** — incremental milestone plan (M0–M6), MVP boundary, per-milestone tests + manual checks, and an architecture reference index. +- **[docs/manual-verification.md](docs/manual-verification.md)** — standing QA checklist for + what tests can't cover (offline/install, keyboard/a11y, theming, reduced-motion). - **[AGENTS.md](AGENTS.md)** — onboarding, stack, directory map, scripts, conventions. ## Quick Orientation diff --git a/docs/manual-verification.md b/docs/manual-verification.md new file mode 100644 index 0000000..33fe86c --- /dev/null +++ b/docs/manual-verification.md @@ -0,0 +1,50 @@ +# Manual Verification Checklist + +> A standing memo, **not** a milestone. These are the things automated tests can't +> cover — they need a real browser, a real install, or a human eye. Run the relevant +> sections before a release, or after any change to the app shell, PWA config, +> routing, theming, or focus/keyboard behavior. Tests stay green ≠ these pass. + +## Offline & installable (PWA) + +- [ ] First load online, then go offline (DevTools → Network → Offline) and reload — + the app boots, fonts render (no system-font fallback), a previously-opened + snippet still renders. +- [ ] Install as a standalone app (desktop install button / Android "Add to Home + screen") — it installs, launches in its own window, and shows the astrolabe + icon (not a generic glyph). +- [ ] Android adaptive icon (maskable) fills the OS shape without clipping the mark. +- [ ] Service-worker update flow: ship a new build, reload — the update-available + prompt appears and applying it loads the new version (`registerType: 'prompt'`). +- [ ] iOS home-screen icon — **known residual**: the manifest ships SVG only; iOS + wants a PNG `apple-touch-icon`, so the iOS home-screen icon may fall back. + +## Keyboard & accessibility + +- [ ] Full keyboard-only run-through: create/select/edit a snippet, open and dismiss + each modal, drive the pane toggle strip and both resize handles, reach Datasets. +- [ ] Focus is never orphaned or trapped: modals trap focus and return it to the + opener on close; hiding a pane from the strip keeps focus on the toggle. +- [ ] Visible focus ring on every interactive control, in both themes. +- [ ] Text and UI contrast pass AA in light and dark. + +## Routing & view-state + +- [ ] Reload restores the view from the URL hash (`#snippet-`, `#datasets/…`). +- [ ] Browser Back/Forward moves through view-state as expected. + +## Theming + +- [ ] Light⇄dark flip repaints the whole app — chrome, Monaco, and the chart. +- [ ] No placeholder styling or raw hexes leak through on any surface. + +## Reduced motion & feedback + +- [ ] With `prefers-reduced-motion`, toasts and transitions honor it (no large motion). +- [ ] Toasts stack, auto-dismiss, and fade as specified; the live-preview busy + indicator appears for slow (>~1s) renders and clears after. + +## Visual sweep of the M6 surfaces + +- [ ] Library search / sort / empty states, the storage monitor, About & Donate + modals, and the busy indicator all look deliberate and behave per spec.