278 lines
6.5 KiB
Markdown
278 lines
6.5 KiB
Markdown
# 设计系统迁移指南
|
||
|
||
> 将现有前端代码迁移到统一设计系统
|
||
|
||
---
|
||
|
||
## 一、迁移步骤
|
||
|
||
### 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>
|
||
```
|
||
|
||
---
|
||
|
||
> **迁移完成后**，项目将拥有统一的设计语言，后续开发效率将显著提升。
|