docs(spec): Sma Grodorna midsummer theme design
Full-takeover frog/maypole midsummer theme for the React frontend:
scoped [data-midsummer] CSS overlay, useMidsummer hook (localStorage,
default on), dancing maypole inside the map pan/zoom group, frog +
flower-crown dots, Glad midsommar banner + confetti, frog-hop easter egg
replacing the rickroll, play-once unmuted jingle. Manual 🐸 toggle.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Erik
parent
52bf9342df
commit
b3753d1ab0
1 changed files with 167 additions and 0 deletions
167
docs/superpowers/specs/2026-06-19-midsummer-theme-design.md
Normal file
167
docs/superpowers/specs/2026-06-19-midsummer-theme-design.md
Normal file
|
|
@ -0,0 +1,167 @@
|
||||||
|
# Midsummer theme — "Små grodorna" — design spec
|
||||||
|
|
||||||
|
Date: 2026-06-19
|
||||||
|
Repo: MosswartOverlord (React frontend in `frontend/`)
|
||||||
|
Status: approved design, ready for implementation plan
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
A "SUPER epic" Swedish-midsummer takeover of the Overlord dashboard, themed
|
||||||
|
around *Små grodorna* (the little frogs) — fitting because Asheron's Call
|
||||||
|
mosswarts are frog-men. Full visual takeover with a dancing maypole, frog +
|
||||||
|
flower-crown player markers, a "Glad midsommar!" banner, and a frog-hop
|
||||||
|
easter egg. Per-browser 🐸 toggle, **default ON**, with an unmuted jingle.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
In scope: the React frontend only (`frontend/`). The classic v1 frontend
|
||||||
|
(`static/classic/`) and legacy vanilla pages are dead and explicitly NOT
|
||||||
|
themed.
|
||||||
|
|
||||||
|
Out of scope: backend changes, DB, the plugin. No server-side flag — the
|
||||||
|
theme is a pure client concern toggled per browser.
|
||||||
|
|
||||||
|
## Approach: scoped overlay, not a rewrite
|
||||||
|
|
||||||
|
A single attribute `data-midsummer` on `<html>` (`document.documentElement`)
|
||||||
|
gates the entire theme. All midsummer styling lives in a NEW stylesheet
|
||||||
|
`frontend/src/styles/midsummer.css`, every rule scoped under
|
||||||
|
`:root[data-midsummer] …`, layered on top of the untouched base
|
||||||
|
`map-layout.css`. Removing the attribute fully reverts the UI — the base
|
||||||
|
theme remains the single source of truth.
|
||||||
|
|
||||||
|
Rejected alternative: swapping in a full second stylesheet (à la the old
|
||||||
|
`christmastheme/`). Too heavy and it drifts from the base theme on every
|
||||||
|
future change. The scoped overlay avoids duplication.
|
||||||
|
|
||||||
|
## State & toggle
|
||||||
|
|
||||||
|
- `frontend/src/hooks/useMidsummer.ts` — a hook backed by a tiny context so
|
||||||
|
every component reads one source of truth.
|
||||||
|
- Reads `localStorage["mo-midsummer"]`; **absent ⇒ enabled (default ON)**.
|
||||||
|
Only the literal string `"off"` disables it.
|
||||||
|
- On change, sets/removes `data-midsummer` on `document.documentElement`
|
||||||
|
and persists `"on"`/`"off"`.
|
||||||
|
- Exposes `{ enabled, toggle, soundOn, toggleSound }`.
|
||||||
|
- Provider mounted at the top of `App.tsx` so both the default app and the
|
||||||
|
`?view=dashboard` page inherit it.
|
||||||
|
- 🐸 toggle button added to the sidebar tool-links
|
||||||
|
(`components/sidebar/SidebarWindowButtons.tsx`), label reflects state.
|
||||||
|
|
||||||
|
## Components (all gated by `enabled`)
|
||||||
|
|
||||||
|
### 1. Maypole — `components/midsummer/Maypole.tsx`
|
||||||
|
- Rendered as a sibling of `PlayerDots` **inside `.ml-map-group`** in
|
||||||
|
`MapView.tsx` (so it pans/zooms with the world automatically), only when
|
||||||
|
`imgSize.w > 0 && enabled`.
|
||||||
|
- Positioned via `worldToPx(MAYPOLE_EW, MAYPOLE_NS, imgW, imgH)`.
|
||||||
|
**Default location: map center** (the midpoint of the Dereth image / a
|
||||||
|
central hub). Coordinate is a single named constant, trivial to move.
|
||||||
|
- Visual: a midsommarstång (pole + flowered cross-bar + ribbons) built in
|
||||||
|
CSS/SVG — no image asset — so it inherits theme colors and stays crisp at
|
||||||
|
any zoom.
|
||||||
|
- Carries its OWN ring of CSS-animated decorative frogs circling the pole
|
||||||
|
(keyframe rotation on a wrapper). The spectacle is independent of live
|
||||||
|
data, so it always looks alive even with nobody online. Real player dots
|
||||||
|
near the pole read as "joining the dance" by proximity.
|
||||||
|
- Pure CSS animation (transform-based) for 60fps; respects
|
||||||
|
`prefers-reduced-motion` (ring holds still).
|
||||||
|
|
||||||
|
### 2. Frog + flower-crown player dots
|
||||||
|
- No change to `PlayerDots.tsx` data flow. Under `[data-midsummer]`,
|
||||||
|
`midsummer.css` decorates `.ml-dot` with a wildflower-crown ring via a
|
||||||
|
`::before` pseudo-element, and turns the hovered/selected dot
|
||||||
|
(`.ml-dot-selected`) into a little frog (pseudo-element eyes + green body).
|
||||||
|
- Falls back gracefully: if a dot has an inline `backgroundColor`, the crown
|
||||||
|
sits on top; the frog variant overrides the fill only on select/hover.
|
||||||
|
|
||||||
|
### 3. Glad midsummer banner + confetti — `components/midsummer/MidsummerBanner.tsx`
|
||||||
|
- A festive top strip ("Glad midsommar! 🐸") rendered at the app shell level
|
||||||
|
(in `MapLayout.tsx`, and on the dashboard page) when `enabled`.
|
||||||
|
- One-shot snaps-glass / flower confetti burst on first load **per session**
|
||||||
|
(guarded by `sessionStorage`), a lightweight self-removing CSS-particle
|
||||||
|
effect (no library). Honors `prefers-reduced-motion` (skips the burst).
|
||||||
|
|
||||||
|
### 4. Frog-hop easter egg (replaces the rickroll)
|
||||||
|
- `Sidebar.tsx:62-80` currently appends a fullscreen `/rick.mp4` overlay +
|
||||||
|
shake on title click. Replace it with a *Små grodorna* hop: clicking the
|
||||||
|
title toggles a body class running a bounce/hop keyframe across the UI for
|
||||||
|
a few seconds, with frogs hopping across the screen. Self-cleans; clicking
|
||||||
|
again re-triggers without stacking. The `rick.mp4` reference is removed.
|
||||||
|
- This easter egg is active regardless of the theme toggle (it's a gag, not
|
||||||
|
a palette), but uses the same frog assets.
|
||||||
|
|
||||||
|
### 5. Jingle — `hooks/useMidsummerSound.ts`
|
||||||
|
- Plays a short *Små grodorna* clip **once** (not looping — a looping jingle
|
||||||
|
on a left-open dashboard is grating).
|
||||||
|
- Asset: `static/midsummer/sma-grodorna.mp3` (a short royalty-free / public
|
||||||
|
clip sourced during implementation; documented in the plan).
|
||||||
|
- Browser reality: unmuted audio cannot autoplay before a user gesture, so
|
||||||
|
the clip fires on the **first user interaction (any click) or the moment
|
||||||
|
the 🐸/🔊 control is used** — never silently on page-paint. A 🔇 control
|
||||||
|
stops/disables it; preference persisted (`soundOn`).
|
||||||
|
- Single module-level `Audio`/`AudioContext`, reused — no per-play leak (the
|
||||||
|
audit flagged per-notification `AudioContext` leaks elsewhere; don't repeat
|
||||||
|
that pattern).
|
||||||
|
|
||||||
|
## File plan
|
||||||
|
|
||||||
|
New:
|
||||||
|
- `frontend/src/hooks/useMidsummer.ts` (context + hook)
|
||||||
|
- `frontend/src/hooks/useMidsummerSound.ts`
|
||||||
|
- `frontend/src/styles/midsummer.css`
|
||||||
|
- `frontend/src/components/midsummer/Maypole.tsx`
|
||||||
|
- `frontend/src/components/midsummer/MidsummerBanner.tsx`
|
||||||
|
- `frontend/src/components/midsummer/FrogToggle.tsx`
|
||||||
|
- `frontend/src/components/midsummer/confetti.ts` (tiny helper)
|
||||||
|
- `static/midsummer/sma-grodorna.mp3` (audio asset)
|
||||||
|
|
||||||
|
Edited:
|
||||||
|
- `App.tsx` — wrap in `MidsummerProvider`; import `midsummer.css`.
|
||||||
|
- `components/map/MapView.tsx` — mount `<Maypole>` inside `.ml-map-group`.
|
||||||
|
- `components/map/MapLayout.tsx` — mount `<MidsummerBanner>`.
|
||||||
|
- `components/map/Sidebar.tsx` — replace rickroll block with frog-hop.
|
||||||
|
- `components/sidebar/SidebarWindowButtons.tsx` — add 🐸 toggle (+ 🔊).
|
||||||
|
- `components/PlayerDashboardFullPage.tsx` — render banner/toggle so the
|
||||||
|
new-tab dashboard matches.
|
||||||
|
|
||||||
|
## Decisions (locked)
|
||||||
|
|
||||||
|
- Maypole location: **map center** (named constant, easy to relocate).
|
||||||
|
- Jingle: **plays once**, unmuted, fires on first gesture.
|
||||||
|
- Toggle default: **ON**, per-browser via `localStorage`.
|
||||||
|
- Auto-date-gating: NOT implemented (user chose manual toggle). A future
|
||||||
|
enhancement could default the toggle from the date (~Jun 19–25).
|
||||||
|
|
||||||
|
## Deploy
|
||||||
|
|
||||||
|
`bash deploy-frontend.sh && git add static/ && git commit && git push`, then
|
||||||
|
`git pull` on the host (bind-mounted `static/`). No container restart. The
|
||||||
|
new audio file lives under `static/midsummer/` so it ships with the static
|
||||||
|
bundle; confirm the service worker (`sw.js`) either ignores it or caches it
|
||||||
|
intentionally.
|
||||||
|
|
||||||
|
## Testing / verification
|
||||||
|
|
||||||
|
- Toggle off ⇒ `data-midsummer` removed, UI identical to today (base theme
|
||||||
|
intact). Toggle on ⇒ full takeover. Preference survives reload.
|
||||||
|
- Maypole sits at map center and stays pinned to the world through
|
||||||
|
pan/zoom; frogs animate; `prefers-reduced-motion` stops motion.
|
||||||
|
- Player dots show crowns; hover/select shows frog.
|
||||||
|
- Banner shows once per session; confetti does not re-fire on every render.
|
||||||
|
- Easter egg hops and self-cleans; no `rick.mp4` request remains.
|
||||||
|
- Jingle plays once after first interaction; 🔇 stops it; no audio-context
|
||||||
|
leak across repeated toggles.
|
||||||
|
- `npm run build` succeeds; bundle includes the new chunk.
|
||||||
|
|
||||||
|
## Risks / caveats
|
||||||
|
|
||||||
|
- **Default-on + shared dashboard**: anyone opening it during the demo gets
|
||||||
|
the full theme. That's intended; the 🐸 toggle is one click to calm it.
|
||||||
|
- **Unmuted autoplay** is gesture-gated by browsers — communicated above;
|
||||||
|
not a bug.
|
||||||
|
- **Animation perf**: the map already re-renders on high-frequency
|
||||||
|
telemetry; keep all midsummer animation pure-CSS/transform and outside
|
||||||
|
React state so it doesn't add re-renders. Cap decorative frog count.
|
||||||
|
- **Asset licensing**: use a clearly royalty-free / public-domain audio clip
|
||||||
|
and note its source in the plan.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue