docs(panel): document the theme system and preferences

upsetbit · claude · upsetbit · commit 35cbf4fdb1d9 · 2026-06-14T14:19:41.000-03:00
Update screens.md (theme picker, /settings/theme), components.md (token
coverage, --on-accent, agent hues on light backgrounds), and
architecture/panel.md (PreferencesService, server-rendered data-theme).

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/architecture/panel.md b/docs/architecture/panel.md
@@ -277,9 +277,16 @@ POST forms (`/logout`, `/cli/authorize/approve`, and device actions).
 ## Talking to the server
 
 `internal/panel/rpc/client.go` builds Connect clients for
-`SessionsService`, `DevicesService`, `AuthService`, `AnalyticsService`.
-Each call sends `Authorization: Admin <PROSA_ADMIN_TOKEN>` so the server
-treats the panel as the owner.
+`SessionsService`, `DevicesService`, `AuthService`, `AnalyticsService`,
+`PreferencesService`. Each call sends `Authorization: Admin
+<PROSA_ADMIN_TOKEN>` so the server treats the panel as the owner.
+
+`PreferencesService` stores panel UI preferences (currently the chosen
+theme) in the `panel_preferences` Postgres table, keyed by owner email.
+The panel resolves the owner's theme on every full-page render — cached
+in-process, invalidated on write — and stamps it onto `<html data-theme>`
+server-side, so the first paint is correct with no flash. The Settings
+picker POSTs to `/settings/theme`, which calls `PreferencesService.Set`.
 
 The `/events` route is a proxy: the panel opens an SSE stream to the
 server's `/sse/events` and re-emits the bytes to the browser. This
diff --git a/docs/panel/components.md b/docs/panel/components.md
@@ -11,7 +11,7 @@ see [screens.md](screens.md). For visual direction see the
 CSS vars defined in `internal/panel/templates/assets/css/tokens.css`. All
 other layers reference these vars — never a literal value.
 
-### Dark palette
+### Default palette — Colorblind (Okabe–Ito)
 
 ```
 --bg               #0f1117
@@ -20,10 +20,11 @@ other layers reference these vars — never a literal value.
 --text-1           #e8eaf0
 --text-2           #aab0bf
 --text-3           #6b7186
---accent           #6b7afc
---accent-soft      #6b7afc33
---ok               #4ade80
---danger           #f04a5c
+--accent           #56b4e9
+--accent-soft      #56b4e933
+--ok               #1fb894
+--danger           #ef6c1a
+--warn             #e69f00
 --divider          #232733
 --chart-grid       #20242f
 ```
@@ -32,9 +33,23 @@ other layers reference these vars — never a literal value.
 it sits quieter than `--divider`, which separates surfaces (light value:
 `#e7ebf1`).
 
-Light mode: `tokens.css` re-defines every palette var under
-`[data-theme="light"]`, and under `[data-theme="system"]` when the OS
-reports `prefers-color-scheme: light`.
+Themes: the colorblind (Okabe–Ito) palette above lives in `:root` as the
+default. Each alternate overrides the color tokens under its own
+`[data-theme="<id>"]` block — `light`, `nord`, `solarized-dark`,
+`solarized-light`, `dracula`, `gruvbox`, `high-contrast` — and `system`
+follows the OS via `prefers-color-scheme`. The panel stamps the owner's
+saved `data-theme` on `<html>` server-side; `charts-init.js` recolors
+charts on the flip.
+
+Every color the panel paints is a token, so no theme leaves anything
+unthemed: surfaces, text, `--accent` plus `--on-accent` (the text/icon
+color that rides on the accent — dark on a light accent, light on a dark
+one), status (`--ok`/`--danger`/`--warn`), `--divider`, the `--chart-*`
+palette, and the `--agent-*` identity hues. Agent hues keep their
+identity across themes; on light backgrounds (`light`, `solarized-light`,
+`system` under OS-light) they darken for contrast. The only literals left
+in CSS are drop shadows and the modal scrim — neutral black on purpose,
+correct against any palette.
 
 ### Typography
 
diff --git a/docs/panel/screens.md b/docs/panel/screens.md
@@ -561,24 +561,39 @@ Devices
 
 ## Settings `/settings`
 
-Single-card surface for the logged-in owner. Spartan by design.
+Two cards for the logged-in owner: identity and appearance.
 
 ```
 Settings
 
   +---------------------------------------------------+
-  |  Signed in as                                     |
+  |  Logged in as                                     |
   |  hi@caian.org                                     |
-  |                                                   |
-  |  [ logout ]                                       |
+  |  [ log out ]                                      |
+  +---------------------------------------------------+
+  +---------------------------------------------------+
+  |  Appearance                                       |
+  |  (o) Colorblind   ( ) Light       ( ) Nord        |
+  |  ( ) Solar. Dark  ( ) Solar. Light( ) Dracula     |
+  |  ( ) Gruvbox      ( ) High Contr. ( ) System      |
   +---------------------------------------------------+
 ```
 
-- One card, no tabs, no preferences sub-pages.
 - Email comes from the session cookie (`p.cookie.FromRequest(r)`).
 - Logout button posts to `/logout` (same as the topbar form).
-- No SSE, no Alpine, no charts. If a future setting earns its place,
-  it joins this card.
+- The theme picker is a swatch grid of nine options: the colorblind
+  (Okabe–Ito) default, seven alternates (`light`, `nord`,
+  `solarized-dark`, `solarized-light`, `dracula`, `gruvbox`,
+  `high-contrast`), and `system`. Picking one sets `data-theme` on
+  `<html>` immediately — recoloring chrome and charts — and POSTs to
+  `/settings/theme`.
+- `/settings/theme` persists the choice server-side via
+  `PreferencesService.Set`, keyed by owner email. The panel renders
+  `data-theme` from the stored value on first paint, so the theme
+  follows the owner across browsers with no flash.
+- The catalog is `panel.Themes`: the picker renders from it and the
+  handler validates the submitted value against it, so the two never
+  drift.
 
 ---
 
