Ilia Denisov
e193f3ca88
Light has been signed off, so the theme store's default choice is now `system` (it was `dark` during the incremental migration). This matches the app.html pre-paint guard, which already resolved an unset choice via prefers-color-scheme — removing the brief boot-time mismatch where the store re-pinned dark. Users still pin light/dark via the account-menu picker. Updates the store default + its test and the design-system / finalize-plan docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
149 lines
6.5 KiB
Markdown
149 lines
6.5 KiB
Markdown
# UI Client — Finalization Plan
|
||
|
||
The MVP web client (Phases 1–30, [PLAN.md](PLAN.md)) is functionally
|
||
complete. This plan finalizes the **web** experience — visual
|
||
consistency, accessibility, localisation, error UX, installability, and
|
||
documentation — before the native platform wrappers in
|
||
[ROADMAP.md](ROADMAP.md). It absorbs the original Phases 33 (PWA) and 35
|
||
(Polish), which were pulled forward to here.
|
||
|
||
**This is a finalization pass, not the final word.** After it ships, the
|
||
owner exercises the whole UI by hand and brings small-nuance fixes; the
|
||
last stage (F8) is an explicit, open-ended owner-driven refinement loop.
|
||
The earlier stages are "done" when their acceptance holds; the feature
|
||
set is "final" only when the owner signs off.
|
||
|
||
Each stage ends with a runnable, reviewable artifact and is gated on the
|
||
per-stage CI rule (push, watch `go-unit` / `ui-test` to green) before
|
||
being marked done.
|
||
|
||
---
|
||
|
||
## F1 — Visual design system — done
|
||
|
||
Merged to `development` via PR #26 (2026-05-22): a shared design-token
|
||
system (`ui/frontend/src/lib/theme/`), light/dark theming with a picker
|
||
and pre-paint guard, and the whole UI migrated onto the tokens.
|
||
Documented literal exceptions: the battle-scene data-viz palette, overlay
|
||
scrims, and directional/deliberate drop shadows. The default theme
|
||
follows the OS (`system`); the account-menu picker pins light or dark.
|
||
Tokens and conventions live in `ui/docs/design-system.md`.
|
||
|
||
Goal: replace the ad-hoc per-component styling (inline hex colors like
|
||
`#0a0e1a`, one-off spacing) with a shared design language so every view
|
||
looks like one product.
|
||
|
||
- `ui/frontend/src/lib/theme/` (or `app.css` `:root`) design tokens:
|
||
color palette (surface / border / text / accent / danger), spacing
|
||
scale, radii, typography, focus-ring style — as CSS custom properties.
|
||
- Migrate components to the tokens (calculator, inspectors, sidebar,
|
||
tables, lobby, auth) — replace literal hex/px with `var(--…)`.
|
||
- Topic doc `ui/docs/design-system.md` documenting the tokens and usage.
|
||
|
||
Acceptance: no literal theme colors left in component `<style>` blocks
|
||
(spot-checked); a single token change restyles the app coherently.
|
||
Consider the `frontend-design` skill for the palette/spacing pass.
|
||
|
||
## F2 — Accessibility (WCAG 2.2 AA) — done
|
||
|
||
Shared a11y primitives (`.sr-only`, `.skip-link`, `trapFocus`,
|
||
`restoreFocus`, the `--color-focus` ring), keyboard paths and ARIA across
|
||
login / lobby / in-game shell (skip links + landmarks, WAI-ARIA sidebar
|
||
tabs with roving + arrow keys, menu Escape + focus restore, the mail
|
||
compose modal dialog with a focus trap), and the map canvas handled as a
|
||
labelled accessible-alternative surface (data via the sidebar/tables).
|
||
Gated by `tests/e2e/a11y-axe.spec.ts` (axe WCAG 2.2 AA scan of every
|
||
top-level view, chromium-desktop, zero violations) and
|
||
`tests/e2e/a11y-keyboard.spec.ts`. Documented in `ui/docs/a11y.md`.
|
||
|
||
(From Phase 35.) Goal: the whole client is usable by keyboard and
|
||
assistive tech.
|
||
|
||
- Keyboard-only paths for login, lobby, and the in-game shell; visible
|
||
focus rings (from the F1 token); ARIA labels/roles; screen-reader-only
|
||
text where needed.
|
||
- `ui/docs/a11y.md` audit results.
|
||
|
||
Acceptance: WCAG 2.2 AA on lobby, login, and the in-game shell per an
|
||
axe-core scan; full keyboard reachability with visible focus.
|
||
Tests: axe-core integration tests on every top-level view; Playwright
|
||
keyboard-only navigation.
|
||
|
||
## F3 — Localisation completeness
|
||
|
||
(From Phase 35.) Goal: every visible string is translated (en + ru).
|
||
|
||
- Audit all components for hard-coded strings; move them into the i18n
|
||
bundles; missing-key detection test; locale-switch persistence across
|
||
reloads.
|
||
|
||
Acceptance: no untranslated visible strings; missing-translation test is
|
||
green; locale persists. Tests: Vitest i18n bundle-structure +
|
||
missing-key detection.
|
||
|
||
## F4 — Error & state UX
|
||
|
||
(From Phase 35, plus the deferred Phase 13/35 items.) Goal: consistent,
|
||
actionable feedback everywhere.
|
||
|
||
- `ui/frontend/src/lib/error/` central error surface with stable codes
|
||
and retry/escalation guidance; every server-side error mapped to a
|
||
translated, actionable message (en/ru).
|
||
- Consistent empty / loading / error states across views.
|
||
- Selected-planet visual on the map (ring/halo) off the `SelectionStore`
|
||
(deferred from Phase 35).
|
||
- Mobile bottom-sheet swipe-down + tap-outside dismissal (deferred from
|
||
Phase 13/35).
|
||
|
||
Acceptance: every server error → a translated actionable message;
|
||
consistent empty/loading/error states; the selected planet is visually
|
||
marked.
|
||
|
||
## F5 — PWA (was Phase 33)
|
||
|
||
Goal: the web build is installable and offline-tolerant. Depends on F6
|
||
(wasm in CI) so the service worker caches a freshly-built artefact.
|
||
|
||
- `ui/frontend/src/service-worker.ts` cache-first assets with
|
||
stale-invalidation on app update; `manifest.webmanifest`;
|
||
`ui/frontend/static/icons/` web icon set; `ui/docs/pwa-strategy.md`.
|
||
|
||
Acceptance: installs as a PWA on Chrome, Edge, and iOS Safari; the SW
|
||
survives an app update without serving stale code. Tests: Lighthouse PWA
|
||
≥ 90; Playwright install→offline→cached-login; version-bump invalidation.
|
||
|
||
## F6 — Build hygiene: build core.wasm in CI
|
||
|
||
(From the PLAN.md TODO; timely — the binary is currently committed and
|
||
must be rebuilt by hand on every Go-bridge change, which has already
|
||
bitten us.) Goal: stop shipping the binary in git.
|
||
|
||
- Install TinyGo on the gitea Actions runner (Linux tarball /
|
||
`curl … | tar -xz`, since `brew` is macOS-only); add `make -C ui wasm`
|
||
ahead of the Vitest step in `.gitea/workflows/ui-test.yaml`.
|
||
- Remove `ui/frontend/static/core.wasm` and `wasm_exec.js` from the repo
|
||
and re-tighten `ui/.gitignore`.
|
||
|
||
Acceptance: CI builds the wasm and Vitest/Playwright pass against the
|
||
freshly built artefact; the binaries are no longer tracked.
|
||
|
||
## F7 — Documentation finalization
|
||
|
||
Goal: living docs read as current state, not build archaeology.
|
||
|
||
- De-archaeologize the 20 `ui/docs/` topic docs: strip "Phase N adds…"
|
||
history, rewrite as present-tense descriptions of how things work.
|
||
- `ui/docs/README.md` index (added during this reorganization).
|
||
- Sync `ui/README.md`, `docs/ARCHITECTURE.md`, and `docs/FUNCTIONAL.md`
|
||
(+ `_ru` mirror) with the finalized UI.
|
||
|
||
Acceptance: no stray "Phase N" references in `ui/docs/`; the index links
|
||
every topic doc; READMEs/ARCHITECTURE describe current state.
|
||
|
||
## F8 — Owner manual-QA refinement loop
|
||
|
||
Open-ended, owner-driven. The owner exercises the whole UI by hand and
|
||
files small-nuance fixes; each is folded in as it surfaces. There is no
|
||
fixed acceptance gate here — finalization is "done" when the owner signs
|
||
off and the client moves on to the ROADMAP platform wrappers.
|