flvx/plans/059-theme-system-design.md

059 - 主题系统设计（v2 — 完整可扩展架构）

概述

设计一个高度可扩展的主题包架构，允许第三方作者通过代码提交的方式创建主题，覆盖前端所有元素——从 CSS 变量到组件实现、布局结构、甚至整个页面。

架构

src/themes/
├── types.ts                  # ThemePackage 接口定义
├── registry.ts               # 主题注册表 + CSS 注入引擎
├── context.tsx                # React Context + Provider + Hooks
├── index.ts                  # 公共 API barrel
├── loader.ts                 # 主题加载器（注册所有内置主题）
├── README.md                 # 主题开发指南
│
├── default/                  # 默认主题（参考实现）
│   └── index.ts
│
├── example-cyberpunk/        # 示例主题（赛博朋克）
│   ├── index.ts
│   └── components/
│       └── button.tsx        # 组件覆盖示范
│
└── <your-theme>/             # 第三方主题
    ├── index.ts
    ├── components/
    ├── layouts/
    ├── pages/
    └── assets/

覆盖层级

层级	字段	说明
CSS 变量	tokens.light / tokens.dark	80+ 个设计 token（颜色、字体、圆角）
原始 CSS	css	注入自定义 CSS（动画、字体、阴影等）
组件替换	components	替换任意 UI 组件（30+ 个可替换组件键）
布局替换	layouts	替换 4 种布局（Admin / H5 / H5Simple / Default）
页面替换	pages	替换 14 个页面路由实现
生命周期	onActivate / onDeactivate	主题启用/停用回调

任务清单

• T1: 创建 src/themes/types.ts — ThemePackage 接口 + 所有可覆盖键定义
• T2: 创建 src/themes/registry.ts — 主题注册/激活/停用/CSS 注入引擎
• T3: 创建 src/themes/context.tsx — React Context + ThemeProvider + hooks
• T4: 创建 src/themes/index.ts — 公共 API barrel
• T5: 创建 src/themes/loader.ts — 自动加载所有内置主题
• T6: 创建 src/themes/default/ — 默认主题参考实现
• T7: 创建 src/themes/example-cyberpunk/ — 完整示例主题（含组件覆盖 + CSS + 生命周期）
• T8: 重构 use-theme.tsx — 向后兼容包装
• T9: 重构 theme-provider.tsx — 集成新主题系统
• T10: 编写 README.md — 主题开发完整指南
• T11: TypeScript 编译验证通过
• T12: (后续) 设置页面集成主题选择器 UI
• T13: (后续) 将现有组件导入逐步迁移到 useThemedComponent 模式