basic/skills/fa-theme-customizer/references/theme-structure.md

主题 CSS 变量结构说明

变量分类

主题由两类变量组成：

1. shadcn 标准 token — 通用设计系统变量，控制组件颜色
2. 框架专属 token（--g-*） — 控制布局区域颜色

---

shadcn 标准 Token

格式：'L C H'（OKLCH 三个数值，不含 oklch() 包裹）

变量	作用
--background	页面主背景色
--foreground	主文字颜色
--card	卡片背景色（通常同 background）
--card-foreground	卡片文字颜色
--popover	弹出层背景色
--popover-foreground	弹出层文字颜色
--primary	主色调（按钮、高亮、激活状态）
--primary-foreground	主色上的文字颜色
--secondary	次要色（次要按钮、标签背景）
--secondary-foreground	次要色上的文字颜色
--muted	静音色（禁用状态、次要背景）
--muted-foreground	静音色上的文字颜色
--accent	强调色（hover 状态背景）
--accent-foreground	强调色上的文字颜色
--destructive	危险/错误色（删除、警告）
--border	边框颜色
--input	输入框边框颜色
--ring	焦点环颜色（通常同 primary）

---

框架专属 Token（--g-*）

格式：'oklch(L C H)' 或 'oklch(var(--xxx))'（含 oklch() 包裹）

变量	作用
--g-main-area-bg	主内容区域背景
--g-header-bg	顶部背景
--g-header-color	顶部文字颜色
--g-header-menu-color	顶部导航菜单项文字颜色
--g-header-menu-hover-bg	顶部导航菜单项 hover 背景
--g-header-menu-hover-color	顶部导航菜单项 hover 文字颜色
--g-header-menu-active-bg	顶部导航菜单项激活背景
--g-header-menu-active-color	顶部导航菜单项激活文字颜色
--g-main-sidebar-bg	主侧边栏背景
--g-main-sidebar-menu-color	主侧边栏导航菜单文字颜色
--g-main-sidebar-menu-hover-bg	主侧边栏导航菜单 hover 背景
--g-main-sidebar-menu-hover-color	主侧边栏导航菜单 hover 文字颜色
--g-main-sidebar-menu-active-bg	主侧边栏导航菜单激活背景
--g-main-sidebar-menu-active-color	主侧边栏导航菜单激活文字颜色
--g-sub-sidebar-bg	次侧边栏背景
--g-sub-sidebar-menu-color	次侧边栏导航菜单文字颜色
--g-sub-sidebar-menu-hover-bg	次侧边栏导航菜单 hover 背景
--g-sub-sidebar-menu-hover-color	次侧边栏导航菜单 hover 文字颜色
--g-sub-sidebar-menu-active-bg	次侧边栏导航菜单激活背景
--g-sub-sidebar-menu-active-color	次侧边栏导航菜单激活文字颜色
--g-tabbar-bg	标签栏背景
--g-tabbar-tab-color	标签项文字颜色
--g-tabbar-tab-hover-bg	标签项 hover 背景
--g-tabbar-tab-hover-color	标签项 hover 文字颜色
--g-tabbar-tab-active-bg	标签项激活背景
--g-tabbar-tab-active-color	标签项激活文字颜色
--g-toolbar-bg	工具栏背景

---

明色与暗色的关键差异

差异一：菜单激活状态

明色使用 primary，暗色使用 accent：

// 明色
'--g-header-menu-active-bg': 'oklch(var(--primary))',
'--g-header-menu-active-color': 'oklch(var(--primary-foreground))',

// 暗色
'--g-header-menu-active-bg': 'oklch(var(--accent))',
'--g-header-menu-active-color': 'oklch(var(--accent-foreground))',

同样适用于 --g-main-sidebar-menu-active-* 和 --g-sub-sidebar-menu-active-*。

差异二：主内容区背景

// 明色：略深于背景，形成层次感
'--g-main-area-bg': 'oklch(0.9612 0 0)',

// 暗色：与背景相同，避免过多层次
'--g-main-area-bg': 'oklch(var(--background))',

差异三：标签栏 hover 背景

// 明色
'--g-tabbar-tab-hover-bg': 'oklch(var(--border))',

// 暗色
'--g-tabbar-tab-hover-bg': 'oklch(var(--accent) / 50%)',

差异四：标签栏激活背景

// 明色
'--g-tabbar-tab-active-bg': 'oklch(var(--background))',

// 暗色
'--g-tabbar-tab-active-bg': 'oklch(var(--secondary))',

差异五：菜单颜色引用

// 明色：使用 accent-foreground
'--g-header-menu-color': 'oklch(var(--accent-foreground))',
'--g-header-menu-hover-color': 'oklch(var(--accent-foreground))',

// 暗色：使用 muted-foreground
'--g-header-menu-color': 'oklch(var(--muted-foreground))',
'--g-header-menu-hover-color': 'oklch(var(--muted-foreground))',

---

完整暗色 --g-* 模板

dark: {
  // shadcn token ...
  '--g-main-area-bg': 'oklch(var(--background))',
  '--g-header-bg': 'oklch(var(--background))',
  '--g-header-color': 'oklch(var(--foreground))',
  '--g-header-menu-color': 'oklch(var(--muted-foreground))',
  '--g-header-menu-hover-bg': 'oklch(var(--muted))',
  '--g-header-menu-hover-color': 'oklch(var(--muted-foreground))',
  '--g-header-menu-active-bg': 'oklch(var(--accent))',
  '--g-header-menu-active-color': 'oklch(var(--accent-foreground))',
  '--g-main-sidebar-bg': 'oklch(var(--background))',
  '--g-main-sidebar-menu-color': 'oklch(var(--muted-foreground))',
  '--g-main-sidebar-menu-hover-bg': 'oklch(var(--muted))',
  '--g-main-sidebar-menu-hover-color': 'oklch(var(--muted-foreground))',
  '--g-main-sidebar-menu-active-bg': 'oklch(var(--accent))',
  '--g-main-sidebar-menu-active-color': 'oklch(var(--accent-foreground))',
  '--g-sub-sidebar-bg': 'oklch(var(--background))',
  '--g-sub-sidebar-menu-color': 'oklch(var(--muted-foreground))',
  '--g-sub-sidebar-menu-hover-bg': 'oklch(var(--muted))',
  '--g-sub-sidebar-menu-hover-color': 'oklch(var(--muted-foreground))',
  '--g-sub-sidebar-menu-active-bg': 'oklch(var(--accent))',
  '--g-sub-sidebar-menu-active-color': 'oklch(var(--accent-foreground))',
  '--g-tabbar-bg': 'oklch(var(--background))',
  '--g-tabbar-tab-color': 'oklch(var(--accent-foreground) / 50%)',
  '--g-tabbar-tab-hover-bg': 'oklch(var(--accent) / 50%)',
  '--g-tabbar-tab-hover-color': 'oklch(var(--accent-foreground) / 50%)',
  '--g-tabbar-tab-active-bg': 'oklch(var(--accent))',
  '--g-tabbar-tab-active-color': 'oklch(var(--foreground))',
  '--g-toolbar-bg': 'oklch(var(--background))',
},