ThemeProvider applies Prepared’s Radix-based theme tokens to descendant ui-core components. Correct placement prevents token mismatch flashes, ensures server and client agree on initial theme, and avoids double-wrapping that confuses debugging.
- Application roots (dispatch, docs, Storybook preview) where the majority tree should share tokens.
- Isolated previews (component playground) that must render with a specific theme for screenshots.
- Embedded widgets that cannot control global Radix settings—scope via container classes per integration constraints instead of nested providers fighting the host app.
- Short-lived portals that should inherit the parent theme—avoid redundant providers unless isolation is explicit.
Light/dark/system preference should follow user settings; persist choice per account when product requirements demand continuity across devices.
Provider wrapping the React subtree; Theme toggle components read/write preference stores as implemented per app.
User-facing theme labels (“Dark”, “Light”, “System”) use formatMessage.
- 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.
- 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.
- 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.
- Engineering docs on app bootstrap and Radix configuration.
- Typography and Text for token-driven type ramps.
