deepdrft/product-notes/theme-dark-mode-remediation.md

# Theme / Dark-Mode Remediation — DRY token pass

Status: proposed. Author: product-designer. Date: 2026-06-19. Implementer: TBD (separate delegation).

A design analysis of the DeepDrft theme system, focused on the dark theme, with a DRY
remediation plan that resolves a punch-list of six reported symptoms through **shared
theme tokens** rather than per-component patches. Daniel reported the symptoms; this note
maps the architecture, isolates the root causes, and sequences the fix.

Prior art this borrows from: `product-notes/track-card-theming.md` (landed 2026-06-05) —
the same class of problem (theme-aware recolor under `.deepdrft-theme-dark`, legible in
both palettes) solved once already with the same mechanism. This note generalizes that
fix from one component to the recurring pattern behind it.

---

## 1. How the theme system is wired today (the map)

There are **three** colour layers, and the bugs all live in how the third one bypasses the
first two.

### Layer A — MudBlazor palettes (C#)
`DeepDrftShared.Client/Common/DeepDrftPalettes.cs` defines `PaletteLight Light`,
`PaletteDark Dark` (+ `CmsLight`, `EmbedLight`, `EmbedDark`). `MainLayout.razor` mounts
`<MudThemeProvider Theme="DeepDrftPalettes.Default" IsDarkMode="_isDarkMode" />`. MudBlazor
injects these as `--mud-palette-*` CSS variables that **flip automatically** when
`IsDarkMode` toggles. This is the part that works: anything reading `--mud-palette-surface`,
`--mud-palette-background`, `--mud-palette-text-primary` inverts correctly for free.

### Layer B — DeepDrft design tokens (CSS)
`DeepDrftShared.Client/wwwroot/styles/deepdrft-tokens.css` defines two token families:

- **Source tokens** — raw brand colours, *constant across both themes*:
  `--deepdrft-navy (#112338)`, `--deepdrft-white (#FAFAF8)`, `--deepdrft-green-accent
  (#3D7A68)`, `--deepdrft-soft (#e3e7ec)`, etc. These never change between light and dark.
- **Theme-aware aliases** — `--theme-surface`, `--theme-surface-soft`, `--theme-primary…senary`,
  `--gradient-base/accent/warm/light`, `--deepdrft-surface`, `--deepdrft-background`. These
  **are** redefined inside the `.deepdrft-theme-dark` block (the wrapper class
  `MainLayout.ThemeWrapperClass` puts on the root div), so they flip.

The token file's own header comment establishes the intended discipline: source tokens are
"source of truth"; theme-aware aliases are what page CSS is *supposed* to consume so it
"resolve[s] coherently across themes."

### Layer C — component / page CSS
Scoped `*.razor.css` files and the global `DeepDrftPublic/wwwroot/styles/deepdrft-styles.css`.
**This is where the discipline breaks.** Page sections that should track the theme surface
instead reach straight past Layer B and bind to the *constant source tokens* of Layer A
(`--deepdrft-white`, `--deepdrft-navy`, `--deepdrft-soft`). A constant cannot invert — so
these surfaces stay light-on-navy-site no matter the mode.

---

## 2. Root causes (six symptoms → three causes)

The six reported symptoms collapse to **three** root causes. That collapse is the whole
point of doing this as one coherent pass rather than six patches.

### Cause 1 — "neutral surface" sections bind to constant source tokens, so they never invert
*(Symptoms: Home hero-left + footer (#3); About light sections (#4))*

These rules are the smoking gun (all bind a constant, not a theme alias):

- `Home.razor.css` — `.hero-left`, `.section`, `.section-divider`, `.section-body p`,
  `.medium-card`, `.split-right`, `.connect-*` → `background: var(--deepdrft-white)`,
  text `color: var(--deepdrft-navy)`.
- `About.razor.css` — `.hero-left`, `.hero-image-pane`, `.bio`/process gradients →
  `background: var(--deepdrft-white)`, text on `--deepdrft-navy`.
- `DeepDrftFooter.razor.css` — `.deepdrft-footer` → `background: var(--deepdrft-white)`,
  logo/links text on `--deepdrft-navy` / `--deepdrft-muted`.

`--deepdrft-white` is `#FAFAF8` in **both** `:root` and `.deepdrft-theme-dark` — it is a
brand constant, never re-aliased. So in dark mode these read as bright off-white panels with
dark text floating in a navy site. The fix is **not** to hardcode a dark colour; it is to
**bind these surfaces to a theme-aware alias** that already inverts.

**Critical nuance Daniel flagged:** the fix must be *neutral to the existing navy and green
accent sections.* The page already has sections that are **intentionally** navy/green in
both modes — `.section-dark` (navy), `.split-left` (green), `.cta-banner` (navy), the
`ReleaseHeroOverlay` (dark image). Those are decorative-by-design and must **not** be touched
by the inversion. Only the "default page surface" sections (the ones currently white-because-
light) should flip. This is a *classification* problem first, a recolor second: separate
"neutral surface" from "decorative accent" and only re-token the former.

### Cause 2 — the play-icon chip background binds `--deepdrft-soft` (constant light grey)
*(Symptoms: greyed-out play icon on release heroes / track lists (#5); too-bright player-bar play button (#6))*

`PlayStateIcon.razor.css` `.icon-container` hardcodes `background-color: var(--deepdrft-soft)`
(`#e3e7ec` — a light grey, constant across both themes). `PlayStateIcon` is the **single**
glyph component used by the release heroes, the Cut track rows, *and* the player bar. So one
constant drives all of these:

- Over a **dark hero image / navy track list** → the light-grey chip reads dull and
  "greyed-out" (#5). Daniel wants: **moss-green chip background, navy play glyph** in dark mode.
- On the **bright player-surface** → the same light-grey chip reads "very bright" against the
  navy dock (#6). Daniel wants: **same green, much less opaque** (a translucent green wash,
  not a solid bright fill).

Both are the same `--deepdrft-soft` constant failing to be theme-aware. One component, one
token — fix the token's dark-mode value and both surfaces resolve. Note the two contexts want
*different green treatments* (solid green chip on the hero; translucent green wash in the
player bar), so the chip background should be a **token the player-bar context can override**,
not a single flat value — see §3.

### Cause 3 — popover surface has no theme-aware token; light mode reads "too dark"
*(Symptom: light-theme popover background too dark, wants desaturated navy (#1))*

Two different popover families exist and they are styled inconsistently:

- **Bespoke panels** (visualizer controls, queue, privacy) deliberately use
  `--deepdrft-panel-ground` (`#1a1c22`, a dark charcoal) for their dark-glass chrome. These
  are *meant* to be dark in both modes — leave them.
- **MudBlazor default popovers** (selects, menus, tooltips, the share popover body) inherit
  `--mud-palette-surface`. In light mode `Surface = #FAFAF8`, but elevation-overlay tinting +
  the `--deepdrft-panel-ground` charcoal leaking through shared chrome is making them read
  darker/muddier than intended. Daniel's ask — "a more desaturated navy" — says the *target*
  isn't pure white; it's a **soft desaturated-navy surface**. There is no token for that today,
  so each popover improvises.

The fix is a **dedicated theme-aware popover-surface token** (`--deepdrft-popover-surface`)
with a desaturated-navy value in light mode and the existing panel-ground in dark mode, bound
once at the MudPopover surface so every default popover picks it up.

---

## 3. The DRY remediation — token structure

The unifying move: **page/component CSS must bind theme-aware aliases, and any surface that
must invert gets a named alias in `deepdrft-tokens.css` (defined twice — `:root` + `.deepdrft-theme-dark`).**
No surface colour is hardcoded at the component level. This is exactly the Layer-B discipline
the token file's header already declares; the work is making the consumers obey it.

### New / clarified tokens (in `deepdrft-tokens.css`)

| Token | Light (`:root`) | Dark (`.deepdrft-theme-dark`) | Replaces |
|---|---|---|---|
| `--deepdrft-page-surface` | `var(--deepdrft-white)` | `var(--deepdrft-navy)` (ground) or `--deepdrft-navy-mid` (elevated) | the literal `--deepdrft-white` on neutral page sections |
| `--deepdrft-page-text` | `var(--deepdrft-navy)` | `var(--deepdrft-white)` | the literal `--deepdrft-navy` text on neutral sections |
| `--deepdrft-page-text-muted` | `var(--deepdrft-muted)` | `color-mix(... lighter)` | muted body/eyebrow text that must stay legible on dark |
| `--deepdrft-play-chip` | `var(--deepdrft-soft)` | `var(--deepdrft-green-accent)` | `.icon-container` background |
| `--deepdrft-play-glyph` | (current) | `var(--deepdrft-navy)` | play glyph colour in dark |
| `--deepdrft-play-chip-soft` | derived | `color-mix(green-accent ~30%, transparent)` | player-bar translucent variant (#6) |
| `--deepdrft-popover-surface` | desaturated navy (e.g. `color-mix(navy 8%, white)`) | `var(--deepdrft-panel-ground)` | MudPopover default surface (#1) |

Values above are *direction, not final*. Per project memory (decorative-palette contrast
targets the actual WCAG threshold for the element type — large text 3:1, pushing toward
vibrancy), the implementer should tune the exact mixes on screen; the **structure** is the
deliverable here, the hex is theirs to land.

### Why tokens, not per-component fixes

- **One source of truth per concept.** "Neutral page surface," "play chip," "popover surface"
  each become *one* token. A future page that needs a neutral surface binds the token and
  inverts for free — no new dark-mode rule to remember (the backfill-cliff smell the
  *design-for-adaptability* memory warns against).
- **Neutrality to accents is structural, not vigilance-based.** Because only neutral-surface
  sections get re-tokened and the decorative navy/green sections keep their explicit brand
  colours, the inversion *cannot* accidentally flip a section that's meant to stay navy. The
  classification is encoded in *which token a section binds*, not in a reviewer noticing.
- **Player-bar vs. hero divergence is expressible.** Cause 2 needs the same green in two
  opacities. A `--deepdrft-play-chip` token + a `--deepdrft-play-chip-soft` override the
  player-bar context sets means one green, two contexts, zero duplication.

### What stays untouched (the neutrality guardrail)
`.section-dark`, `.split-left`, `.cta-banner` (Home + About), `ReleaseHeroOverlay` dark-image
chrome, and the bespoke `--deepdrft-panel-ground` panels (visualizer/queue/privacy) keep their
explicit brand colours. They are decorative-by-design and already correct in both modes. The
remediation must **not** route them through the new neutral-surface tokens.

---

## 4. Track / wave breakdown (for clean dispatch)

Sequenced so the token layer lands first and the component re-pointing fans out behind it.
Tracks T2–T4 are parallel once T1 is in.

### T1 — Token foundation *(cold-start prerequisite)*
Add the theme-aware tokens from §3 to `deepdrft-tokens.css` — each defined in **both** `:root`
and `.deepdrft-theme-dark`. No component consumes them yet; this is a pure additive token
slice. Tune the dark-mode values on screen. **Load-bearing for everything below.**
- Scope: `DeepDrftShared.Client/wwwroot/styles/deepdrft-tokens.css` only.
- Acceptance: tokens resolve to the right value in each mode (verify via devtools); no visual
  change yet (nothing binds them).

### T2 — Neutral-surface inversion *(Cause 1 → symptoms #3, #4)*
Re-point the neutral page-surface sections from constant source tokens to `--deepdrft-page-surface`
/ `--deepdrft-page-text` / `--deepdrft-page-text-muted`. **Classify first** — only the neutral
sections; leave `.section-dark` / `.split-left` / `.cta-banner` / hero-overlay alone.
- Scope: `Home.razor.css`, `About.razor.css`, `DeepDrftFooter.razor.css`.
- Acceptance: in dark mode the Home hero-left, the medium grid, the footer, and the About
  light sections render dark-surface/light-text; the navy and green accent sections are
  visually unchanged; light mode is pixel-identical to today.
- Risk: the appbar already has dark-mode handling (`deepdrft-styles.css §5`); confirm the
  footer/hero changes don't double-invert anything the appbar rules already cover.

### T3 — Play-chip theming *(Cause 2 → symptoms #5, #6)*
Re-point `.icon-container` background from `--deepdrft-soft` to `--deepdrft-play-chip`; set the
dark play glyph to `--deepdrft-play-glyph` (navy); in the **player-bar context only**, override
the chip to the translucent `--deepdrft-play-chip-soft`.
- Scope: `PlayStateIcon.razor.css` (+ a player-bar-scoped override, likely in
  `AudioPlayerBar.razor.css` or a context class on the bar's `.icon-container`).
- Acceptance (dark mode): release-hero + Cut-track-row play chips are **moss-green with a navy
  glyph**; the player-bar play button is the **same green but markedly less opaque**; light
  mode unchanged. Confirm hover states still read.
- Note: `PlayStateIcon` is shared — verify the chip change is acceptable on **every** mount
  (heroes, track rows, player bar) and that the player-bar override is the only context-specific
  divergence.

### T4 — Popover surface token *(Cause 3 → symptom #1)*
Introduce `--deepdrft-popover-surface` and bind MudBlazor's default popover surface to it so
light-mode popovers read as soft desaturated-navy rather than the current too-dark muddle.
**Do not** touch the bespoke `--deepdrft-panel-ground` panels.
- Scope: `deepdrft-styles.css` (a `.mud-popover` / popover-surface rule binding the new token);
  token already added in T1.
- Acceptance: light-mode default popovers (selects/menus/share body) render desaturated-navy;
  dark-mode popovers unchanged; the visualizer/queue/privacy panels are untouched.
- Open question (resolve during T4): confirm whether the "too dark" popover is a MudBlazor
  elevation-overlay artifact or panel-ground leakage — the fix differs slightly (override the
  overlay tint vs. set the surface). One devtools inspection settles it; flagged so the
  implementer checks rather than guesses.

### Dependency shape
`T1 → {T2, T3, T4}`. T1 is the only cold-start item. T2/T3/T4 are independent of each other
and can land in any order or in parallel once T1 is in. None of them touch source code, the
data layer, or the streaming seam — this is a pure CSS-token pass.

---

## 5. Open questions for Daniel

1. **Dark neutral-surface = ground or elevated?** Should the inverted Home/About/footer
   surfaces be the navy *ground* (`--deepdrft-navy`, matching the site background — sections
   dissolve into one continuous dark field) or *elevated* navy-mid (`--deepdrft-navy-mid` —
   sections read as distinct raised panels)? Recommend **ground** for the footer/hero (continuous
   field, less busy) and let the medium-cards stay as bordered panels on that ground. This is a
   taste call; flag for Daniel.
2. **Popover target colour (#1).** "Desaturated navy" — how far from white? Recommend a light
   wash (`color-mix(navy ~8%, white)`) so it stays clearly a light-mode surface, not a dark one.
   Confirm direction on screen.
3. Everything else (exact green opacity for the player-bar chip, exact muted-text mix) is a
   tune-on-screen detail, not a decision gate.

These are the only items that change the shape of the work; the rest is mechanical.