Symptom
@dashforge/tw-theme exposes a setMode() function as the only working way to sync theme mode with the internal store. Writing document.documentElement.dataset.dashTwTheme = 'dark' from outside the provider is silently ignored — the attribute is present in the DOM but the Valtio store + downstream components stay out of sync.
Nothing warns the consumer, and setMode() is not exposed as a hook or provider prop — it must be imported directly from @dashforge/tw-theme.
Why this is bad
- Undiscoverable: writing
data-*-theme is the intuitive escape hatch (Radix, Ariakit, MUI-CSS, Panda all use variants of this) — consumers reach for it first
- Silent failure: no warning, no error; the attribute value looks correct in devtools but components don't react
- Blueprint spent hours diagnosing why the theme toggle button wasn't affecting
<Card> background before finding setMode() in the store code
Discovered while
Refactoring the Blueprint Builder V2 theme wire-up. Filed in Blueprint's dogfood report as G-23 (severity: medium — undiscoverable API).
Workaround applied in Blueprint
Switched from dataset.dashTwTheme = … to import { setMode } from '@dashforge/tw-theme' + setMode(theme).
Acceptance (pick one or both)
Related
Symptom
@dashforge/tw-themeexposes asetMode()function as the only working way to sync theme mode with the internal store. Writingdocument.documentElement.dataset.dashTwTheme = 'dark'from outside the provider is silently ignored — the attribute is present in the DOM but the Valtio store + downstream components stay out of sync.Nothing warns the consumer, and
setMode()is not exposed as a hook or provider prop — it must be imported directly from@dashforge/tw-theme.Why this is bad
data-*-themeis the intuitive escape hatch (Radix, Ariakit, MUI-CSS, Panda all use variants of this) — consumers reach for it first<Card>background before findingsetMode()in the store codeDiscovered while
Refactoring the Blueprint Builder V2 theme wire-up. Filed in Blueprint's dogfood report as G-23 (severity: medium — undiscoverable API).
Workaround applied in Blueprint
Switched from
dataset.dashTwTheme = …toimport { setMode } from '@dashforge/tw-theme'+setMode(theme).Acceptance (pick one or both)
data-dash-tw-theme(MutationObserver on<html>) andconsole.warnin dev mode:"data-dash-tw-theme was written outside DashforgeTailwindProvider — use setMode() from @dashforge/tw-theme or the provider's mode prop instead."modeandonModeChangeas a controlled interface on<DashforgeTailwindProvider>so consumers can drive it via React state instead of an imperative helperdashforge-docs-labdocuments the theme-sync contract explicitly (Theming → Runtime mode switching)Related