Theming exceptions
Diagrams are themed by the renderer's own config object and never read your CSS custom properties.
Ship a token → theme map. Two literal objects, light and dark, built from the semantic aliases, re-initialised and re-rendered when the theme flips. Resolve the tokens at flip time; the renderer will not do it for you.
Agent-authored HTML renders in its own document. Custom properties do not cross the boundary, and the content is untrusted, so it cannot be given the stylesheet.
Do not attempt to theme it. Theme the frame — border, radius, the warning strip above it — and let the content render as authored. A pane that stays light in dark mode is correct here; a half-restyled one is not.
Highlighters carry their own palettes, usually keyed to a theme name rather than to tokens.
Pin it. CodeBlock stays on warm ink in both themes by
design, so a single palette holds throughout and no flip is needed.
Dark mode is free only for surfaces we draw. Components that read semantic aliases —
--bg-surface, --text-primary, --state-* — flip with no
per-component work, which is exactly why the three exceptions above must be written down:
they are the surfaces a team will assume were handled, discover in the dark, and patch badly
under time pressure. Each one renders content the system did not author, through a pipeline
the system does not own.
The general test when adding any component: does anything here set a colour that CSS
custom properties cannot reach? A canvas, a chart library, an embedded document, an SVG
with baked fills, an image with a light background. If so, it belongs on this card.