fa-theme-customizer - SKILL.md Agent Skill

name: fa-theme-customizer description: 为 Fantastic-admin 框架创建和定制主题配色方案，始终同时生成明色（light）和暗色（dark）两套主题。当用户提到以下任何需求时必须使用此技能：换主题颜色、换配色、做一个 XX 风格的主题、主题太单调了、品牌色是 XXX 帮我生成主题、把 tweakcn 配色转成框架主题、想要暗色/冷色/暖色调、根据设计稿颜色生成主题。即使用户只是描述一种感觉（"清新"、"沉稳"、"科技感"）或提供一个颜色值（"#2563EB"），也应触发此技能。支持"吉卜力"、"赛博朋克"、"莫兰迪"、"北欧极简"等专业设计风格关键词。

主题定制器

为 Fantastic-admin 框架生成符合规范的主题配色。

核心原则：始终同时输出明色和暗色两套。theme.sync 默认为 true，切换颜色方案时明暗共用同一套主题名称，缺少任何一套都会导致对应模式下显示异常。

文件位置

主题定义：packages/themes/index.ts（跨所有应用共享）
应用设置：apps/<app>/src/settings.ts（启用主题）
类型推断：自动从 index.ts 的 key 推断，无需手动更新类型

三层架构

层	导出名	内容	何时生成
基础色	`BASE_COLORS`	18 个 shadcn token × 明/暗（背景、文字、边框等）	仅当用户需要自定义基础色基调
主题色	`THEMES`	4 个品牌色 token × 明/暗（primary / secondary）	始终生成
框架布局色	`FRAMEWORK_COLORS`	全局布局颜色（顶栏、侧栏、标签栏等）	极少调整 — 静态定义，通过 CSS 变量自动适配；仅当用户明确要求修改框架区域配色时才调整

FRAMEWORK_COLORS 是固定的 light/dark 定义，全部引用 CSS 变量（如 oklch(var(--background))）。结构细节见 references/theme-structure.md。

工作流程

第一步：判断生成范围

用户意图	需要生成
提到"基础色"、"底色"、"背景色风格"、具体基础色名（neutral/stone/zinc 等）	BASE_COLORS + THEMES
仅提到主题色、品牌色、风格感觉	仅 THEMES
明确提到要修改框架区域配色（顶栏、侧栏、标签栏等）	THEMES + FRAMEWORK_COLORS

第二步：确定设计风格

如果用户未明确指定颜色，读取 references/design-styles.md 获取完整的风格目录和配色建议。

第三步：生成 OKLCH 色值

框架使用 OKLCH 色彩空间，格式为 'L C H'（三个数值，不含 oklch() 包裹）。

关键转换规则：

明色背景：1 0 0（纯白）或接近白色的色调
暗色背景：0.141 0.005 285.823 附近（深灰）
primary 明色 L 值通常比暗色高 0.05~0.1

读取 references/theme-structure.md 了解完整的 CSS 变量说明和取值规范。

第四步：写入主题文件

A. BASE_COLORS（仅在需要新基础色时）

需要完整的 18 个 shadcn 标准 token（明/暗各一套）：

// packages/themes/index.ts → BASE_COLORS
myBaseName: {
  light: {
    '--background': '1 0 0',
    '--foreground': 'L C H',
    '--card': 'L C H',            // 通常同 background
    '--card-foreground': 'L C H', // 通常同 foreground
    '--popover': 'L C H',         // 通常同 background
    '--popover-foreground': 'L C H', // 通常同 foreground
    '--primary': 'L C H',
    '--primary-foreground': 'L C H',
    '--secondary': 'L C H',
    '--secondary-foreground': 'L C H',
    '--muted': 'L C H',
    '--muted-foreground': 'L C H',
    '--accent': 'L C H',
    '--accent-foreground': 'L C H',
    '--destructive': '0.577 0.245 27.325',   // 明色固定值
    '--border': 'L C H',
    '--input': 'L C H',
    '--ring': 'L C H',                        // 通常同 primary
  },
  dark: {
    // 同明色结构，色值更深
    '--destructive': '0.704 0.191 22.216',   // 暗色固定值
  },
}

B. THEMES（始终需要）

仅需 4 个品牌色 token（明/暗各一套），其余继承自 BASE_COLORS：

// packages/themes/index.ts → THEMES
myTheme: {
  light: {
    '--primary': 'L C H',
    '--primary-foreground': 'L C H',
    '--secondary': 'L C H',
    '--secondary-foreground': 'L C H',
  },
  dark: {
    '--primary': 'L C H',
    '--primary-foreground': 'L C H',
    '--secondary': 'L C H',
    '--secondary-foreground': 'L C H',
  },
}

C. FRAMEWORK_COLORS（极少调整）

FRAMEWORK_COLORS 通过 CSS 变量引用自动适配大多数主题，通常无需修改。仅当用户明确要求修改框架区域（顶栏、侧栏、标签栏等）的配色风格时才调整。

修改时注意明色与暗色的关键差异，详见 references/theme-structure.md。

第五步：在应用设置中启用

先执行 ls apps/ 确认有哪些应用，询问用户要在哪个应用中启用，然后修改 apps/<app>/src/settings.ts：

theme: {
  // 自定义基础色时使用（可选）
  baseColorLight: 'myBaseName',   // 对应 BASE_COLORS 的 key
  baseColorDark: 'myBaseName',    // sync 为 true 时两者相同
  // 启用主题色（必选）
  light: 'myTheme',               // 对应 THEMES 的 key
  dark: 'myTheme',                // sync 为 true 时两者相同
}

sync 设置说明：

true（默认）：明暗共用同一套基础色和主题色
false：明暗可分别指定不同的基础色和主题色

第六步：验证

生成完成后，逐项检查：

明色和暗色两套是否都已生成
色值格式为 'L C H'，不含 oklch() 包裹
THEMES 条目中没有 --g-* 框架 token
destructive 使用了正确的明/暗固定值
已在目标应用的 settings.ts 中正确启用

常见错误

错误	正确做法
只生成明色或暗色一套	始终同时生成两套
在 THEMES 中添加 `--g-*` token	`--g-*` 由 FRAMEWORK_COLORS 统一管理
随意修改 FRAMEWORK_COLORS	该层通过 CSS 变量自动适配，仅在用户明确要求时才调整
BASE_COLORS 和 THEMES 混淆	BASE_COLORS 有 18 个 token，THEMES 只有 4 个
destructive 明暗用同一个值	明色 `0.577 0.245 27.325`，暗色 `0.704 0.191 22.216`
色值写成 `oklch(0.5 0.1 180)`	正确格式：`'0.5 0.1 180'`

参考资源

设计风格目录：references/design-styles.md — 20+ 种专业设计风格的配色方案和灵感来源
CSS 变量说明：references/theme-structure.md — 每个变量的作用、取值规范和明暗差异
社区配色：https://tweakcn.com/community — shadcn/ui 社区主题，可直接参考其 CSS 变量