主题模式与样式变量

配置 MuseMVP 当前主题体系中的 light/dark/system 模式、变量 token 与主题切换行为。

本文聚焦 MuseMVP 当前版本的主题实现：模式切换（light / dark / system）+ CSS 变量定制。

能力概览

能力	当前实现
可用主题模式	`config.ui.enabledThemes` 控制
默认主题模式	`config.ui.defaultTheme` 控制
全局主题 Provider	`next-themes`，挂载于 `src/modules/html-document/Document.tsx`
变量来源	`src/app/globals.css` 与 `src/app/styles/theme.css`
前端切换器	应用布局中使用 `ColorThemeSwitcherNoCustomTheme`

范围说明

当前体系是稳定的“模式切换 + 变量 token”方案，不内置多品牌预设主题库。

快速配置

设置可用模式

在 src/config/index.ts 中调整 enabledThemes 与 defaultTheme。

// src/config/index.ts
ui: {
  enabledThemes: ["light", "dark", "system"],
  defaultTheme: "dark",
}

修改核心变量

在 src/app/globals.css 中维护基础变量与暗色变量。

/* src/app/globals.css */
:root {
  --background: oklch(...);
  --foreground: oklch(...);
  --primary: oklch(...);
}

.dark {
  --background: oklch(...);
  --foreground: oklch(...);
  --primary: oklch(...);
}

按需扩展业务变量

在 src/app/styles/theme.css 增加扩展 token（如 --success、--highlight），并在组件中消费。

模式选项说明

模式值	含义
`light`	固定浅色主题
`dark`	固定深色主题
`system`	跟随系统/浏览器颜色偏好

常见误区

注意样式导入顺序

src/app/main.css 中先导入 theme.css，后导入 globals.css。
若两处定义同名变量，最终以 globals.css 为准。

默认模式必须在可用列表里

请保持 defaultTheme 一定包含在 enabledThemes 中。
例如 defaultTheme 为 dark 时，enabledThemes 里必须有 dark。

落地页视觉 token

默认落地页是暖陶土主色 + 暖灰底，不是硬直角风格。

Token	默认值	位置
`--radius`	`0.875rem`	`src/app/globals.css`（`:root` 与 `.dark`）。`@theme inline` 仍保持 `+4px` 圆角阶梯。
`--primary`	陶土 / 焕彩橙（亮色 `oklch(0.55 0.14 42)`）	`src/app/globals.css`
阴影	柔和多层阴影，不是 `blur: 3px` 硬阴影	`src/app/globals.css`
`.landing-grid`	淡 72px 网格 + 径向 mask	`src/app/main.css`

落地页卡片上的风格性 rounded-none 已去掉。登录后设置页页头和内容卡（SettingsShell、SettingsPanelItem）使用 rounded-xl，与壳层对齐。控件拼缝（data-table、calendar、input-group、toggle-group）仍可保留 rounded-none。