theming

# Theming ## Purpose Build themes that remain readable and coherent when switched. Dark mode is not an inversion; a palette that works on white will not work on black without being redesigned, and inverting it produces the vibrating, exhausting interfaces that dark mode is criticized for. ## When to Use - Adding dark mode to an interface. - Building a multi-theme or white-label system. - Generating a palette from a brand colour. - Fixing a theme where contrast breaks in one mode. ## Capabilities - Semantic token architecture that supports theme switching. - Dark-mode design (as opposed to inversion). - Palette generation with perceptually uniform colour spaces. - Contrast verification across every theme. - Respecting system preference and user override. ## Inputs - The base palette or the seed colour. - The themes required: light, dark, high-contrast, per-brand. - Accessibility requirements. ## Outputs - Semantic tokens that resolve differently per theme. - Every theme passing contrast requirements. - A switch that respects the system preference and remembers an override. ## Workflow 1. **Build on semantic tokens** — Components reference `--color-surface`, never `--grey-900`. Only the semantic layer changes between themes; components do not change at all. 2. **Design the dark theme, do not invert it** — Pure black is harsh and causes halation with white text. Use a very dark grey. Desaturate the accents: a colour that is vivid on white is glaring on dark. 3. **Pre...