docs(website): theming phases 3-4 as built
Records where the build diverged from the design and why. - The presets do not live in theme.css as [data-theme] blocks. Section 6.2 is marked superseded and a "Phases 3-4 as landed" section explains the inline --accent precedence problem that forced server-side resolution. - Section 4.5's accentInt fix is struck through: getPublic() never exposed accentInt, and Discord embeds are colored by a separate process reading env, so there was nothing per-request to recompute. Replaced with what was actually done -- the bot fetching the effective accent. - Phase 9 re-scoped. Applying Fantasy on a live instance showed the section 4.8 rgba literals carry a hue, not just a light/dark assumption, so the dark presets need that promotion too. - BACKEND_DESIGN.md: the new /settings/theme/options route, the `theme` block on /public/settings, effective values in the brand block, theme_visual validation on PUT /admin/settings, route count 225 -> 226. - api-route-inventory.json regenerated from the manifest. Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -50,6 +50,7 @@ Every new setting is an *override layer*, never a replacement:
|
||||
| # | Decision |
|
||||
|---|---|
|
||||
| Brand contract | **`getPublic().brand` returns effective values** (override → env). The Android app and Discord embeds track admin theming for free — see §4.5 |
|
||||
| Theme delivery | **The server resolves the whole effective token set** and the client writes it as CSS custom properties. No `[data-theme]` blocks — see §6.2 |
|
||||
| Structural tokens | **Radius + shadow depth only.** `spacingUnit` and `borderWeight` are **cut**, not deferred — see §4.6 |
|
||||
| Radius token values | **Seeded at today's real values** (four tokens, not three), so the promotion step is a true no-op — see §4.7 |
|
||||
| Presets in v1 | **Three dark presets** — Runic Gateway, Modern, Fantasy. Parchment (light) is Phase 9 — see §4.8 |
|
||||
@@ -156,8 +157,19 @@ The web client needs **no change** for this — its existing
|
||||
([`SiteContext.jsx:30-32`](../../website/client/src/contexts/SiteContext.jsx))
|
||||
simply receives a better value. Consequences to handle:
|
||||
|
||||
- `brand.accentInt` must be **recomputed from the effective accent** per request
|
||||
rather than read from the boot-time constant, or Discord embeds drift.
|
||||
- ~~`brand.accentInt` must be **recomputed from the effective accent** per
|
||||
request rather than read from the boot-time constant, or Discord embeds
|
||||
drift.~~ **Corrected in Phase 3 — this fix as written was a no-op.**
|
||||
`getPublic().brand` never exposes `accentInt` (`publicBrand.test.js` asserts
|
||||
it is `undefined`, deliberately: it is a Discord-only integer form), and the
|
||||
server-side `brand.accentInt` has no consumer at all. Discord embeds are
|
||||
colored by **`bot/src/brand.js`, in a separate process**, reading
|
||||
`BRAND_ACCENT_COLOR` from env at boot — so there was nothing per-request to
|
||||
recompute, and the drift the note describes was real but unfixable from the
|
||||
server. What Phase 3 actually did: the bot now fetches
|
||||
`GET /public/settings` → `brand.accent` (it already has a public-API client)
|
||||
behind a 10-minute cached getter, keeping env as the fallback. See
|
||||
"Phases 3–4 as landed" below.
|
||||
- `publicBrand.test.js` gains cases: no rows → env values unchanged (the existing
|
||||
assertions must still pass verbatim); `theme_visual` accent set → effective
|
||||
accent returned; `brand_assets.favicon` set → favicon overridden while `logo`
|
||||
@@ -362,10 +374,19 @@ null a field out to "clear" it** — remove it from the object.
|
||||
|
||||
### 6.2 Preset blocks
|
||||
|
||||
`:root` (no `data-theme` attribute set at all) stays the **Runic Gateway** default
|
||||
— today's actual values — so an instance with no `theme_visual` row renders
|
||||
exactly as it does now. `runic-gateway` is *also* declared as a named preset so
|
||||
that switching back to it after trying another is the same code path.
|
||||
> **Superseded in Phase 3.** The presets below are correct as *values* and were
|
||||
> built as specified, but they do **not** live in `theme.css` as `[data-theme]`
|
||||
> blocks. They live in `server/src/config/themePresets.js`, and the server
|
||||
> resolves the effective token set into `getPublic().theme` for the client to
|
||||
> write onto `<html>`. See "Phases 3–4 as landed" for why, and note two
|
||||
> corrections the build made to the palettes: each preset carries the **full**
|
||||
> color set (fifteen tokens, not the eight below), and `--shadow-card` is
|
||||
> themed alongside the radii.
|
||||
|
||||
`:root` stays the **Runic Gateway** default — today's actual values — so an
|
||||
instance with no `theme_visual` row renders exactly as it does now.
|
||||
`runic-gateway` is *also* declared as a named preset so that switching back to
|
||||
it after trying another is the same code path.
|
||||
|
||||
```css
|
||||
[data-theme="runic-gateway"] {
|
||||
@@ -514,13 +535,13 @@ today until the admin acts.
|
||||
| **0 — Settings-store groundwork** ✅ | `settingsDb.remove()`; `DELETE /admin/settings/:key` with key allowlist; `GET /settings/nav` (§4.2); `parseJsonSetting()` helper; register the five keys; three into `PUBLIC_KEYS`. Swagger + route-manifest regen |
|
||||
| **1 — `navOverrides.js` + tests** ✅ | The pure merge util, unit-tested in isolation. **The one piece with real correctness risk** |
|
||||
| **2 — Radius/shadow token groundwork** ✅ | Promote the literals in `theme.css` to the four tokens of §4.7, values unchanged. Verify zero visual diff before any admin UI exists |
|
||||
| **3 — Theme engine** | Three preset blocks, the combined Google Fonts link, `SiteContext` extension, and the effective-value resolution in `getPublic().brand` (§4.5) |
|
||||
| **4 — Admin theme UI** | `/admin/appearance` view + route in `App.jsx` + `NAV`/`TITLES` entries in `AdminLayout.jsx` |
|
||||
| **3 — Theme engine** ✅ | Three presets, the combined Google Fonts link, `SiteContext` extension, and the effective-value resolution in `getPublic().brand` (§4.5) |
|
||||
| **4 — Admin theme UI** ✅ | `/admin/appearance` view + route in `App.jsx` + `NAV`/`TITLES` entries in `AdminLayout.jsx` |
|
||||
| **5 — Brand assets** | Cached-shell rewrite in `app.js` (§4.3); upload endpoint on the existing multer config; `<img>` logo slot beside `MoonDot` in the three shells; `heroImage` chain extension |
|
||||
| **6 — Public nav wiring** | `SiteHeader.jsx` → `nav_public`. Lowest risk of the three: no roles, no groups |
|
||||
| **7 — Nav builder UI** | `NavEditor.jsx` with `@dnd-kit` (new dependency), **Public tab only** |
|
||||
| **8 — Admin + Player nav** | Wire the remaining two layouts, add the remaining two tabs, once the public pattern is validated in use |
|
||||
| **9 — Parchment (optional)** | Light-mode port per §4.8 — its own contrast pass across every component |
|
||||
| **9 — Palette-following literals + Parchment (optional)** | Promote the hue-carrying `rgba()` literals of §4.8 so they follow the palette (the **dark** presets need this too — see "Phases 3–4 as landed"), then the light-mode port with its own contrast pass across every component |
|
||||
|
||||
Phases 0–2 are one PR pair (website + docs), 3–4 a second, 5 a third, 6–8 a
|
||||
fourth. **All four PR pairs target `edge`, not `main`** — the feature reaches
|
||||
@@ -554,6 +575,97 @@ carries a half-wired theme engine.
|
||||
of the phase was a no-op; the only two `box-shadow` declarations in
|
||||
`theme.css` both already read `var(--shadow-card)`.
|
||||
|
||||
### Phases 3–4 as landed
|
||||
|
||||
Four things the design settled differently once it met the code.
|
||||
|
||||
**1. The server resolves the whole token set; there are no `[data-theme]`
|
||||
blocks.** §6.2 put the presets in `theme.css` and had the client set a
|
||||
`data-theme` attribute. That does not work as written: `SiteContext` writes
|
||||
`--accent` as an **inline style on `<html>`** (`SiteContext.jsx:31`), and an
|
||||
inline property beats any attribute-selector block. An admin who picked Fantasy
|
||||
without also setting a custom accent would have had Fantasy's `#c9973f` painted
|
||||
over by `brand.accent` from env — and §4.5's whole point is that
|
||||
`getPublic().brand.accent` is what the phone app themes itself from, so the two
|
||||
surfaces would have disagreed about the accent while both being "right".
|
||||
|
||||
The fix removes the conflict rather than sequencing around it. Presets live in
|
||||
`server/src/config/themePresets.js`; `server/src/utils/themeResolve.js` layers
|
||||
`:root` ← preset ← custom **per field** into a token map; `getPublic()` returns
|
||||
it as `theme`; `client/src/lib/themeVars.js` writes it onto `<html>`. One
|
||||
authority for the merge, `brand.accent` is by construction the accent the site
|
||||
actually paints, and `theme.css`'s `:root` is untouched — an instance with no
|
||||
row gets no `theme` block, the client writes nothing, and the page renders
|
||||
byte-for-byte as today.
|
||||
|
||||
The client half's real logic is *removal*: inline properties are not cleared by
|
||||
writing a smaller object over them, so `applyThemeTokens` tracks what it set
|
||||
last time and `removeProperty`s whatever the new payload no longer mentions.
|
||||
Without that, "Reset to defaults" would look broken until a reload.
|
||||
|
||||
**2. Presets carry the full fifteen-token palette, and theme `--shadow-card`.**
|
||||
§6.2's blocks set eight colors. Applied literally, Fantasy's warm brown page
|
||||
would have kept `--line: #2a3544` and `--blue: #13243c` — dark blue-grey borders
|
||||
and a blue-grey active nav row — because those tokens are not in the list.
|
||||
Every preset now sets `--panel-flat`, `--line`, `--line-soft`, `--head`,
|
||||
`--muted`, `--dim` and `--blue` as well. The admin *form* still exposes only
|
||||
§6.1's eight; the rest are supporting shades a preset gets right coherently but
|
||||
that are not worth hand-picking. `--mode-live` / `--mode-maint` stay fixed
|
||||
across every preset (green means live) and `--panel-grad` stays derived, both
|
||||
locked by tests.
|
||||
|
||||
**3. The option catalog is served, not duplicated.**
|
||||
`GET /api/v1/settings/theme/options` returns the presets (with their full token
|
||||
maps, so a control can show what an unset field currently resolves to), the font
|
||||
shortlist, the shadow depths, and the editable field names paired with the CSS
|
||||
variable each drives. Duplicating those lists in client code would mean the form
|
||||
could offer a font the server rejects, which surfaces as a save 400ing for no
|
||||
visible reason. A test asserts every offered option validates.
|
||||
|
||||
Validation is deliberately asymmetric: **strict on write** (`PUT
|
||||
/admin/settings` 400s and names the offending field) and **forgiving on read**
|
||||
(a bad field is dropped, its neighbours keep applying). Strict-on-write gives
|
||||
feedback; forgiving-on-read means a row hand-edited in the DB degrades to the
|
||||
shipped default instead of rendering a broken site.
|
||||
|
||||
One addition to §5.1's twelve font options: **Georgia in the serif list.** The
|
||||
shortlist gave the sans role a "today's default" option (Arial, byte-identical
|
||||
to `--sans`) but left serif with no way back to `Georgia, "Times New Roman",
|
||||
serif` short of resetting the whole theme. It pulls in no web family, so §5.2's
|
||||
combined URL is unchanged.
|
||||
|
||||
**4. The Discord bot fetches the accent; §4.5's `accentInt` note was a no-op.**
|
||||
See the correction in §4.5. `bot/src/brand.js` now reads
|
||||
`GET /public/settings` → `brand.accent` through the public-API client it already
|
||||
had, behind getters with a 10-minute TTL — so `brand.accentInt` stays a plain
|
||||
property read at every existing call site, an embed never awaits a network call,
|
||||
and any failure (site down, maintenance, malformed body) keeps the last known
|
||||
good value with `BRAND_ACCENT_COLOR` as the floor.
|
||||
|
||||
**Found while smoke-testing: §4.8's rgba literals are not only a light-mode
|
||||
problem.** The 28 dark-assuming `rgba()` literals were scoped to Phase 9 on the
|
||||
reasoning that they break a *light* preset. Applying **Fantasy** on a live
|
||||
instance shows they also carry a **hue**: `.btn-ghost`'s
|
||||
`background: rgba(11, 22, 48, 0.45)` (essentially `--blue` at 45%) leaves the
|
||||
portal's quick-link buttons reading blue on a warm brown page, and the hero
|
||||
overlay stack in `heroLayout.js` is `rgba(11,15,20,…)` regardless of preset.
|
||||
Nothing is broken or unreadable — it is a visible seam, not a bug — but Phase 9
|
||||
should be re-scoped from "light-mode port" to "make the hue-carrying literals
|
||||
follow the palette", which the dark presets need too. Not fixed here: it is the
|
||||
23-declaration-style promotion Phase 2 was, and folding it into the phase that
|
||||
introduced the presets would have hidden it inside an unrelated diff.
|
||||
|
||||
**Still open, by decision:** the theme arrives with the `/public/settings` fetch,
|
||||
so a themed instance paints the shipped palette for one frame before repainting.
|
||||
Phase 5 has to rewrite `renderIndexHtml` into a cached, invalidated shell anyway
|
||||
(§4.3) — injecting a `<style>` block with the effective tokens there removes the
|
||||
flash for free, so it is deferred rather than solved twice.
|
||||
|
||||
**Also fixed in passing:** `settings/nav.controller.js` imported the logger
|
||||
*factory* rather than calling it, so `log.error` was `undefined` and a DB fault
|
||||
would have thrown a `TypeError` inside the catch — no response sent, request
|
||||
left hanging — instead of returning a 500. Introduced in Phase 0.
|
||||
|
||||
### 8.1 Admin builder UI notes
|
||||
|
||||
- Tabbed control for the three navs; drag-and-drop reorderable list.
|
||||
|
||||
Reference in New Issue
Block a user