Theming
Last updated:
Theming systems support visual variation consistently — themes should remain maintainable and accessible.
01 — Purpose
Consistent visual variation
Theming systems support visual variation consistently — themes should remain maintainable and accessible.
Light mode, dark mode, brand variants, and high-contrast themes should share one token system — not parallel hardcoded palettes that drift apart and fail contrast checks.
This site themes via semantic colour tokens in the LSCSS theme layer — see design tokens.
02 — Principles
Themes should extend systems cleanly
Token-driven systems, accessible contrast, semantic colour naming.
- token-driven systems — swap values, not component rules, per theme
- accessible contrast — test both light and dark; see colour and contrast systems
- semantic colour naming —
--color-text, not--gray-700
03 — Practice
Good theming architecture
One component stylesheet; theme layer overrides tokens.
- use CSS custom properties on
:rootor[data-theme]— components consumevar(--color-surface) - respect
prefers-color-scheme— system preference as default or option - keep theme logic in the theme layer — see cascade layers
- test focus rings and states in every theme — not only default background
- document how to add a theme — which tokens must be defined
Use the active colour scheme
light-dark() chooses a value from the element's activecolor-scheme. It does not create a theme toggle or save a preference. Set color-scheme deliberately and keep theme values in semantic tokens, including a usable fallback.
Support checked 4 October 2026: image values inlight-dark(), including gradients and image URLs, became Baseline Newly available with Safari 27. They can express decorative light and dark backgrounds without duplicating component rules. See the September platform update and the light-dark() reference. Check support for image values separately from colour values and test text and focus contrast against each background.
04 — Avoid
Theme anti-patterns
Duplicated theme logic and inaccessible dark modes ship constantly.
- duplicated theme logic — separate component CSS per theme
- inaccessible dark themes — grey-on-grey text, invisible borders
- hardcoded colour values in components — bypassing tokens
- theme toggles without persistence or system preference respect
- presentation tokens —
--hero-pink-darkinstead of semantic roles
05 — Close
Theme at the token layer
If a colour appears in a component file, question whether it belongs in tokens.
Add a new theme by defining token overrides — not by forking components. Audit contrast and focus for every semantic pair.
See design tokens, motion standards for themed duration tokens, and CSS standard.