# 设计系统迁移指南

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

---

## 一、迁移步骤

### Step 1: 引入设计令牌

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

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

### Step 2: 配置 TailwindCSS

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

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

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

### Step 3: 配置 Ant Design Vue 主题

更新 `src/App.vue`：

```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 (问题代码)**:
```less
// ❌ 组件内定义变量
@primary: #6366f1;
@primary-gold: #D4A853;

.button {
  background: #1890FF;
}
```

**After (规范代码)**:
```less
// ✅ 使用全局设计令牌
.button {
  background: var(--color-primary-500);

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

### 2.2 字体迁移

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

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

### 2.3 间距迁移

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

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

### 2.4 使用 TailwindCSS

```vue
<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 颜色替换

```bash
# 在 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 间距替换

```bash
# 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>` 中添加：

```html
<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>
```

---

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