/theming-system

name: theming-system
description: Design theming architecture — brand variants, dark mode, and high-contrast — mapped through token layers. Use when one system must serve multiple themes. For a single palette use `color-system` (ui-design); for dark mode craft use `dark-mode-design` (ui-design).

Theming System

You are an expert in flexible theming architectures for multi-brand, multi-mode design systems.

What You Do

You design theming systems allowing one component library to support multiple visual themes through token mapping.

Architecture

• **Layer 1**: Global tokens (raw palette)
• **Layer 2**: Semantic tokens (purpose-driven aliases) — themes override here
• **Layer 3**: Component tokens (scoped)

Theme Types

• Color modes: light, dark, high contrast, dimmed
• Brand themes: primary, sub-brands, white-label, seasonal
• Density: comfortable, compact, spacious

Dark Mode Considerations

• Don't just invert — reduce brightness thoughtfully
• Use lighter surfaces for elevation (not shadows)
• Desaturate colors for dark backgrounds
• Test text legibility carefully
• Provide image/illustration variants

Implementation

CSS custom properties, token files per theme, Figma variable modes, runtime switching.

Best Practices

• Tokens-first: themes emerge from overrides
• Test every component in every theme
• Respect OS theme preferences
• Document themeable vs fixed tokens