flnxi-Wu/docs/guides/UI_STYLES_ARCHITECTURE.md

# UI 样式系统架构说明

## 架构设计

为了解决深浅色适配问题，同时保持视觉设计的统一性，我们采用了**三层架构**：

```
┌─────────────────────────────────────┐
│  ui-styles-light.ts / dark.ts       │  ← 最终导出的样式（由组合器生成）
│  (组件直接使用)                      │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│  ui-styles-composer.ts               │  ← 样式组合器（组合基础样式 + 颜色主题）
│  (自动组合生成)                       │
└──────────────┬──────────────────────┘
               │
      ┌────────┴────────┐
      │                  │
┌─────▼──────┐  ┌───────▼────────┐
│ ui-styles- │  │ ui-theme-      │
│ base.ts    │  │ colors-*.ts    │
│            │  │                │
│ 布局/大小/ │  │ 仅颜色配置     │
│ 动画等   │  │                │
└────────────┘  └────────────────┘
```

## 文件结构

### 1. `lib/ui-styles-base.ts` - 基础样式配置
**包含内容：**
- 布局（padding, margin, spacing）
- 大小（rounded, border-width）
- 动画（transition, hover effects）
- 结构（flex, grid, positioning）

**不包含：**
- 颜色（bg-*, text-*, border-* 的颜色部分）
- 阴影颜色（shadow-* 的颜色部分）

**示例：**
```typescript
export const baseCardStyles = {
  base: 'rounded-2xl border backdrop-blur-sm shadow-lg p-6 transition-all duration-300',
  // ↑ 只有结构，没有颜色
}
```

### 2. `lib/ui-theme-colors-light.ts` - 浅色模式颜色配置
**包含内容：**
- 所有颜色相关的 Tailwind 类名
- 浅色模式下的颜色值

**示例：**
```typescript
export const themeColors = {
  card: {
    border: 'border-slate-200/70',
    bg: 'bg-white',
    shadow: 'shadow-slate-200/50',
    // ...
  },
  // ...
}
```

### 3. `lib/ui-theme-colors-dark.ts` - 深色模式颜色配置
**包含内容：**
- 所有颜色相关的 Tailwind 类名
- 深色模式下的颜色值

**示例：**
```typescript
export const themeColors = {
  card: {
    border: 'border-slate-700/70',
    bg: 'bg-slate-800',
    shadow: 'shadow-black/50',
    // ...
  },
  // ...
}
```

### 4. `lib/ui-styles-composer.ts` - 样式组合器
**功能：**
- 将基础样式和颜色主题组合成完整的样式字符串
- 自动生成 `lightThemeStyles` 和 `darkThemeStyles`

**示例：**
```typescript
function composeCardStyles(colors: ColorTheme) {
  return {
    base: `${baseStyles.baseCardStyles.base} ${colors.card.border} ${colors.card.bg} ${colors.card.shadow}`,
    // ↑ 基础结构 + 颜色 = 完整样式
  }
}
```

### 5. `lib/ui-styles-light.ts` / `lib/ui-styles-dark.ts` - 最终导出
**功能：**
- 从组合器导入生成的样式
- 提供给组件使用

## 修改指南

### 修改布局、大小、动画等视觉设计

**修改文件：** `lib/ui-styles-base.ts`

**示例：** 如果要修改卡片的内边距从 `p-6` 改为 `p-8`：

```typescript
// lib/ui-styles-base.ts
export const baseCardStyles = {
  base: 'rounded-2xl border backdrop-blur-sm shadow-lg p-8 transition-all duration-300',
  //                                                              ↑ 改为 p-8
  // 这个修改会自动应用到浅色和深色模式
}
```

### 修改颜色

**修改文件：** 
- 浅色模式：`lib/ui-theme-colors-light.ts`
- 深色模式：`lib/ui-theme-colors-dark.ts`

**示例：** 如果要修改浅色模式下的主要按钮颜色：

```typescript
// lib/ui-theme-colors-light.ts
export const themeColors = {
  button: {
    primary: {
      bg: 'bg-indigo-700',  // 从 bg-indigo-600 改为 bg-indigo-700
      // ...
    },
  },
}
```

## 优势

### ✅ 统一视觉设计
- 修改布局、大小、动画时，只需修改 `ui-styles-base.ts` 一处
- 浅色和深色模式自动同步更新

### ✅ 独立颜色适配
- 颜色配置完全分离，互不影响
- 可以独立调整浅色或深色模式的颜色

### ✅ 易于维护
- 清晰的职责分离
- 修改时不会遗漏或出错

### ✅ 类型安全
- TypeScript 类型检查确保配置正确

## 使用方式

组件中的使用方式不变：

```tsx
'use client'
import { useThemeStyles } from '@/lib/ui-styles'

export default function MyComponent() {
  const styles = useThemeStyles()
  
  return (
    <div className={styles.cardStyles.base}>
      <button className={styles.buttonStyles.primary}>按钮</button>
    </div>
  )
}
```

## 迁移说明

现有的组件无需修改，因为：
- `ui-styles-light.ts` 和 `ui-styles-dark.ts` 的导出接口保持不变
- `useThemeStyles()` Hook 的行为保持不变
- 只是内部实现从硬编码改为组合生成

## 注意事项

1. **不要直接修改** `ui-styles-light.ts` 或 `ui-styles-dark.ts` 的内容
   - 这些文件是从组合器自动生成的
   - 修改会被覆盖

2. **修改基础样式**时，确保不包含颜色
   - 颜色应该在 `ui-theme-colors-*.ts` 中定义
   - 基础样式中的颜色类名（如 `bg-white`）应该移除，改为在颜色主题中定义

3. **修改颜色**时，确保浅色和深色模式都更新
   - 保持视觉一致性
   - 如果只修改一处，另一处可能显示不正确

## 实际示例

### 示例 1：修改卡片内边距

**场景：** 要将所有卡片的内边距从 `p-6` 改为 `p-8`

**步骤：**
1. 打开 `lib/ui-styles-base.ts`
2. 找到 `baseCardStyles` 中的所有 `p-6`，改为 `p-8`
3. 保存文件

**结果：**
- ✅ 浅色模式的所有卡片内边距自动更新为 `p-8`
- ✅ 深色模式的所有卡片内边距自动更新为 `p-8`
- ✅ 只需修改一处，两套主题同步更新

### 示例 2：修改按钮颜色

**场景：** 要将浅色模式的主要按钮颜色从 `indigo-600` 改为 `indigo-700`

**步骤：**
1. 打开 `lib/ui-theme-colors-light.ts`
2. 找到 `button.primary.bg`，将 `bg-indigo-600` 改为 `bg-indigo-700`
3. 保存文件

**结果：**
- ✅ 浅色模式的主要按钮颜色更新
- ✅ 深色模式不受影响（保持 `indigo-500`）
- ✅ 布局、大小、动画等其他样式不受影响

### 示例 3：修改动画效果

**场景：** 要将卡片的悬停提升效果从 `-translate-y-1` 改为 `-translate-y-2`

**步骤：**
1. 打开 `lib/ui-styles-base.ts`
2. 找到 `baseCardStyles.hover` 中的 `hover:-translate-y-1`，改为 `hover:-translate-y-2`
3. 保存文件

**结果：**
- ✅ 浅色和深色模式的所有卡片悬停效果同步更新
- ✅ 颜色不受影响