Tencent · RylanBot · Jul 20, 2025 · Jul 20, 2025 · Jul 20, 2025 · Jul 21, 2025
diff --git a/packages/theme-generator/CONTRIBUTING_zh-CN.md b/packages/theme-generator/CONTRIBUTING_zh-CN.md
@@ -0,0 +1,76 @@
+# CONTRIBUTING
+
+**如果你想要新增特性或修复 Bug，建议阅读本文档，以便更好地理解代码的实现**
+
+## 📁 目录结构
+
+项目 UI 层由一个浮动入口 `dock` 和一个包含多个功能面板的侧边 `panel` 组成：
+
+```mermaid
+graph TB
+  A[Generator] --> B[float-dock]
+  A[Generator] --> C[panel-drawer]
+
+  C[panel-drawer] --> D[color-panel]
+  C[panel-drawer] --> E[font-panel]
+  C[panel-drawer] --> F[shadow-panel]
+  C[panel-drawer] --> G[radius-panel]
+  C[panel-drawer] --> H[size-panel]
+
+  classDef panelFill fill:#e6fffb,stroke:#13c2c2,stroke-width:2px;
+  class D,E,F,G,H panelFill;
+```
+
+项目还包含两个文件夹：
+
+```mermaid
+graph TB
+  A[styles] --> B["*.min.css 样式文件"]
+
+  C[common] --> D[components 通用组件]
+  C[common] --> E[i18n 国际化]
+  C[common] --> F[theme 核心逻辑<br>（包括内置主题模板和颜色算法等实现）]
+  C[common] --> G[utils 工具函数]
+
+  classDef themeFill fill:#e6f7ff,stroke:#1890ff,stroke-width:2px;
+  class F themeFill
+```
+
+`*.min.css` 文件来自 `tdesign-vue` 且经过二次压缩
+
+- 额外添加了 `:host` 选择器，确保 Web Components 打包后样式正常
+- 移除 `td-brand-color-x` 系列颜色 Token，使主题生成器能与外部主题色直接同步
+
+## 🧚 交互逻辑
+
+### 数据持久化
+
+1. `custom-theme-options`：
+
+| Key                           | 类型                       | 示例                  |
+| ----------------------------- | -------------------------- | --------------------- |
+| `theme`                       | 主题                       | `TCloud`              |
+| `color`                       | 主题色                     | `#45C58B`             |
+| `gray/success/warning/danger` | 功能色的品牌色             | `#2ba471`             |
+| `font/radius/shadow`          | 预设步骤中的位置           | `1`                   |
+| `line-height`                 | 固定或递增模式及其参数 | `plus_9` / `time_1.5` |
+| `recommend`                   | 智能推荐                   | `true`                |
+| `neutral`                     | 关联主题色                 | `true`                |
+
+2. `custom-theme-tokens`：各种 `--td-*` token，主要来自用户手动修改单个变量的操作
+
+### 执行流程
+
+1. **初始化**：根据本地存储的 `theme`（或默认主题），进行 CSS 模板挂载
+
+2. **配置恢复**：读取本地存储的 `tokens`，并还原用户的自定义修改
+
+3. **面板渲染**：各个 Panel 根据 `options` 确定初始化数值
+
+## 😈 开发规范
+
+1. **常量管理**：使用 `UPPER_CASE` 命名方式，独立存放在 JS 文件中，与 Vue 逻辑分离
+
+2. **全局状态管理**：避免通过 props 层层传递共享变量，优先使用 `inject`、`mixin` 或 `store` 等
+
+3. **动态编码管理**：避免硬编码数值，特别是 Token 相关的映射，优先从 CSS 中获取配置
diff --git a/packages/theme-generator/README-zh_CN.md b/packages/theme-generator/README-zh_CN.md
@@ -1,16 +1,10 @@
-# tdesign-theme-generator
+<h1 style="text-align: center"><em><img alt="TDesign Logo" width="40" src="https://tdesign.tencent.com/favicon.ico"> TDesign Theme Generator</em></h1>
 
-- TDesign 主题配置生成器挂件 支持任意框架使用。
+[English](./README.md) | 简体中文
 
-## 🏗️ Develop
+TDesign 主题生成器挂件，专为组件库的文档站点量身打造，用于实时预览配色和样式的调整。
 
-- `npm run dev`
-
-- `npm run build:watch` 配合 npm link 进入站点热更新预览
-
-- `npm run build` 构建 web component
-
-## 📦 Usage
+## 🔨 基础使用
 
 1. `npm i tdesign-theme-generator`
 
@@ -27,3 +21,10 @@
     generator.setAttribute('device', 'mobile');
     document.body.appendChild(generator);
   ```
+
+## 🏗️ 快速开发
+
+```bash
+npm link
+npm run build:watch # 进入组件库站点热更新预览
+```
diff --git a/packages/theme-generator/README.md b/packages/theme-generator/README.md
@@ -1,18 +1,10 @@
-## TDesign Theme Generator Plugin
+<h1 style="text-align: center"><em><img alt="TDesign Logo" width="40" src="https://tdesign.tencent.com/favicon.ico"> TDesign Theme Generator</em></h1>
 
-- TDesign theme generator plugin, which is available in any web application.
+English | [简体中文](./README_zh-CN.md)
 
-### 🏗️ Develop
+TDesign theme generator plugin, which is tailored for the component library documentation site. It is used for real-time preview of color and style adjustments.
 
-- `npm run dev`
-
-- `npm run build:watch` execute `npm link` as well to preview in application project
-
-### ⚙️ Build
-
-- `npm run build` build web-component
-
-### 📦 Usage
+## 🔨 Usage
 
 1. `npm i tdesign-theme-generator`
 
@@ -29,3 +21,10 @@
     generator.setAttribute('device', 'mobile');
     document.body.appendChild(generator);
   ```
+
+## 🏗️ Develop
+
+```bash
+npm link
+npm run build:watch # open the component library site with hot-reload preview
+```
diff --git a/packages/theme-generator/package.json b/packages/theme-generator/package.json
@@ -31,7 +31,7 @@
     "cssbeautify": "^0.3.1",
     "lodash": "^4.17.21",
     "tdesign-icons-vue": "^0.0.8",
-    "tdesign-vue": "1.9.4-naruto",
+    "tdesign-vue": "1.13.1-naruto",
     "tvision-color": "^1.6.0",
     "vue": "2.7.14"
   },

diff --git a/packages/theme-generator/src/Generator.vue b/packages/theme-generator/src/Generator.vue
@@ -1,51 +1,34 @@
 <template>
   <div class="theme-generator">
-    <dock
-      @trigger-visible="handleTriggerVisible"
-      @refresh-content="handleRefreshContent"
-      @change-theme="handleChangeTheme"
-      @click-setting="handleClickSetting"
+    <float-dock
       :drawerVisible="visible"
       :showSetting="showSetting"
+      @click-setting="handleClickSetting"
+      @trigger-visible="handleTriggerVisible"
     />
-    <panel-drawer
-      :drawerVisible="visible"
-      :theme="theme"
-      :refresh="refresh"
-      @panel-drawer-visible="handleDrawerVisible"
-      :propsTop="propsTop"
-    />
+    <panel-drawer :drawerVisible="visible" @panel-drawer-visible="handleDrawerVisible" />
   </div>
 </template>
 
 <script>
 import {
-  applyThemeFromLocal,
-  DEFAULT_THEME,
-  generateNewTheme,
-  getOptionFromLocal,
+  applyTokenFromLocal,
+  initGeneratorVars,
+  syncModeToGenerator,
   syncThemeToIframe,
-} from './common/Themes';
-
-import Dock from './dock/index.vue';
-import PanelDrawer from './panel-drawer/index.vue';
+  themeStore,
+} from './common/themes';
 
-const activeTabMap = {
-  color: 0,
-  font: 1,
-  radius: 2,
-  shadow: 3,
-  size: 4,
-};
+import FloatDock from './float-dock';
+import PanelDrawer from './panel-drawer';
 
 export default {
   name: 'ThemeGenerator',
   components: {
+    FloatDock,
     PanelDrawer,
-    Dock,
   },
   props: {
-    propsTop: String,
     showSetting: {
       type: [Boolean, String],
     },
@@ -54,42 +37,31 @@ export default {
       default: 'web',
     },
   },
-  provide() {
-    return {
-      device: this.device,
-    };
-  },
   data() {
     return {
-      activeTabMap,
-      refresh: false,
       visible: 0,
-      activeTabIdx: activeTabMap.color,
-      theme: DEFAULT_THEME,
     };
   },
+  computed: {
+    $theme() {
+      return themeStore.theme;
+    },
+  },
   mounted() {
-    const localTheme = getOptionFromLocal('color') ?? DEFAULT_THEME.value;
-    generateNewTheme(localTheme, undefined, this.device);
+    themeStore.updateDevice(this.device);
+    syncModeToGenerator();
+    initGeneratorVars();
+    applyTokenFromLocal();
     syncThemeToIframe(this.device);
-    applyThemeFromLocal(this.device);
   },
   methods: {
-    handleChangeTheme(theme) {
-      this.theme = theme;
-    },
-    handleRefreshContent() {
-      this.refresh = !this.refresh;
-    },
     handleTriggerVisible() {
       this.visible = true;
     },
     handleDrawerVisible(v) {
       this.visible = v;
-      this.$emit('panel-drawer-visible', v);
     },
     handleClickSetting() {
-      this.$emit('click-setting');
       this.visible = false;
     },
   },
@@ -107,12 +79,15 @@ export default {
 }
 </style>
 <style>
-.t-popup .t-select-option {
-  font-size: 14px;
-}
 .t-popconfirm {
   z-index: 10000;
 }
+.t-popconfirm .t-icon {
+  font-size: 20px !important;
+}
+.t-popup .t-select-option {
+  font-size: 14px;
+}
 .t-popup .t-input-number {
   font-size: 14px;
 }
@@ -122,23 +97,22 @@ export default {
 .t-popup .t-icon {
   font-size: 14px !important;
 }
-
-.t-popconfirm .t-icon {
-  font-size: 20px !important;
-}
 .t-popup .t-select__empty {
   font-size: 14px;
 }
-.t-button.t-size-l {
-  font-size: 16px;
-}
 .t-radio-button__label {
   font-size: 14px;
 }
+.t-radio-group__bg-block {
+  background: var(--bg-color-theme-radio-active) !important;
+}
 .t-slider__button {
   width: 16px;
   height: 16px;
 }
+.t-button.t-size-l {
+  font-size: 16px;
+}
 .t-button--variant-base.t-button--theme-primary:hover,
 .t-button--variant-base.t-button--theme-primary:focus-visible {
   border-color: var(--brand-main-hover);

diff --git a/packages/theme-generator/src/README.md b/packages/theme-generator/src/README.md
diff --git a/packages/theme-generator/src/color-panel/built-in/color-map.js b/packages/theme-generator/src/color-panel/built-in/color-map.js
@@ -0,0 +1,48 @@
+export const GRAY_TOKENS = [
+  '--td-bg-color-container-hover',
+  '--td-bg-color-secondarycontainer',
+  '--td-bg-color-secondarycontainer-hover',
+  '--td-bg-color-component-disabled',
+  '--td-bg-color-page',
+  '--td-bg-color-container-active',
+  '--td-bg-color-component',
+  '--td-component-stroke',
+  '--td-bg-color-secondarycontainer-active',
+  '--td-bg-color-component-hover',
+  '--td-component-border',
+  '--td-bg-color-component-active',
+];
+
+export const SUCCESS_TOKENS = [
+  '--td-success-color-light',
+  '--td-success-color-focus',
+  '--td-success-color-disabled',
+  '--td-success-color-hover',
+  '--td-success-color',
+  '--td-success-color-active',
+];
+
+export const ERROR_TOKENS = [
+  '--td-error-color-light',
+  '--td-error-color-focus',
+  '--td-error-color-disabled',
+  '--td-error-color-hover',
+  '--td-error-color',
+  '--td-error-color-active',
+];
+
+export const WARNING_TOKENS = [
+  '--td-warning-color-light',
+  '--td-warning-color-focus',
+  '--td-warning-color-disabled',
+  '--td-warning-color-hover',
+  '--td-warning-color',
+  '--td-warning-color-active',
+];
+
+export const FUNCTION_TOKENS = {
+  gray: GRAY_TOKENS,
+  success: SUCCESS_TOKENS,
+  error: ERROR_TOKENS,
+  warning: WARNING_TOKENS,
+};