docs(website): theming & nav phases 3-4 as built #105

wtclaude · 2026-08-08T00:18:18Z

wtclaude commented

2026-08-08 00:18:18 +00:00

What & why

Docs half of the phases 3–4 PR pair. Code: RunicGateway/website#122. Targets edge.

Mostly a record of where the build diverged from the design, and why.

`THEMING_AND_NAV.md`

§6.2 marked superseded. The preset values were built as specified, but they are not [data-theme] blocks in theme.css. A new "Phases 3–4 as landed" section explains the reason: SiteContext writes --accent as an inline style on <html>, which beats an attribute-selector block, so a preset's accent would have lost to BRAND_ACCENT_COLOR while getPublic().brand.accent — what the Android app themes itself from — reported the other value. Resolving server-side removes the conflict instead of sequencing around it.
§4.5's accentInt fix is struck through, because it was a no-op. getPublic() never exposed accentInt (a test asserts it stays undefined), the server-side one has no consumer, and Discord embeds are colored by a separate process reading env at boot. Replaced with what was actually done — the bot fetching the effective accent behind a cached getter.
Phase 9 re-scoped, from a live finding: applying Fantasy shows the §4.8 rgba() literals carry a hue, not just a light/dark assumption (.btn-ghost is rgba(11, 22, 48, 0.45), so portal quick-links read blue on a warm page). The dark presets need that promotion too, so the phase becomes "make the hue-carrying literals follow the palette, then Parchment".
The rest of the section records the full-15-token palettes, the served option catalog, the strict-on-write / forgiving-on-read asymmetry, the one added font (Georgia, so the serif role has a way back to today's default), the deferred theme flash, and the Phase 0 logger-factory bug fixed in passing.
A new row in §3's locked decisions for the delivery mechanism.

`BACKEND_DESIGN.md`

The new /settings/theme/options route in the §2 tree and the /settings route table, including why the catalog is served rather than duplicated client-side.
/public/settings now documents the optional theme block and says the brand fields are effective values (an admin theme beats BRAND_ACCENT_COLOR; an uploaded asset beats its BRAND_* path).
PUT /admin/settings documents theme_visual validation, and the settings-schema section gains a paragraph on server-side resolution and the two-path validation posture.
Route count 225 → 226.

`api-route-inventory.json`

Regenerated from server/routes.manifest.json — a clean 4-line diff this time, the mirror having been resynced in the phases 0–2 pair.

How it was tested

Docs only. The route inventory was regenerated from the manifest rather than hand-edited, and every claim about the code comes from the branch in website#122, where the server suite (732 pass), the client suite (75 pass), swagger/manifest regen and a live smoke against a real MariaDB are all green.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand
every change, and take responsibility for it. AI-authored commits are
marked with a Co-Authored-By / Assisted-By trailer.

License

I agree that my contribution is licensed under this project's license
(GNU GPL v3.0 or later), and I have the right to contribute it.

## What & why Docs half of the phases 3–4 PR pair. Code: RunicGateway/website#122. Targets **`edge`**. Mostly a record of where the build diverged from the design, and why. ### `THEMING_AND_NAV.md` - **§6.2 marked superseded.** The preset *values* were built as specified, but they are not `[data-theme]` blocks in `theme.css`. A new **"Phases 3–4 as landed"** section explains the reason: `SiteContext` writes `--accent` as an inline style on `<html>`, which beats an attribute-selector block, so a preset's accent would have lost to `BRAND_ACCENT_COLOR` while `getPublic().brand.accent` — what the Android app themes itself from — reported the other value. Resolving server-side removes the conflict instead of sequencing around it. - **§4.5's `accentInt` fix is struck through**, because it was a no-op. `getPublic()` never exposed `accentInt` (a test asserts it stays `undefined`), the server-side one has no consumer, and Discord embeds are colored by a *separate process* reading env at boot. Replaced with what was actually done — the bot fetching the effective accent behind a cached getter. - **Phase 9 re-scoped**, from a live finding: applying Fantasy shows the §4.8 `rgba()` literals carry a **hue**, not just a light/dark assumption (`.btn-ghost` is `rgba(11, 22, 48, 0.45)`, so portal quick-links read blue on a warm page). The dark presets need that promotion too, so the phase becomes "make the hue-carrying literals follow the palette, then Parchment". - The rest of the section records the full-15-token palettes, the served option catalog, the strict-on-write / forgiving-on-read asymmetry, the one added font (Georgia, so the serif role has a way back to today's default), the deferred theme flash, and the Phase 0 logger-factory bug fixed in passing. - A new row in §3's locked decisions for the delivery mechanism. ### `BACKEND_DESIGN.md` - The new **`/settings/theme/options`** route in the §2 tree and the `/settings` route table, including why the catalog is served rather than duplicated client-side. - **`/public/settings`** now documents the optional **`theme`** block and says the brand fields are **effective** values (an admin theme beats `BRAND_ACCENT_COLOR`; an uploaded asset beats its `BRAND_*` path). - `PUT /admin/settings` documents `theme_visual` validation, and the settings-schema section gains a paragraph on server-side resolution and the two-path validation posture. - Route count 225 → 226. ### `api-route-inventory.json` Regenerated from `server/routes.manifest.json` — a clean 4-line diff this time, the mirror having been resynced in the phases 0–2 pair. ## How it was tested Docs only. The route inventory was regenerated from the manifest rather than hand-edited, and every claim about the code comes from the branch in website#122, where the server suite (732 pass), the client suite (75 pass), swagger/manifest regen and a live smoke against a real MariaDB are all green. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` / `Assisted-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-08 00:18:19 +00:00

docs(website): theming phases 3-4 as built e669243aca

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>

wtclaude changed title from ~~docs(website): theming & nav phases 3-4 as built~~ to docs(website): theming & nav phases 3-4 as built

2026-08-08 00:18:28 +00:00

whitlocktech approved these changes 2026-08-08 00:21:36 +00:00

whitlocktech merged commit ce6f5b8788 into edge

2026-08-08 00:21:43 +00:00

whitlocktech deleted branch docs/theming-nav-phase-3-4

2026-08-08 00:21:44 +00:00

whitlocktech referenced this issue from a commit

2026-08-08 00:21:45 +00:00

Merge pull request 'docs(website): theming & nav phases 3-4 as built' (#105) from docs/theming-nav-phase-3-4 into edge

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#105