MuseMVP

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	`next-themes`, mounted in `src/modules/html-document/Document.tsx`
Token source	`src/app/globals.css` and `src/app/styles/theme.css`
UI switcher	`ColorThemeSwitcherNoCustomTheme` 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 src/config/index.ts.

// src/config/index.ts
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.

App Layout Customization - Customize dashboard/admin layout style
Application Configuration - Full src/config/index.ts options
Internationalization - Theme label i18n mapping

Theme Modes and Tokens