参考手册Workspace 包参考
theme 主题系统
多色彩方案主题管理，支持亮色/暗色模式和 6 种预设配色
本页是 01MVP 模板的 Workspace 包参考，适合在需要查看导出、源码入口和扩展点时使用。若你正在按功能启用或改造模板，先看 UI 与主题。
这是什么
@01mvp/theme 是主题色彩方案管理工具，一键切换整个网站的配色风格。基于 shadcn/ui 的 CSS 变量体系实现，兼容 next-themes。
能做什么
- 亮色 / 暗色模式切换
- 6 种预设配色方案（Default、Claude、Cosmic Night 等）
- 用户选择主题后自动保存到浏览器（localStorage）
- 防闪烁脚本（
getThemeScript），避免页面加载时闪一下默认主题
大概原理
主题系统通过 CSS 变量（如 --primary、--background）控制全局颜色。每种配色方案是一组 CSS 变量的不同取值。切换主题时，系统在 <html> 标签上添加/移除对应的 CSS 类名，浏览器自动重新计算所有使用这些变量的元素颜色。
核心类型
主题模式（ThemeMode）
"light" | "dark" -- 亮色或暗色模式。
配色方案（ColorScheme）
"default" | "claude" | "cosmic-night" | "modern-minimal" | "ocean-breeze" | "perplexity"
主题状态（ThemeState）
Prop
Type
配色方案配置（ColorSchemeConfig）
每种配色方案的元信息：
Prop
Type
可用配色方案
| 方案 | 主色调 | CSS 类名 |
|---|---|---|
| Default | #343434 (灰色) | 无 |
| Claude | #b45309 (暖橙) | theme-claude |
| Cosmic Night | #7c3aed (深紫) | theme-cosmic-night |
| Modern Minimal | #6366f1 (靛蓝) | theme-modern-minimal |
| Ocean Breeze | #10b981 (青绿) | theme-ocean-breeze |
| Perplexity | #0d9488 (青蓝) | theme-perplexity |
引入 CSS 主题文件
/* 在全局样式中按需引入需要的主题 */
@import "@01mvp/theme/themes/default.css";
@import "@01mvp/theme/themes/claude.css";
@import "@01mvp/theme/themes/perplexity.css";快速使用
import { initializeTheme, applyTheme, saveTheme } from "@01mvp/theme";
const state = initializeTheme("light", "default");
// 切换暗色模式
applyTheme("dark", state.colorScheme);
saveTheme({ mode: "dark", colorScheme: state.colorScheme });
// 切换配色方案
applyTheme("light", "claude");
saveTheme({ mode: "light", colorScheme: "claude" });防止主题闪烁（FOUC）
页面加载时，如果 JS 还没执行完就先显示了默认主题，然后才切换成用户保存的主题，就会出现"闪一下"的现象。用 getThemeScript() 生成一段内联脚本放在 <head> 里，可以在 JS 加载前就应用正确的主题。
// 在 layout.tsx 的 <head> 中使用
import { getThemeScript } from "@01mvp/theme";
<head>
<script dangerouslySetInnerHTML={{ __html: getThemeScript() }} />
</head>API 参考
initializeTheme(defaultMode?, defaultColorScheme?)-- 初始化主题，读取 localStorage 并应用applyTheme(mode, colorScheme)-- 在<html>上设置主题类名saveTheme(state)-- 保存主题到 localStoragegetStoredTheme()-- 读取已保存的主题
类型
type ThemeMode = "light" | "dark";
type ColorScheme = "default" | "claude" | "cosmic-night"
| "modern-minimal" | "ocean-breeze" | "perplexity";
interface ThemeState { mode: ThemeMode; colorScheme: ColorScheme; }