# 🏗️ 建科小智设计规范 (Design Specification)

**版本**: v4.0
**技术栈**: React 18 + TypeScript + Vite + Ant Design + SCSS + Zustand

---

## 🎨 样式系统 (Styling System)

### 1. 色彩系统 (Color System - v3.2 企业品牌色)

#### **主色调 (Brand Colors)**
| 变量 | 值 | 用途 |
|------|------|------|
| `$primary-color` | `#005D80` | 企业主色 (WCAG AAA) |
| `$primary-light` | `#007A99` | 悬停/强调 |
| `$primary-dark` | `#004060` | 点击/激活 |
| `$primary-gradient-start` | `#00A0CA` | 渐变起点 |
| `$primary-gradient-end` | `#005D80` | 渐变终点 |

#### **功能性颜色 (Functional Colors)**
| 变量 | 值 | 用途 |
|------|------|------|
| `$success-color` | `#059669` | 成功状态 |
| `$warning-color` | `#F59E0B` | 警告状态 |
| `$error-color` | `#DC2626` | 错误状态 |
| `$info-color` | `#00A0C7` | 信息提示 |

#### **文字颜色 (Text Colors)**
| 变量 | 值 | 用途 |
|------|------|------|
| `$text-primary` | `#1F2937` | 主文字内容 |
| `$text-secondary` | `#6B7280` | 次要/辅助文字 |
| `$text-hint` | `#9CA3AF` | 提示/占位符文字 |
| `$text-disabled` | `#D1D5DB` | 禁用状态文字 |

#### **背景颜色 (Background Colors)**
| 变量 | 值 | 用途 |
|------|------|------|
| `$bg-primary` | `#F9FAFB` | 页面主背景 |
| `$bg-secondary` | `#FFFFFF` | 卡片/容器次背景 |
| `$bg-tertiary` | `#F3F4F6` | 第三级背景/分割线背景 |
| `$bg-hover` | `#F9FAFB` | 悬停态背景 |

---

### 2. 间距系统 (Spacing System - 4px 基准)

| 变量 | 值 | 用途 |
|------|------|------|
| `$spacing-1` | `4px` | 最小间距 |
| `$spacing-2` | `8px` | 小间距 |
| `$spacing-3` | `12px` | 中等间距 |
| `$spacing-4` | `16px` | 标准间距 (Standard) |
| `$spacing-5` | `20px` | 大间距 |
| `$spacing-6` | `24px` | 加大间距 |
| `$spacing-8` | `32px` | 特大间距 |
| `$spacing-10` | `40px` | 页面级间距 |

**快捷别名**:
*   `$spacing-xs`: `4px`
*   `$spacing-sm`: `8px`
*   `$spacing-md`: `12px`
*   `$spacing-lg`: `16px`
*   `$spacing-xl`: `24px`
*   `$spacing-2xl`: `32px`

---

### 3. 圆角系统 (Border Radius)

| 变量 | 值 | 用途 |
|------|------|------|
| `$radius-sm` | `4px` | 标签、徽章 |
| `$radius-md` | `6px` | 小按钮、输入框 |
| `$radius-lg` | `8px` | 标准按钮、卡片、容器 |
| `$radius-xl` | `12px` | 大尺寸卡片、模态框 |
| `$radius-2xl` | `16px` | 特大尺寸容器 |
| `$radius-full` | `9999px` | 圆形元素 (Avatar/Pill) |

---

## 📐 布局规范 (Layout Specification)

### 1. 页面容器 (Page Container)
用于承载主要内容的顶层容器。
```scss
.page-container {
    padding: $spacing-4 $spacing-6;  // 16px / 24px
    min-height: calc(100vh - $header-height);
    background: $bg-primary;
}
```

### 2. 内容区块 (Content Section)
用于页面内的逻辑分组。
```scss
.content-section {
    margin-bottom: $spacing-4;  // 16px
    padding: $spacing-3;        // 12px
    background: $bg-secondary;
    border-radius: $radius-lg;
}
```

### 3. 响应式断点 (Responsive Breakpoints)
| 变量 | 值 | 说明 |
|------|------|------|
| `$screen-sm` | `640px` | 手机横屏 |
| `$screen-md` | `768px` | 平板竖屏 |
| `$screen-lg` | `1024px` | 平板横屏 |
| `$screen-xl` | `1280px` | 桌面小屏 |
| `$screen-2xl` | `1536px` | 桌面大屏 |

---

## 🛠️ 开发规范 (Development Rules)

### 1. SCSS 使用准则
*   **强制导入**: 所有 `.scss` 文件必须在第一行使用 `@use` 引入变量。
    ```scss
    @use '@/styles/variables.scss' as *;
    ```
*   **禁止硬编码**: 禁止直接书写颜色值（如 `#FFFFFF`）或像素值（如 `16px`），必须引用对应的 `$variable`。

### 2. 组件开发原则 (Type B Strategy)
*   **解耦逻辑**: 复杂组件必须拆分为 **Smart Container** (处理 Store/API) 和 **Dumb View** (纯 UI 展示)。
*   **Props 驱动**: View 层不应直接访问 `useChatStore` 等全局状态，所有数据和回调必须通过 Props 注入。

### 3. 组件 Checklist
- [ ] 是否使用了 CSS Modules (`.module.scss`)？
- [ ] 是否引用了项目定义的变量而非硬编码值？
- [ ] 是否遵循了圆角与间距的阶梯规范？
- [ ] (针对复杂组件) 是否实现了 Container/View 的解耦？