library-picturebook-activity/frontend/docs/theme-customization.md

# 主题色修改指南

本文档说明如何修改 Ant Design Vue 的主题色。

## 📋 概述

项目使用 Ant Design Vue 4.x 作为 UI 组件库，主题色配置主要通过两个文件实现：

1. **`src/styles/theme.scss`** - CSS 变量定义，用于全局样式和侧边栏等自定义组件
2. **`src/App.vue`** - Ant Design Vue 的 ConfigProvider 配置，用于组件库的主题色

## 📁 需要修改的文件

### 1. `src/styles/theme.scss`

该文件定义了 CSS 变量，用于：

- 全局主题色变量
- 侧边栏菜单样式
- 自定义组件的主题色

### 2. `src/App.vue`

该文件通过 `a-config-provider` 组件配置 Ant Design Vue 的主题色，影响所有 Ant Design Vue 组件的默认颜色。

## 🔧 修改步骤

### 步骤 1: 修改 `src/styles/theme.scss`

在 `:root` 选择器中修改以下 CSS 变量：

```scss
:root {
  // 主色调
  --ant-color-primary: #1890ff; // 主色
  --ant-color-primary-hover: #40a9ff; // 悬停色（通常比主色浅）
  --ant-color-primary-active: #096dd9; // 激活色（通常比主色深）
  --ant-color-primary-bg: #e6f7ff; // 主色背景（浅色背景）
  --ant-color-primary-bg-hover: #bae7ff; // 主色背景悬停

  // 信息色（通常与主色一致）
  --ant-color-info: #1890ff;
  --ant-color-info-bg: #e6f7ff;

  // 链接色（通常与主色一致）
  --ant-color-link: #1890ff;
  --ant-color-link-hover: #40a9ff;
  --ant-color-link-active: #096dd9;

  // 侧边栏相关颜色
  --sidebar-menu-item-hover: #e6f7ff; // 菜单项悬停背景
  --sidebar-menu-item-selected-bg: #e6f7ff; // 菜单项选中背景色
  --sidebar-menu-text-selected: #1890ff; // 选中菜单文字颜色
}
```

### 步骤 2: 修改 `src/App.vue`

在 `themeConfig` 对象中修改主题色配置：

```typescript
const themeConfig: ConfigProviderProps["theme"] = {
  token: {
    colorPrimary: "#1890ff", // 主色调
    colorInfo: "#1890ff", // 信息色（通常与主色一致）
    colorLink: "#1890ff", // 链接色（通常与主色一致）
    borderRadius: 6, // 圆角（可选）
  },
  algorithm: undefined, // 使用默认算法
}
```

## 🎨 颜色值说明

### 主色调（Primary）

- **主色（colorPrimary）**: 按钮、链接、选中状态等的主要颜色
- **悬停色（hover）**: 鼠标悬停时的颜色，通常比主色浅 10-20%
- **激活色（active）**: 点击时的颜色，通常比主色深 10-20%
- **背景色（bg）**: 选中项的背景色，通常是主色的 5-10% 透明度

### 颜色搭配建议

1. **悬停色**: 在主色的基础上增加亮度（HSL 的 L 值增加 10-15%）
2. **激活色**: 在主色的基础上降低亮度（HSL 的 L 值减少 10-15%）
3. **背景色**: 使用主色的浅色版本（透明度约 5-10%）

## 📝 常见主题色示例

### 拂晓蓝主题（Daybreak Blue）- 官方推荐

**拂晓蓝**是 Ant Design 官方的基础色板中的蓝色，代表"包容、科技、普惠"。这是 Ant Design Vue 的默认主题色。

参考文档：[Ant Design 色彩规范](https://ant.design/docs/spec/colors-cn#%E7%B3%BB%E7%BB%9F%E7%BA%A7%E8%89%B2%E5%BD%A9%E4%BD%93%E7%B3%BB)

```scss
// theme.scss
// 拂晓蓝色板：blue-0 (#E6F4FF) 到 blue-9 (#001D66)
--ant-color-primary: #1890ff; // 主色 - blue-5（Ant Design Vue 4.x）
--ant-color-primary-hover: #40a9ff; // 悬停色 - blue-4
--ant-color-primary-active: #096dd9; // 激活色 - blue-6
--ant-color-primary-bg: #e6f7ff; // 主色背景 - blue-0（最浅）
```

```typescript
// App.vue
colorPrimary: "#1890ff" // 拂晓蓝主色
```

**完整的拂晓蓝色板**：

- blue-0: `#E6F4FF` (最浅)
- blue-1: `#BAE0FF`
- blue-2: `#91CAFF`
- blue-3: `#69B1FF`
- blue-4: `#4096FF`
- blue-5: `#1890ff` (主色，Ant Design Vue 4.x)
- blue-6: `#0958D9`
- blue-7: `#003EB3`
- blue-8: `#002C8C`
- blue-9: `#001D66` (最深)

### 橙色主题

```scss
// theme.scss
--ant-color-primary: #ff7a00;
--ant-color-primary-hover: #ff9a2e;
--ant-color-primary-active: #d46b08;
--ant-color-primary-bg: #fff7e6;
```

```typescript
// App.vue
colorPrimary: "#ff7a00"
```

### 墨绿色主题

```scss
// theme.scss
--ant-color-primary: #01412b;
--ant-color-primary-hover: #026b47;
--ant-color-primary-active: #013320;
--ant-color-primary-bg: #e2f0ed;
```

```typescript
// App.vue
colorPrimary: "#01412b"
```

### 紫色主题

```scss
// theme.scss
--ant-color-primary: #722ed1;
--ant-color-primary-hover: #9254de;
--ant-color-primary-active: #531dab;
--ant-color-primary-bg: #f9f0ff;
```

```typescript
// App.vue
colorPrimary: "#722ed1"
```

### 红色主题

```scss
// theme.scss
--ant-color-primary: #f5222d;
--ant-color-primary-hover: #ff4d4f;
--ant-color-primary-active: #cf1322;
--ant-color-primary-bg: #fff1f0;
```

```typescript
// App.vue
colorPrimary: "#f5222d"
```

## ⚠️ 注意事项

1. **同步修改**: 必须同时修改 `theme.scss` 和 `App.vue` 两个文件，确保主题色一致

2. **颜色对比度**: 确保文字颜色与背景色有足够的对比度，符合无障碍访问标准（WCAG AA 级别）

3. **侧边栏颜色**: 如果修改了主色调，记得同步更新侧边栏相关的 CSS 变量：
   - `--sidebar-menu-item-hover`
   - `--sidebar-menu-item-selected-bg`
   - `--sidebar-menu-text-selected`

4. **深色模式**: 如果项目支持深色模式，需要在 `[data-theme="dark"]` 选择器中定义深色模式的主题色

5. **浏览器缓存**: 修改后可能需要清除浏览器缓存或强制刷新（Ctrl+F5）才能看到效果

6. **颜色格式**: 使用十六进制颜色值（如 `#1890ff`），也可以使用 RGB/RGBA 格式

## 🔍 颜色工具推荐

- **Ant Design 色彩工具**: https://ant.design/docs/spec/colors-cn
- **Coolors**: https://coolors.co/ - 配色方案生成器
- **Adobe Color**: https://color.adobe.com/ - 颜色搭配工具
- **Material Design Color Tool**: https://material.io/resources/color/ - Material Design 配色工具

## 📚 相关文档

- [Ant Design Vue 主题定制](https://antdv.com/docs/vue/customize-theme-cn)
- [CSS 变量](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties)

## 🎯 快速修改模板

如果需要快速修改主题色，可以按照以下模板操作：

1. 选择主色调（例如：`#ff7a00`）
2. 计算悬停色（主色 + 亮度）
3. 计算激活色（主色 - 亮度）
4. 选择背景色（主色的浅色版本）

然后替换以下位置的值：

- `src/styles/theme.scss` 中的 `--ant-color-primary*` 变量
- `src/App.vue` 中的 `colorPrimary`、`colorInfo`、`colorLink` 值

修改完成后，重启开发服务器或刷新页面即可看到效果。