Skip to content

theme-system.md

Latest commit

 

History

History
82 lines (66 loc) · 3.99 KB

theme-system.md

File metadata and controls

82 lines (66 loc) · 3.99 KB

Theme Family System / 主题家族系统

概述

两层主题系统：mode（light/dark/system，由 next-themes 管理）+ theme family（色板，由自定义 context + CSS 变量管理）。

架构

themes/*.json           → 定义色板（OKLCH）、代码主题映射
src/lib/theme/loader.ts → 服务端读取 + 校验 JSON，按 order 排序
src/lib/theme/render-css.ts → 生成 html[data-theme-family="x"] 规则
src/app/layout.tsx      → <head> 注入反闪烁脚本 + <style> 块
src/lib/theme/context.ts + ThemeFamilyProvider → 客户端状态 + localStorage

CSS 特异性：html[data-theme-family] (0,1,0) > :root (0,0,1)；html.dark[data-theme-family] (0,2,0) > .dark (0,1,0)。globals.css 中的 :root / .dark 块作为兜底。

主题 JSON Schema

{
  "id": "night-owl",          // 唯一 ID，对应 data-theme-family 值
  "label": "Night Owl",       // 显示名
  "order": 7,                 // 排序权重
  "description": "...",       // 可选短描述
  "codeTheme": {              // Prism / HLJS 代码高亮
    "light": "coy",           // 键名对应 code-themes.ts 中的 PRISM_THEME_MAP / HLJS_THEME_MAP
    "dark": "nightOwl"
  },
  "shikiTheme": {             // Shiki 代码高亮（ai-elements）
    "light": "night-owl-light",  // 值为 Shiki BundledTheme 名
    "dark": "night-owl"
  },
  "light": { /* 31 个 ThemeColors 键，oklch 值 */ },
  "dark":  { /* 同上 */ }
}

代码高亮三条渲染链

消费组件 高亮器 解析函数
ChatCodeBlock (CodeBlock.tsx) Prism resolvePrismStyle()
DocPreview / FilePreview HLJS resolveHljsStyle()
AI Elements CodeBlock (code-block.tsx) Shiki resolveShikiThemes()
Settings Preview (AppearanceSection.tsx) Shiki codeToHtml()

三条链路都通过 useThemeFamily() 取得当前 family，再查找对应的 codeTheme / shikiTheme 映射。

当前主题清单（12 个）

ID Order Light Code Dark Code Shiki Light Shiki Dark
default 0 oneLight oneDark github-light github-dark
github 1 ghcolors vscDarkPlus github-light-default github-dark-default
rose-pine 2 duotoneLight duotoneSea rose-pine-dawn rose-pine
tokyo-night 3 materialLight materialOceanic github-light tokyo-night
everforest 4 gruvboxLight duotoneForest everforest-light everforest-dark
nord 5 coldarkCold nord github-light nord
kanagawa 6 vs duotoneEarth kanagawa-lotus kanagawa-wave
night-owl 7 coy nightOwl night-owl-light night-owl
poimandres 8 coldarkCold coldarkDark min-light poimandres
vesper 9 gruvboxLight twilight min-light vesper
horizon 10 duotoneLight materialDark github-light horizon
synthwave84 11 prism synthwave84 min-light synthwave-84

新增主题

  1. 在 themes/ 目录创建 JSON 文件，遵循上述 schema
  2. 填写所有 31 个 ThemeColors 键（light + dark），值用 OKLCH
  3. codeTheme 键名必须在 code-themes.ts 的 PRISM_THEME_MAP / HLJS_THEME_MAP 中存在
  4. shikiTheme 值必须是 Shiki BundledTheme
  5. Loader 自动发现——无需改代码

关键设计决策

  • 不用 Catppuccin / Solarized / Monokai 占位：已删除早期占位主题，只保留有完整 light+dark 对且在两种模式下都有明显差异的 family
  • Rose Pine 合并：Dawn 是 light 变体，Base 是 dark 变体，Moon 的 light 和 Base 一样 → 只保留一个 rose-pine family
  • Tokyo Night 合并：Storm 和 Base 在 light 模式几乎无差异 → 只保留一个 tokyo-night family，light 使用真实 TN Light 色板
  • 硬编码蓝色清理：全局 blue-* / indigo-* Tailwind 类已替换为 primary 语义色，保留语义状态色（green/red/yellow）
  • Settings 预览用 Shiki：与 ai-elements 实际渲染一致，而非 Prism 近似