Theming

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 :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

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.