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-* 的颜色部分）

示例：

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 类名
• 浅色模式下的颜色值

示例：

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 类名
• 深色模式下的颜色值

示例：

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

示例：

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：

// 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

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

// 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 类型检查确保配置正确

使用方式

组件中的使用方式不变：

'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. 保存文件

结果：

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