gacha-event-tracker/docs/superpowers/specs/2026-10-16-ui-redesign-design.md

Event Clock redesign: Relaxed and Structured

Date: 2026-10-16. Status: approved requirements; both the initial implementation and the 2026-10-17 fidelity correction were rejected by the owner. Current continuation instructions: docs/handoffs/2026-10-17-redesign-second-rejection-handoff.md. Launch the current server, then ask the owner for the biggest differences before further UI changes.

Owner amendment, 2026-10-17: Structured is the default; preserve explicit saved Relaxed.

Intent and approval record

Make several games' events and routines easier to scan and act on, while retaining trustworthy deadlines and every existing reader choice. The owner approved the Round 7 visual direction, then explicitly chose two UIs, reversing the preceding single-UI decision. The second is Round 6 B, confirmed in conversation. Both have the same capabilities and data.

Visual references:

• Relaxed: Round 7
• Structured: Round 6 B
• Accumulated review decisions, Round 5, Round 6, Round 7

The prototypes are visual/interaction references, not production code. Sample codes, archive history, source failures and backups must never become real reader data.

Product choices

Settings → Appearance offers Interface: Relaxed / Structured, with preview thumbnails and short descriptions. Relaxed is the proposed default for new and upgraded installs; existing Dark/Light/System choices remain intact. Relaxed uses Round 7's separated panels, softer surfaces, Bricolage Grotesque/Figtree typography and generous gutters. Structured uses Round 6 B's ruled layout and Barlow typography. Both put the current-style game focus pills first in the left rail. Switch immediately, remember the choice, and preserve the current page, focus and progress.

Interface, Dark/Light/System, colour scheme and Standard/Compact event rows are independent preferences. Standard is the default row density. Content determines row height: missing descriptions reserve no blank line and receive no fabricated replacement text.

Use a shared component hierarchy with interface-specific tokens and narrowly scoped styles. Duplicating the app's React tree or maintaining two separate stores would double behavioural maintenance. A spacing-only switch would not reproduce the two approved visual directions.

Navigation, settings and updates

Main pages: Checklist, Timeline, Routines, Archive, Settings. Preserve the existing stored Checklist view id soon and Timeline id timeline. Visiting a utility page must not overwrite the preferred main view. Settings has its own navigation, beginning with General, and includes Your games, Appearance, Lists, Region & time, Data & sources, Backup, About and Changelog.

Keep game focus behaviour from GameFocus.tsx: All/game pills, outstanding counts, tap the selected game to return to All, Next through games and back to All. Hide the picker for one game. Focus never changes followed games. Game ordering remains the reader's order, otherwise A–Z.

Checklist and Timeline share a compact updates area. New code notices, events new since the reader's last visit, release news and source-age notices have distinct labels and state. Do not clear one by acknowledging another. Omit empty update kinds and the entire area when empty.

Replace Older schedules with Event data may be out of date. Supporting copy names the affected followed games: “For games you track: Genshin Impact, …”. Details & reasons opens Data & sources. Show this row only when freshness() reports an affected followed game; temporary focus does not narrow it. Do not add a large warning banner or repeat it on every row.

Reuse the real 48-hour freshness rule and oldest-source-per-game semantics. The footer always states feed age from source data, never generatedAt, with Check for new data. The button requests the published feed; it cannot force wiki scraping. Source details retain last successful data, last confirmed check, content-change time, source links and known reasons. A recent check with unchanged content is different from an overdue check. If no failure reason is recorded, say “The reason for the delay is unavailable”; do not infer blocking or network failure. Offline status is distinct from source age.

About retains the colophon, Lucas Winther attribution, contributor acknowledgements, all source communities and studios, reset-clock reference, disclaimer and project links. Credits are not filtered by followed games. Changelog is a Settings page, with no footer link or About button. Existing release notices link to that page.

Routines and game setup

Routines owns follow/unfollow, built-ins, Create your own routine, Make it mine, editing and independent Checklist/Timeline pins. A follow controls tracking; a pin controls placement. Stopping a routine preserves its history. Reader-authored games, events and task forms remain fully functional; prototype placeholders do not satisfy this requirement.

Routines → Checklist display controls Separate daily panel / Grouped with routines, also exposed in Appearance as the same preference. Separate is the proposed default. A daily tick appears in one place, is reachable with one action, and remains distinct per tracked server.

Routine group choices: Collapsed by default, Expanded by default, Always expanded. Default is Collapsed. A single-game focus expands its groups; returning to All restores the chosen policy. Always expanded removes collapse controls. Numeric inputs retain native steppers and step=1.

Game settings contains Setup, Codes and About. Setup offers Events / Dailies / Weeklies & monthlies / Cycles, plus individual routine choices. These types compose; events are visibility, not a routine. Save type intent separately from current follows. Unsupported or currently empty types remain selectable with an explanation. New built-ins matching saved intent are offered for review, never silently followed on an established install.

“Track another server” explains: “Play on more than one server? Add your other server to track both accounts separately.” It creates fresh choices with Events selected initially, and asks all tracking questions again. It copies no ticks, follows or pins. Changing an existing server is a different action and preserves that account's recorded history.

Game colour is shared across its servers, editable with picker/hex/preview/Reset to default. About lists every registered data source for that game with links and thanks to its editors, including event, banner and pass sources even when a source currently contributes no events.

Appearance and clocks

Slate, Warm, Plum and Custom schemes are available in each interface. Custom edits background, surface, text and interface accent separately for light and dark. Retain chosen base colours; derive readable rendered text, game hues and semantic colours against their actual surfaces. Keep game identity distinct from urgency. Small text must clear 4.5:1 in both modes and UIs. Fonts must have usable offline fallback; do not make rendering depend on Google Fonts loading.

Display timezone defaults to Automatic, resolved from the browser. Allow searchable named IANA zones and Revert to Automatic. Display timezone changes formatting, never server periods or stored day keys. Custom event entry states the timezone in which its date/time is interpreted.

Per tracked game/server, reset timing defaults to Automatic and permits a custom server-local hour/minute, with Revert to Automatic. Reuse real game/server offsets, regional hours and built-in clock overrides. Explicit timestamps, regionEnds and reader-entered instants remain authoritative; only reset-based/day-precision boundaries use the resolved reset clock. A routine with its own explicit clock keeps it. No change to the global games table is needed for reader overrides.

Reset changes are effective from their saved timestamp. Preserve a clock revision history per tracked account and attach the revision to new logs. Previously stored day/period labels are never re-keyed or silently interpreted under a different clock. Legacy logs belong to the initial automatic-clock revision. Historical summaries must retain access to all revisions; transition overlap is displayed as recorded history rather than merging or dropping ticks. Reverting to Automatic starts another revision and preserves earlier records. Test the boundary immediately before and after a change, including a change that moves the current game-day backward.

Onboarding

New-user setup starts with events only. Ask default game server, appearance and timezone, then games and What do you want to track?, then preferred Checklist/Timeline. Show events that haven't started belongs in the tracking step and begins off. Explain types inline, especially cycles: routines repeating on a game's cadence, such as every fourteen days. Explain “no active window” separately from “no supported built-in”. Initial setup may follow currently supported items deliberately selected by type; subsequent additions require review. Defer pin decisions until readers can see the views. Do not change old installs to the new-install defaults.

Returning readers receive a one-time release-specific welcome, available in either main view, with Take the quick tour / Keep browsing. The tour visits Routines, Checklist, Archive and Settings, with Back and Skip, then returns to the reader's preferred main view. Persist a marker separate from changelogSeen. Opening or skipping the tour changes no games, routines or progress.

Archive and statistics

On Done or Ignore, persist the outcome and event snapshot immediately. Show “Completed · Moved to Archive” or “Ignored · Moved to Archive” in the row for about 1.5 seconds, then fade/collapse. Keep Undo for about eight seconds. Reduced motion removes the fade, retaining the confirmation. Archive Restore is always available; restoring an ended event restores its recorded status, but does not pretend it is running again.

Retain event metadata, description, source, dates/precision, region-specific ends, account, progress and outcome timestamp. Unknown end dates remain null. Cache snapshots of seen events before feed replacement so expired unfinished events can be recorded when they leave the live feed. Missing from a feed is not proof of expiry: retain an outstanding snapshot until its known deadline passes; unknown-end events remain unresolved and must not become unfinished by guess. Only archive events for tracking periods the reader actually followed, not hidden catalogue games.

Default Archive body is per-game, with version groups only where the source states a version. History timeline is an optional alternate body. The story panel shows monthly and overall completion rate, current/best completion run, event check-ins, unfinished counts and per-game outcome bars. Rates use done / (done + ended unfinished), excluding ignored and unresolved. Use outcome time for done and resolved end time for unfinished when grouping by month. Completion runs order those eligible outcomes by that time; ignored entries neither extend nor break them. Event check-ins sum recorded distinct days per event/account, not unique calendar days of play. Near-miss detail reports an actually recorded goal shortfall, only where a known target exists; no invented threshold or estimated play progress. Label all statistics as recorded archive history.

Old marks whose events are no longer available remain preserved but cannot acquire fabricated titles, deadlines or descriptions. Explain that earlier history may be incomplete.

Persistent state, migration and backup

Keep existing event IDs, daily IDs, task IDs and day-key formats. Introduce stable tracked-account identities around game/server choices; do not turn a region change into a different event ID. Legacy progress, daily logs, ignores, task amounts and routine choices are associated once with each game's initial account at the reader's saved region. A migration marker records the mapping. Retain legacy key spaces and unknown/unreadable records; migration is idempotent and does not duplicate logs on reload. Additional accounts get independent state. Existing global preferences, game visibility/order, custom content and view survive. Migration must work for readers returning after months and for old exports, not only the current developer browser.

New state includes account configurations/logs, routine follows/pins and tracking intent, archive snapshots, reset revisions, appearance/timezone preferences, update-seen markers and code redemptions. Document concrete schemas and keys in DATA-MODEL with the storage implementation. Use a validated versioned full-state envelope for backup and restore; accept existing version-1 exports through a tested legacy reader. Preserve the existing distinction between progress import and Import all. A new export must carry all new reader-owned state. Do not recursively include backup history inside each backup.

Automatic backups run on app use and after settled data changes. Use a stable UTC calendar basis, independent of display timezone. Keep latest snapshot per UTC day for today and the six previous days; older snapshots fold into four consecutive seven-day windows; older snapshots then fold into six calendar-month buckets measured backward from the oldest weekly window. Buckets are disjoint; retain the newest snapshot in each and discard anything older. A partially covered calendar month at the weekly boundary retains only eligible older snapshots. Maximum seventeen retained snapshots, plus one pre-restore recovery copy. Never invent snapshots for unused days.

Backup rows say View backup. Preview shows date and contents; Restore this backup is the explicit action. Validate the entire payload before changing live state, save current data as a recovery copy, and support Undo last restore. Make multi-key restore recoverable using a prepared transaction envelope; startup must resolve an interrupted restore before normal store writes. Storage writes must report success/failure rather than relying on today's silently failing writeJson. If persistence/quota prevents a recovery copy or complete restore, leave current data intact and offer export. Failed backup retention writes must not delete the last good copy. Explain that browser-local backups disappear if browser storage is cleared; export is the copy outside this browser. No accounts or remote sync.

Codes and source boundaries

Codes belong in game settings and notify in-app in both main views. Discovery/newness is per game and independent from redemption per tracked account. Viewing a game's codes clears its new indicator, never redemption. Only declare a code new when present in a successfully read feed, not because its redemption checkbox is clear. Preserve first-observed metadata across builds.

The supplied Genshin Game8 codes URL is a source candidate, not a shipped feed. A deterministic codes source is a separate ingestion sub-project with its own source/robots review, fixture, parser/schema and refresh integration. It must follow existing scraping rules and publish only source-stated code/reward/expiry facts; unknown expiry stays unknown. The UI implementation includes a real empty/unavailable state and never ships sample codes as real. Integrating this source is required to finish the codes feature, but must not delay validating the shared UI shell.

Implementation boundaries and delivery order

Use production React components, pure state/selectors and existing Bun tooling. Extract page coordination from App and settings from Controls as needed for the actual new page boundaries; avoid unrelated refactors. No added runtime dependencies, accounts, push service, SQLite work, parser rewrites or prototype JavaScript transplanted into production.

Deliver in independently verifiable stages:

1. Shared shell, both interfaces, settings/navigation, typography and responsive layouts.
2. Validated state/envelope, account migration and reset revision machinery with recovery tests.
3. Routines, game setup, independent pins, direct dailies and clock-aware views.
4. Archive retention/outcomes/statistics and automatic backup/restore.
5. Onboarding, shared updates/source details, credits/Changelog, themes/timezone/custom colours.
6. Deterministic code ingestion and real code notices/redemption, then complete end-to-end review.

The detailed implementation plan must define file-level tasks and concrete storage schemas before stage 2. Each stage preserves a runnable app and documents what has actually landed. No staged delivery is a claim that the complete redesign is finished.

Verification and documentation

Test migrations from realistic legacy saves and exports, idempotence, independent account progress, reset changes/reverts at boundaries, null ends, vanished feed rows, archive denominator/ordering, backup folding across calendar boundaries, quota failures and interrupted restores. Test code newness independently from redemption and source-age scope independently from focus. Existing date/parser/ID tests must remain green. Tests create their own fixtures and never require public build output, repository docs or network.

Run typecheck and the full offline suite; build CSS/JS/static shell with production JSX settings. Check actual built app in Chrome on a new port for each rebuild at phone and desktop widths, both interfaces, both themes, Standard/Compact, keyboard/focus, reduced motion and 200% zoom. Exercise custom palette contrast on all used surfaces, no horizontal page overflow, one-action dailies, timeline reset adjacency, both onboarding paths, archive Undo/Restore and backup recovery. Verify offline reopening and the real update flow without losing progress.

Update PRD, DATA-MODEL, ARCHITECTURE, DESIGN, PRODUCT and affected AGENTS guidance with each implemented stage. Source integration also updates INGESTION/SOURCES. The shipped documents continue to describe shipped behaviour until that implementation exists. Add changelog/release notes under the repository's normal commit workflow when authorized; do not commit or push merely because this specification has been written.