sionrui/frontend/app/web-gold/docs/DESIGN_MIGRATION_GUIDE.md

设计系统迁移指南

将现有前端代码迁移到统一设计系统

---

一、迁移步骤

Step 1: 引入设计令牌

在 src/main.ts 中添加设计令牌导入：

// main.ts
import './styles/design-tokens.css'  // 添加在最先
import './style.less'
// ... 其他导入

Step 2: 配置 TailwindCSS

更新 tailwind.config.js 为 tailwind.config.ts：

# 删除旧配置
rm tailwind.config.js

# 使用新配置
# 已创建: tailwind.config.ts

Step 3: 配置 Ant Design Vue 主题

更新 src/App.vue：

<script setup lang="ts">
import { ConfigProvider, theme } from 'ant-design-vue'
import { antdThemeConfig, themeManager } from '@gold/styles/antd-theme'

const isDark = ref(themeManager.initTheme())
const currentTheme = computed(() => themeManager.getAntdTheme(isDark.value))

// 监听系统主题变化
watchEffect(() => {
  const media = window.matchMedia('(prefers-color-scheme: dark)')
  const handler = (e: MediaQueryListEvent) => {
    if (!localStorage.getItem('theme')) {
      isDark.value = e.matches
      themeManager.setTheme(e.matches)
    }
  }
  media.addEventListener('change', handler)
})
</script>

<template>
  <ConfigProvider :theme="currentTheme">
    <router-view />
  </ConfigProvider>
</template>

---

二、组件迁移示例

2.1 颜色迁移

Before (问题代码):

// ❌ 组件内定义变量
@primary: #6366f1;
@primary-gold: #D4A853;

.button {
  background: #1890FF;
}

After (规范代码):

// ✅ 使用全局设计令牌
.button {
  background: var(--color-primary-500);

  &:hover {
    background: var(--color-primary-400);
  }
}

2.2 字体迁移

Before:

/* ❌ 硬编码字体大小 */
.title { font-size: 24px; }
.desc { font-size: 12px; }

After:

/* ✅ 使用设计令牌 */
.title { font-size: var(--font-size-2xl); }
.desc { font-size: var(--font-size-xs); }

2.3 间距迁移

Before:

/* ❌ 魔法数字 */
.card {
  padding: 20px;
  margin-top: 24px;
  gap: 16px;
}

After:

/* ✅ 语义化间距 */
.card {
  padding: var(--space-5);
  margin-top: var(--space-6);
  gap: var(--space-4);
}

2.4 使用 TailwindCSS

<template>
  <!-- 使用 TailwindCSS 工具类 -->
  <div class="p-5 rounded-lg shadow-base bg-white">
    <h2 class="text-lg font-medium text-gray-900">标题</h2>
    <p class="mt-2 text-sm text-gray-500">描述文字</p>
    <button class="mt-4 px-4 py-2 bg-primary-500 text-white rounded-base
                   hover:bg-primary-400 transition-duration-fast">
      操作按钮
    </button>
  </div>
</template>

---

三、需要修改的文件清单

优先级 P0 - 立即修改

文件	问题	修改内容
src/components/agents/ChatDrawer.vue	局部定义 @primary: #6366f1	改用 var(--color-primary-500)
src/components/agents/HistoryPanel.vue	局部定义 @primary: #6366f1	改用 var(--color-primary-500)
src/views/auth/Login.vue	金色主题 @primary-gold: #D4A853	改用品牌蓝
src/views/home/Home.vue	硬编码颜色 #1890FF	改用 var(--color-primary-500)

优先级 P1 - 短期修改

文件	问题
src/views/content-style/Copywriting.vue	混用 var(--color-primary) 和 #1677ff
src/components/GradientButton.vue	需要验证与设计系统一致

---

四、批量替换脚本

4.1 颜色替换

# 在 frontend/app/web-gold 目录执行

# 替换硬编码的主色
find src -name "*.vue" -o -name "*.less" | xargs sed -i 's/#1890FF/var(--color-primary-500)/g'
find src -name "*.vue" -o -name "*.less" | xargs sed -i 's/#40A9FF/var(--color-primary-400)/g'
find src -name "*.vue" -o -name "*.less" | xargs sed -i 's/#6366f1/var(--color-primary-500)/g'
find src -name "*.vue" -o -name "*.less" | xargs sed -i 's/#1677ff/var(--color-primary-500)/g'

4.2 间距替换

# padding: 16px -> padding: var(--space-4)
find src -name "*.vue" -o -name "*.less" | xargs sed -i 's/padding: 16px/padding: var(--space-4)/g'
find src -name "*.vue" -o -name "*.less" | xargs sed -i 's/padding: 20px/padding: var(--space-5)/g'
find src -name "*.vue" -o -name "*.less" | xargs sed -i 's/padding: 24px/padding: var(--space-6)/g'

---

五、验证清单

完成迁移后，检查以下项目：

• 所有颜色使用 CSS 变量或 TailwindCSS 类
• 没有硬编码的 #xxxxxx 颜色值（除特殊情况）
• 字体大小使用 var(--font-size-*) 或 TailwindCSS
• 间距使用 var(--space-*) 或 TailwindCSS
• 组件内没有重复定义 @primary 等 Less 变量
• 页面视觉效果一致
• 深色模式切换正常工作

---

六、设计令牌速查表

颜色

用途	变量	值
主色	--color-primary-500	#3B82F6
主色悬浮	--color-primary-400	#60A5FA
成功	--color-success-500	#22C55E
警告	--color-warning-500	#F59E0B
错误	--color-error-500	#EF4444
正文	--color-text-primary	#111827
次要文字	--color-text-secondary	#4B5563
边框	--color-border	#E5E7EB

间距

变量	值	用途
--space-2	8px	图标与文字
--space-3	12px	小间距
--space-4	16px	标准间距
--space-5	20px	卡片内边距
--space-6	24px	区块间距

圆角

变量	值	用途
--radius-sm	4px	标签
--radius-base	6px	按钮、输入框
--radius-md	8px	下拉框
--radius-lg	12px	卡片、弹窗

---

七、常见问题

Q: 旧组件样式不生效？

确保设计令牌在 main.ts 中最先导入。

Q: Ant Design 组件样式不一致？

检查 App.vue 中是否正确配置了 ConfigProvider 的 theme 属性。

Q: TailwindCSS 类不生效？

1. 确保 tailwind.config.ts 文件存在
2. 确保 postcss.config.js 配置正确
3. 重启开发服务器

Q: 深色模式切换有闪烁？

在 index.html 的 <head> 中添加：

<script>
  (function() {
    const theme = localStorage.getItem('theme');
    if (theme === 'dark' || (!theme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
      document.documentElement.setAttribute('data-theme', 'dark');
    }
  })();
</script>

---

迁移完成后，项目将拥有统一的设计语言，后续开发效率将显著提升。