# 全局样式变量使用指南

**版本**: v3.0
**创建时间**: 2024-01-19
**项目**: jkec-xiaozhi-v2/jk-rag-platform

---

## 📁 文件位置

```
src/styles/
├── variables.scss    # SCSS/CSS 变量（统一文件）
└── global.scss       # 全局样式入口
```

---

## 🚀 快速开始

### 方式 1: SCSS 变量（推荐）

**在 SCSS 文件顶部导入**:
```scss
@import '@/styles/variables.scss';

// 使用变量
.my-component {
    color: $text-primary;
    padding: $spacing-4;
    border-radius: $radius-lg;
}
```

### 方式 2: CSS 变量

**在 SCSS/CSS 文件中使用**:
```scss
.my-component {
    color: var(--text-primary);
    padding: var(--spacing-4);
    border-radius: var(--radius-lg);
}
```

**在 JS/TS 中使用**:
```typescript
const primaryColor = getComputedStyle(
    document.documentElement
).getPropertyValue('--color-primary');
```

> **注意**: CSS 变量已定义在 `variables.scss` 的 `:root {}` 中，无需单独导入 CSS 文件。

---

## 📋 变量清单

### 色彩系统

```scss
// 主色调
$primary-color: #1D4ED8;
$primary-light: #3B82F6;
$primary-dark: #1E40AF;

// 辅助色
$success-color: #10B981;
$warning-color: #F59E0B;
$error-color: #EF4444;
$info-color: #3B82F6;

// 中性色
$text-primary: #1F2937;
$text-secondary: #6B7280;
$text-hint: #9CA3AF;
$bg-primary: #F9FAFB;
$bg-secondary: #FFFFFF;
$border-base: #E5E7EB;
```

### 间距系统

```scss
// 4px 基准
$spacing-1: 4px;
$spacing-2: 8px;
$spacing-3: 12px;
$spacing-4: 16px;
$spacing-6: 24px;
$spacing-8: 32px;
```

### 圆角系统

```scss
$radius-sm: 4px;
$radius-md: 6px;
$radius-lg: 8px;
$radius-xl: 12px;
$radius-full: 9999px;
```

### 阴影系统

```scss
$shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
$shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);
$shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);
$shadow-glow: 0 0 20px rgba(59, 130, 246, 0.3);
```

### 字体系统

```scss
// 字体大小
$font-xs: 9px;
$font-sm: 12px;
$font-base: 13px;
$font-lg: 15px;
$font-xl: 16px;

// 字重
$font-weight-medium: 500;
$font-weight-semibold: 600;
```

### 动画系统

```scss
// 时长
$animation-fast: 0.1s;
$animation-base: 0.2s;
$animation-slow: 0.3s;

// 缓动
$easing-default: cubic-bezier(0.4, 0, 0.2, 1);

// 快捷过渡
$transition-base: all $animation-base $easing-default;
```

---

## 🔧 旧代码迁移指南

### 步骤 1: 导入变量文件

**在文件顶部添加**:
```scss
@import '@/styles/variables.scss';
```

### 步骤 2: 替换硬编码值

#### 色彩替换

```scss
// ❌ 旧代码 (LESS)
color: @primary-color;

// ✅ 新代码 (SCSS)
color: $text-primary;
```

#### 间距替换

```scss
// ❌ 旧代码 (LESS)
padding: @spacing-4;

// ✅ 新代码 (SCSS)
padding: $spacing-4;
```

### 步骤 3: 使用 Mixins（可选）

```scss
// 文字截断
.my-text {
    @include text-truncate();
}

// 多行文字截断
.my-description {
    @include text-clamp(2);  // 最多 2 行
}

// 居中
.my-center {
    @include center-flex();
}

// 卡片阴影
.my-card {
    @include shadow-card();
}
```

---

## 📝 迁移示例

### 示例 1: 按钮组件

**迁移前 (LESS)**:
```less
.btn {
    padding: @spacing-2 @spacing-4;
    background: @primary-color;
    color: #FFFFFF;
    border-radius: @radius-md;
    font-size: @font-md;
    font-weight: @font-weight-medium;
    transition: @transition-base;

    &:hover {
        background: @primary-light;
        transform: translateY(-@spacing-1);
        box-shadow: @shadow-md;
    }
}
```

**迁移后 (SCSS)**:
```scss
@import '@/styles/variables.scss';

.btn {
    padding: $spacing-2 $spacing-4;
    background: $primary-color;
    color: #FFFFFF;
    border-radius: $radius-md;
    font-size: $font-md;
    font-weight: $font-weight-medium;
    transition: $transition-base;

    &:hover {
        background: $primary-light;
        transform: translateY(-$spacing-1);
        box-shadow: $shadow-md;
    }
}
```

### 示例 2: 卡片组件

**迁移前 (LESS)**:
```less
.card {
    padding: @spacing-5;
    background: @bg-secondary;
    border-radius: @radius-2xl;
    border: 1px solid @border-light;

    &:hover {
        box-shadow: @shadow-xl;
    }
}
```

**迁移后 (SCSS)**:
```scss
@import '@/styles/variables.scss';

.card {
    padding: $spacing-5;
    background: $bg-secondary;
    border-radius: $radius-2xl;
    border: 1px solid $border-light;

    &:hover {
        box-shadow: $shadow-xl;
    }
}
```

---

## 🎯 最佳实践

### 1. 始终使用变量

```scss
// ✅ 好
color: $text-primary;

// ❌ 不好
color: #1F2937;
```

### 2. 使用语义化命名

```scss
// ✅ 好
background: $bg-active;

// ❌ 不好
background: rgba(29, 78, 216, 0.1);
```

### 3. 使用间距系统

```scss
// ✅ 好
margin: $spacing-4;

// ❌ 不好
margin: 16px;
```

### 4. 使用快捷 Mixins

```scss
// ✅ 好
@include text-truncate();

// ❌ 不好
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
```

---

## 📊 迁移检查清单

### 文件级别

- [ ] 导入 `variables.scss`
- [ ] 移除硬编码颜色
- [ ] 移除硬编码间距
- [ ] 移除硬编码圆角
- [ ] 移除硬编码字体
- [ ] 移除硬编码阴影

### 组件级别

- [ ] 按钮使用 `$primary-color`
- [ ] 卡片使用 `$bg-secondary`
- [ ] 文字使用 `$text-primary` / `$text-secondary`
- [ ] 边框使用 `$border-base`
- [ ] 间距使用 `$spacing-*`
- [ ] 圆角使用 `$radius-*`

---

## 🔍 常见问题

### Q1: 变量不生效？

**检查**:
1. 是否正确导入文件
2. 导入路径是否正确
3. 是否在 SCSS 文件中使用

**解决**:
```scss
// 确保在文件顶部导入
@import '@/styles/variables.scss';
```

### Q2: 如何覆盖变量？

**方法**:
```scss
// 在导入后覆盖
@import '@/styles/variables.scss';
$primary-color: #FF0000;  // 覆盖主色
```

### Q3: CSS 变量和 SCSS 变量选哪个？

**推荐**:
- SCSS 变量：编译时优化，IDE 支持好 ✅
- CSS 变量：运行时动态修改，JS 可访问

**建议**: 优先使用 SCSS 变量，需要 JS 访问时使用 CSS 变量。

---

## 📄 相关文档

1. `建科小智设计规范_v3.md` - 完整设计规范
2. `variables.scss` - SCSS/CSS 变量文件
3. `global.scss` - 全局样式

---

**文档维护**: AI Assistant
**最后更新**: 2026-03-28
**版本**: v4.0 (SCSS)