xiaozhi/jk-rag-platform/DESIGN_SPECIFICATION.md

🏗️ 建科小智设计规范 (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)

用于承载主要内容的顶层容器。

.page-container {
    padding: $spacing-4 $spacing-6;  // 16px / 24px
    min-height: calc(100vh - $header-height);
    background: $bg-primary;
}

2. 内容区块 (Content Section)

用于页面内的逻辑分组。

.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 引入变量。

  @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 的解耦？