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 :root or [data-theme] — components consume var(--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-dark instead 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.