MianyVue/CSS_THEME_GUIDE.md

# CSS主题系统使用指南

## 概述

本项目采用统一的CSS主题系统，通过CSS变量实现一致的视觉效果和便捷的主题管理。所有颜色、尺寸、间距等样式值都通过预定义的CSS变量进行管理，确保代码的一致性和可维护性。

## 🎯 核心原则

### ✅ 正确做法
```css
/* 使用CSS变量 */
padding: var(--spacing-md);
font-size: var(--font-size-base);
border-radius: var(--size-border-radius);
color: var(--color-text-primary);
```

### ❌ 禁止做法
```css
/* 硬编码值 - 严禁使用 */
padding: 12px;
font-size: 14px;
border-radius: 8px;
color: #ffffff;
```

## 🎨 变量分类系统

### 1. 尺寸变量 (`--size-*`)
```css
/* 常用固定尺寸 */
--size-1: 1px;     /* 边框、分割线 */
--size-2: 2px;     /* 小装饰 */
--size-4: 4px;     /* 小圆角 */
--size-6: 6px;     /* 按钮圆角 */
--size-8: 8px;     /* 标准圆角 */
--size-12: 12px;   /* 卡片圆角 */
--size-16: 16px;   /* 图标尺寸 */
--size-24: 24px;   /* 大图标 */
--size-32: 32px;   /* 按钮高度 */
--size-40: 40px;   /* 操作按钮 */
--size-48: 48px;   /* 头像尺寸 */
--size-60: 60px;   /* 头部高度 */
```

### 2. 间距变量 (`--spacing-*`)
```css
/* 间距系统 */
--spacing-xxs: 2px;  /* 微小间距 */
--spacing-xs: 4px;   /* 极小间距 */
--spacing-sm: 8px;   /* 小间距 */
--spacing-md: 12px;  /* 中等间距 */
--spacing-lg: 16px;  /* 大间距 */
--spacing-xl: 20px;  /* 超大间距 */
--spacing-2xl: 24px; /* 卡片间距 */
--spacing-3xl: 32px; /* 区域间距 */
--spacing-4xl: 40px; /* 大区域间距 */
--spacing-5xl: 48px; /* 页面间距 */
--spacing-6xl: 60px; /* 头部间距 */
```

### 3. 字体变量 (`--font-size-*`)
```css
/* 字体大小系统 */
--font-size-xs: 12px;    /* 辅助文字 */
--font-size-sm: 13px;    /* 小文字 */
--font-size-base: 14px;  /* 基础文字 */
--font-size-md: 15px;    /* 中等文字 */
--font-size-lg: 16px;    /* 大文字 */
--font-size-xl: 18px;    /* 标题文字 */
--font-size-2xl: 20px;   /* 副标题 */
--font-size-3xl: 24px;   /* 主标题 */
```

### 4. 图标变量 (`--icon-size-*`)
```css
/* 图标尺寸系统 */
--icon-size-xs: 12px;  /* 状态图标 */
--icon-size-sm: 14px;  /* 小图标 */
--icon-size-md: 16px;  /* 标准图标 */
--icon-size-lg: 20px;  /* 大图标 */
--icon-size-xl: 24px;  /* 超大图标 */
--icon-size-2xl: 28px; /* 装饰图标 */
--icon-size-3xl: 32px; /* 特大图标 */
```

### 5. 颜色变量 (`--color-*`)
```css
/* 文字颜色 */
--color-text-primary: /* 主要文字 */
--color-text-secondary: /* 次要文字 */
--color-text-tertiary: /* 辅助文字 */
--color-text-error: /* 错误文字 */

/* 背景颜色 */
--color-bg-primary: /* 主背景 */
--color-bg-secondary: /* 次背景 */
--color-bg-card: /* 卡片背景 */
--color-bg-hover: /* 悬停背景 */

/* 边框颜色 */
--color-border-primary: /* 主边框 */
--color-border-secondary: /* 次边框 */
--color-border-active: /* 激活边框 */
```

### 6. CAD软件主题色
```css
/* Creo主题 */
--color-primary: /* 蓝色主题 */

/* PDMS主题 */
--color-pdms: /* 橙色主题 */
--color-pdms-gradient: /* 橙色渐变 */

/* Revit主题 */
--color-revit: /* 绿色主题 */
--color-revit-gradient: /* 绿色渐变 */

/* 复杂度分析主题 */
--color-complexity: /* 分析橙色 */
--color-complexity-high: /* 高复杂度红色 */
--color-complexity-low: /* 低复杂度绿色 */
```

## 🛠️ 使用示例

### 按钮样式
```css
.custom-button {
  padding: var(--spacing-md) var(--spacing-lg);
  font-size: var(--font-size-base);
  border-radius: var(--size-border-radius-button);
  border: var(--border-width-thin) solid var(--color-border-primary);
  gap: var(--spacing-sm);
}
```

### 卡片样式
```css
.card-component {
  padding: var(--spacing-xl);
  margin-bottom: var(--spacing-2xl);
  border-radius: var(--size-border-radius-card);
  border: var(--border-width-thin) solid var(--color-border-primary);
  background: var(--color-bg-card);
}
```

### 文字样式
```css
.title {
  font-size: var(--font-size-2xl);
  color: var(--color-text-primary);
  margin-bottom: var(--spacing-lg);
}

.subtitle {
  font-size: var(--font-size-base);
  color: var(--color-text-secondary);
}
```

### 响应式断点
```css
@media (max-width: var(--breakpoint-tablet)) {
  .responsive-element {
    padding: var(--spacing-sm);
    font-size: var(--font-size-sm);
  }
}
```

## 🔧 变量映射表

### 常用硬编码值对应的变量

| 硬编码值 | 对应变量 | 用途 |
|---------|---------|------|
| `1px` | `var(--size-1)` | 边框 |
| `2px` | `var(--size-2)` | 小装饰 |
| `4px` | `var(--spacing-xs)` | 微间距 |
| `6px` | `var(--size-6)` | 按钮圆角 |
| `8px` | `var(--spacing-sm)` | 小间距 |
| `10px` | `var(--size-10)` | 内边距 |
| `12px` | `var(--spacing-md)` | 标准间距 |
| `14px` | `var(--font-size-base)` | 基础字体 |
| `16px` | `var(--spacing-lg)` | 大间距 |
| `20px` | `var(--spacing-xl)` | 超大间距 |
| `24px` | `var(--spacing-2xl)` | 卡片间距 |
| `768px` | `var(--breakpoint-tablet)` | 平板断点 |

## 📋 开发检查清单

### 开发前检查
- [ ] 确认所需尺寸在变量系统中是否已存在
- [ ] 如需新尺寸，先在`theme.css`中添加变量
- [ ] 确认变量命名符合语义化原则

### 代码审查检查
- [ ] 没有使用任何硬编码的`px`、`rem`、`em`值
- [ ] 所有颜色都使用CSS变量
- [ ] 响应式断点使用变量
- [ ] 间距、字体、圆角都使用对应变量

### 测试检查
- [ ] 组件在不同主题下显示正常
- [ ] 响应式布局工作正常
- [ ] 所有交互状态（hover、active、focus）正常

## 🚨 常见问题

### Q: 需要的尺寸在变量中找不到怎么办？
A: 在`src/assets/styles/theme.css`中添加新变量，命名要语义化。

### Q: 特殊组件需要特定尺寸怎么办？
A: 在theme.css中的"组件特定"区域添加专用变量。

### Q: 如何确保主题切换正常？
A: 所有样式都使用CSS变量，确保亮暗主题切换时自动更新。

### Q: 媒体查询也要使用变量吗？
A: 是的，使用`var(--breakpoint-*)`系列变量。

## 🎯 最佳实践

1. **语义化命名**：变量名要明确表达用途
2. **分层设计**：区分基础变量和语义变量
3. **一致性原则**：同类元素使用相同变量
4. **可维护性**：修改主题只需调整变量文件
5. **文档更新**：新增变量要及时更新文档

## 🔄 持续改进

- 定期审查未使用的变量
- 根据设计需求扩展变量系统
- 收集开发反馈，优化变量分类
- 保持变量系统的简洁性和易用性

---

**记住：统一的主题系统是项目可维护性的关键！严格遵循变量使用规范。**