Theme Modes and Tokens
Configure light/dark/system mode, token variables, and theme switch behavior in the current MuseMVP implementation.
This guide focuses on the current theme implementation in MuseMVP: mode switching (light / dark / system) plus CSS token customization.
Capability Overview
| Capability | Current behavior |
|---|---|
| Theme modes | Controlled by config.ui.enabledThemes |
| Default mode | Controlled by config.ui.defaultTheme |
| Theme provider | @wrksz/themes/next, mounted in src/modules/html-document/Document.tsx |
| Token source | src/app/globals.css and src/app/styles/theme.css |
| UI switcher | ColorThemeSwitcherNoCustomTheme (@wrksz/themes/client) used in app layouts |
Scope
The current system is a stable "mode switch + token variables" setup. It does not include a built-in multi-brand preset library.
Quick Configuration
Set allowed modes
Update enabledThemes and defaultTheme in packages/config.
// packages/config
ui: {
enabledThemes: ["light", "dark", "system"],
defaultTheme: "dark",
}Update core tokens
Update shared and dark-mode tokens in src/app/globals.css.
/* src/app/globals.css */
:root {
--background: oklch(...);
--foreground: oklch(...);
--primary: oklch(...);
}
.dark {
--background: oklch(...);
--foreground: oklch(...);
--primary: oklch(...);
}Add product-specific tokens when needed
Place additional design tokens in src/app/styles/theme.css (for example --success, --highlight) and consume them in components.
Mode Option Reference
| Mode | Meaning |
|---|---|
light | Always uses light palette |
dark | Always uses dark palette |
system | Follows OS/browser color-scheme preference |
Common Pitfalls
Import order matters
src/app/main.css imports theme.css first and globals.css second.
If the same variable exists in both files, globals.css wins.
Default mode must be enabled
Keep defaultTheme included in enabledThemes.
Example: if defaultTheme is dark, enabledThemes should still include dark.
Landing visual tokens
Default landing look is warm terracotta primary on a warm gray canvas, not a hard-edged theme.
| Token | Default | Where |
|---|---|---|
--radius | 0.875rem | src/app/globals.css (:root and .dark). @theme inline keeps the +4px radius ladder. |
--primary | terracotta / clay orange (oklch(0.55 0.14 42) in light) | src/app/globals.css |
| Shadows | soft multi-layer, not blur: 3px hard edges | src/app/globals.css |
.landing-grid | faint 72px grid with a radial mask | src/app/main.css |
Style-only rounded-none on landing cards is gone. Signed-in settings headers and panels (SettingsShell, SettingsPanelItem) use rounded-xl to match the shell. Keep rounded-none on control seams such as data-table, calendar, input-group, and toggle-group.
Related Docs
- App Layout Customization - Customize dashboard/admin layout style
- Application Configuration - Full
packages/configoptions - Internationalization - Theme label i18n mapping