Axon 911 Frontend DocsAxon 911 Frontend Docs
Axon 911 Frontend Docs
    Loading navigation…
U
User
Switch to light mode
  1. Primitives
  3. Theme
  5. Usage

Theme

Usage

Overview
Set appearance with data-theme on the document element. createAppearancePreference writes light or dark there for AppearanceMode.Light, AppearanceMode.Dark, or AppearanceMode.System.
When to use
  • Application roots that should follow the person's light, dark, or system choice.
  • A preview surface that must render one appearance for a screenshot. Pass initial: AppearanceMode.Dark or AppearanceMode.Light.
When not to use
  • A portaled popup that should match a nested region. A theme region does not cross a portal. Set data-theme on the popup's own document or container.
  • Brand selection. Brand classes are not part of @prepared911/ui.
System setting
AppearanceMode.System follows prefers-color-scheme and keeps following it while the page is open. A system change animates like any other change. A change that does not alter the resolved appearance does not animate. Call dispose() when the owner of the preference goes away so the page stops listening to the system setting.
Reduced motion
createAppearancePreference animates through transitionAppearance. Nothing animates when the document has no startViewTransition, when prefers-reduced-motion: reduce matches, or when <html> has data-motion="reduced". The new appearance is still applied.
Content guidelines
User-facing theme labels (“Dark”, “Light”, “System”) use formatMessage.
Behavior and states
  • Prevent flash of incorrect theme on load via inline critical script, SSR hints, or cookie agreement—match app architecture.
  • Avoid mounting multiple competing providers in one tree unless testing isolation.
Best practices
  • Do nest only one provider per production tree unless a deliberate sandbox requires otherwise.
  • Do test high-contrast focus rings and charts in both themes.
  • Don’t toggle theme rapidly in response to noisy system events—debounce.
  • Don’t store secrets or PII in theme persistence mechanisms.
Accessibility
  • Ensure theme switches are keyboard operable and state is announced politely.
  • Verify color tokens still meet contrast requirements in both themes for text, icons, and charts.
Design system
@prepared911/ui does not ship ThemeProvider. The page appearance is data-theme on the document element, through createAppearancePreference. A subtree that must stay light or dark imports themeRegionProps and ThemeRegionAppearance from @prepared911/ui and spreads the result. That region does not cover a popup portaled to the document.
Related Components
  • Engineering docs on app bootstrap and Radix configuration.
  • Typography and Text for token-driven type ramps.
Previous
Text / Accessibility
Next
Theme / API and Development
On this page
Overview
When to use
When not to use
System setting
Reduced motion
Content guidelines
Behavior and states
Best practices
Accessibility
Design system
Related Components