system
400.wtf

400.wtf / system / docs · docs/ADR/0009-dark-only-visual-language.md

ADR-0009 — Dark-only visual language

Status: Superseded by ADR-0011 (civic redesign, 2026-10). Originally accepted 2026-07, Phase 0 items 0.1/0.2.

Context

The design is unambiguously dark: bg-black hardcoded in Layout.astro, white/thin typography, additive-blended particles that only read against black, and a void/ singularity brand. Yet the codebase carries a full light/dark apparatus: an inline theme script in BaseHead.astro toggling .dark from localStorage/system preference, @custom-variant dark in global.css, an unused ThemeToggler.vue, and a PrimeVue-era emerald palette in base.css with light and dark variable sets. None of it affects the rendered site.

Problem

Unused theme infrastructure costs comprehension (every reader must determine whether theming is load-bearing), invites half-broken contributions (a dark: utility that works only accidentally), and contradicts the brand. Keep, finish, or delete?

Decision

Commit to dark-only. The site renders one theme: the void. Delete the theme toggler, the inline theme script, the @custom-variant dark, the light-mode variable set, and the Prime palette (replaced by brand tokens — branding.md R1). Add <meta name="color-scheme" content="dark"> and color-scheme: dark on :root so browser UI (scrollbars, form controls, the config panel’s native <select>) matches.

Rationale: a light mode of a black-hole site is not a theme, it’s a different site. The accessibility interests normally served by theming are handled by dedicated means: prefers-reduced-motion (accessibility R2), zoom re-enabled (accessibility R1), and contrast maintained within the dark palette (thin-weight legibility is the watch item, not luminosity inversion).

Alternatives considered

  • Finish light mode: large design cost (the background cannot invert — additive particles need a dark ground), permanent 2× styling surface, off-brand result.
  • Keep the infra dormant “just in case”: the status quo; rejected — dead branches are where bugs breed (text-muted-color went unnoticed partly because the styling layer already contained inert code).
  • System-preference-only (no toggle, honor prefers-color-scheme): still requires designing a light world; same objection as finishing it.

Tradeoffs

  • (+) ~100 lines deleted; styling layer becomes fully truthful; brand and code agree.
  • (+) color-scheme: dark fixes native-control mismatches for free.
  • (−) Light-preferring visitors get a dark site (they also get that from every cinema).
  • (−) If a future surface genuinely needs light styling (print stylesheet for the zine, OG images on white feeds), it’s a one-off, not a theme system.

Consequences

  • Branding tokens (--color-void, --color-muted, accretion/cherenkov accents) become the single palette authority; artifacts inherit them.
  • The artifact checklist gains: “reads correctly against the void; no light-mode assumptions.”

Future evolution

Superseded only by a deliberate art-directed second theme (e.g., a “white hole” April Fools’ inversion — which would be an artifact, not a theme system).