# PicStack 设计规范

## 🎨 视觉设计系统

### 配色方案

#### 主色系
\`\`\`css
主色 (Primary): #1677FF        /* 清爽科技蓝 */
品牌强调色 (Brand): #0958D9     /* 深蓝强调 */
辅助色 (Secondary): #52C41A     /* 成功绿 */
\`\`\`

#### 背景层级
\`\`\`css
Base Background: #F5F7FA        /* 最外层背景 */
Surface Background: #FFFFFF     /* 容器背景 */
Section Background: #FAFBFC     /* 区块背景 */
\`\`\`

#### 文本色系
\`\`\`css
主文本: #262626     /* 深灰黑 */
副文本: #595959     /* 中灰 */
弱文本: #8C8C8C     /* 浅灰 */
禁用文本: #BFBFBF  /* 超浅灰 */
\`\`\`

#### 功能色系
\`\`\`css
成功: #52C41A      /* 绿色 - 上传成功 */
警告: #FAAD14      /* 橙色 - 存储空间不足 */
错误: #FF4D4F      /* 红色 - 上传失败 */
信息: #1677FF      /* 蓝色 - 提示信息 */
链接: #1677FF      /* 蓝色链接 */
\`\`\`

### 字体体系

#### 字体族
\`\`\`css
中文: 'PingFang SC', 'Microsoft YaHei', sans-serif
英文: 'Inter', 'SF Pro Display', -apple-system, sans-serif
等宽: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace
\`\`\`

#### 字号等级
\`\`\`css
XS:   12px  /* 辅助文本 */
SM:   14px  /* 常规文本 */
BASE: 16px  /* 基础文本 */
LG:   18px  /* 小标题 */
XL:   24px  /* 标题 */
2XL:  32px  /* 大标题 */
3XL:  48px  /* Hero 标题 */
\`\`\`

#### 字重
\`\`\`css
Normal:    400
Medium:    500
Semibold:  600
Bold:      700
\`\`\`

### 间距系统（8px 基准）

\`\`\`css
XS:  4px
SM:  8px
MD:  16px
LG:  24px
XL:  32px
2XL: 48px
3XL: 64px
\`\`\`

### 圆角

\`\`\`css
SM:   4px   /* 按钮、输入框 */
MD:   8px   /* 卡片 */
LG:   12px  /* 大卡片 */
XL:   16px  /* Hero 区块 */
FULL: 50%   /* 头像 */
\`\`\`

### 阴影系统

\`\`\`css
卡片阴影: 0 2px 8px rgba(0, 0, 0, 0.08)
悬浮阴影: 0 4px 16px rgba(0, 0, 0, 0.12)
弹窗阴影: 0 8px 32px rgba(0, 0, 0, 0.16)
\`\`\`

## 🧩 组件规范

### 卡片组件
- 统一使用 `borderRadius: 12px`
- 默认阴影: `0 2px 8px rgba(0, 0, 0, 0.08)`
- Hover 状态: 上移 4px + 阴影加深

### 按钮组件
- 主按钮: 蓝色背景 + 白色文字
- 次要按钮: 白色背景 + 蓝色边框
- 危险按钮: 红色背景/文字
- 最小高度: 36px (默认) / 42px (大) / 28px (小)

### 输入框
- 默认高度: 36px
- 圆角: 4px
- Focus 状态: 蓝色边框
- Hover 状态: 浅蓝边框

## 🎬 动效规范

### 过渡时长
\`\`\`css
Fast:  150ms   /* 快速交互 */
Base:  300ms   /* 标准过渡 */
Slow:  500ms   /* 复杂动画 */
\`\`\`

### 缓动函数
\`\`\`css
标准: cubic-bezier(0.4, 0, 0.2, 1)
进入: cubic-bezier(0, 0, 0.2, 1)
退出: cubic-bezier(0.4, 0, 1, 1)
\`\`\`

### 常用动效
- 卡片 Hover: `translateY(-4px) + 阴影提升`
- 按钮 Hover: `scale(1.02)`
- 图片加载: `opacity 0 → 1 (300ms)`
- 页面切换: `fadeIn animation (500ms)`

## 📐 布局规范

### 网格系统
- 基于 Ant Design 24 列栅格
- Gutter: 16px (默认) / 24px (大屏)

### 响应式断点
\`\`\`css
xs: < 576px    /* 手机 */
sm: ≥ 576px    /* 平板竖屏 */
md: ≥ 768px    /* 平板横屏 */
lg: ≥ 992px    /* 笔记本 */
xl: ≥ 1200px   /* 桌面 */
xxl: ≥ 1600px  /* 大屏 */
\`\`\`

### 页面布局
\`\`\`
Header (64px 固定高度)
├─ Sidebar (220px 固定宽度)
└─ Content (自适应)
   └─ Footer (70px 固定高度)
\`\`\`

## 🖼️ 图片规范

### 图片网格
- 默认: `grid-template-columns: repeat(auto-fill, minmax(240px, 1fr))`
- 移动端: `minmax(160px, 1fr)`
- Gap: 16px (桌面) / 12px (移动)

### 缩略图
- 尺寸: 240x240px
- 圆角: 8px
- 加载骨架屏: 灰色渐变动画

## ♿ 可访问性

### 颜色对比度
- 正文文字: 至少 4.5:1
- 大号文字: 至少 3:1
- 交互元素: 至少 3:1

### 键盘导航
- 所有交互元素支持 Tab 导航
- Focus 状态明显可见
- 支持 Enter/Space 触发

### ARIA 标签
- 为图片添加 alt 属性
- 为图标按钮添加 aria-label
- 为表单控件添加 aria-describedby

## 📝 代码规范

### 命名约定
- 组件: PascalCase (如 `ImageCard`)
- 文件名: PascalCase (如 `ImageCard.tsx`)
- 变量/函数: camelCase (如 `handleUpload`)
- 常量: UPPER_SNAKE_CASE (如 `MAX_FILE_SIZE`)
- CSS 类: kebab-case (如 `image-grid`)

### 文件组织
\`\`\`
Component/
├── index.tsx        # 主组件
├── styles.css       # 样式文件(可选)
├── types.ts         # 类型定义(可选)
└── README.md        # 组件文档(可选)
\`\`\`

### 注释规范
\`\`\`typescript
/**
 * 组件功能简述
 * @param props - 参数说明
 * @returns JSX 元素
 */
\`\`\`

## 🎯 最佳实践

### 性能优化
- 使用 React.memo 避免不必要的重渲染
- 图片懒加载 (Intersection Observer)
- 虚拟滚动处理大列表
- 路由懒加载 (React.lazy + Suspense)

### 用户体验
- 加载状态使用骨架屏
- 错误状态提供重试选项
- 成功操作显示提示消息
- 危险操作二次确认

### 状态管理
- 全局状态使用 Zustand
- 表单状态使用本地 state
- 服务端状态使用 React Query (未来)

---

**持续更新中...**