Initial commit

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-03 10:10:11 +08:00
commit 14289beb66
45 changed files with 15479 additions and 0 deletions
--- a/docs/UI设计系统.md
+++ b/docs/UI设计系统.md
@@ -0,0 +1,566 @@
+# SFTP文件管理系统 - UI设计系统
+
+## 设计理念
+
+SFTP文件管理系统采用**现代简约、专业高效**的设计理念，注重用户体验和操作效率。设计系统遵循以下核心原则：
+
+- **清晰性**：界面层次分明，信息一目了然
+- **一致性**：统一的视觉语言和交互模式
+- **效率性**：减少操作步骤，提升工作效率
+- **可访问性**：符合WCAG 2.1 AA标准，支持键盘导航
+
+---
+
+## 1. 颜色系统
+
+### 1.1 主色调
+
+| 颜色名称 | Hex值 | RGB值 | 用途 |
+|---------|-------|-------|------|
+| 主色（Primary） | `#0d6efd` | rgb(13, 110, 253) | 主要操作按钮、链接、选中状态 |
+| 成功（Success） | `#198754` | rgb(25, 135, 84) | 成功提示、连接状态 |
+| 警告（Warning） | `#ffc107` | rgb(255, 193, 7) | 警告信息、加载状态 |
+| 危险（Danger） | `#dc3545` | rgb(220, 53, 69) | 删除操作、错误提示 |
+| 信息（Info） | `#0dcaf0` | rgb(13, 202, 240) | 信息提示 |
+
+### 1.2 中性色
+
+| 颜色名称 | Hex值 | 用途 |
+|---------|-------|------|
+| 深灰（Dark） | `#212529` | 导航栏背景、深色文字 |
+| 中灰（Gray-600） | `#6c757d` | 次要文字、边框 |
+| 浅灰（Gray-200） | `#e9ecef` | 工具栏背景、分割线 |
+| 极浅灰（Gray-100） | `#f8f9fa` | 面板头部背景 |
+| 白色（White） | `#ffffff` | 主背景、卡片背景 |
+
+### 1.3 状态颜色
+
+| 状态 | 颜色 | 用途 |
+|------|------|------|
+| 连接成功 | `#198754` | SFTP连接状态指示器 |
+| 连接失败 | `#dc3545` | 连接错误状态 |
+| 连接中 | `#ffc107` | 连接进行中状态 |
+| 选中状态 | `#0d6efd` | 文件列表选中项背景 |
+| 悬停状态 | `#f8f9fa` | 文件项悬停背景 |
+
+### 1.4 对比度要求
+
+- **正文文字**：与背景对比度 ≥ 4.5:1
+- **大号文字**（18px+）：与背景对比度 ≥ 3:1
+- **交互元素**：与背景对比度 ≥ 3:1
+
+---
+
+## 2. 字体系统
+
+### 2.1 字体族
+
+```css
+font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 
+             'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 
+             'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
+```
+
+**说明**：
+- 优先使用系统字体，确保跨平台一致性
+- 支持中英文混排
+- 无衬线字体，提升可读性
+
+### 2.2 字体大小
+
+| 元素 | 大小 | 行高 | 用途 |
+|------|------|------|------|
+| H1 标题 | 32px (2rem) | 1.2 | 页面主标题 |
+| H2 标题 | 24px (1.5rem) | 1.3 | 模块标题 |
+| H3 标题 | 20px (1.25rem) | 1.4 | 子模块标题 |
+| 正文 | 14px (0.875rem) | 1.5 | 正文内容 |
+| 小号文字 | 12px (0.75rem) | 1.5 | 辅助信息、文件大小、日期 |
+| 按钮文字 | 14px (0.875rem) | 1.5 | 按钮标签 |
+
+### 2.3 字重
+
+| 字重 | 值 | 用途 |
+|------|-----|------|
+| 细体 | 300 | 次要信息 |
+| 常规 | 400 | 正文内容 |
+| 中等 | 500 | 强调文字 |
+| 粗体 | 600 | 标题、重要信息 |
+| 特粗 | 700 | 导航栏品牌 |
+
+---
+
+## 3. 间距系统
+
+### 3.1 基础间距单位
+
+使用 **8px** 作为基础间距单位，所有间距应为 8px 的倍数。
+
+| 间距名称 | 值 | 用途 |
+|---------|-----|------|
+| xs | 4px (0.25rem) | 图标与文字间距 |
+| sm | 8px (0.5rem) | 小元素间距 |
+| md | 16px (1rem) | 标准元素间距 |
+| lg | 24px (1.5rem) | 大元素间距 |
+| xl | 32px (2rem) | 区块间距 |
+| xxl | 48px (3rem) | 大区块间距 |
+
+### 3.2 组件内边距
+
+| 组件 | 内边距 | 说明 |
+|------|--------|------|
+| 导航栏 | 8px 16px | 垂直 8px，水平 16px |
+| 工具栏 | 8px 16px | 垂直 8px，水平 16px |
+| 面板头部 | 8px | 统一 8px |
+| 文件项 | 8px 12px | 垂直 8px，水平 12px |
+| 按钮 | 6px 12px | 小按钮 |
+| 按钮（大） | 10px 20px | 主要按钮 |
+
+---
+
+## 4. 组件规范
+
+### 4.1 导航栏
+
+```css
+.navbar {
+  background-color: #212529;
+  color: #ffffff;
+  padding: 8px 16px;
+  height: 48px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.navbar-brand {
+  font-size: 18px;
+  font-weight: 600;
+  color: #ffffff;
+}
+```
+
+**规范**：
+- 固定高度：48px
+- 深色背景：`#212529`
+- 白色文字
+- 品牌名称左对齐，操作按钮右对齐
+
+### 4.2 工具栏
+
+```css
+.toolbar {
+  background-color: #e9ecef;
+  border-bottom: 1px solid #dee2e6;
+  padding: 8px 16px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+```
+
+**规范**：
+- 浅灰背景：`#e9ecef`
+- 按钮组间距：8px
+- 按钮大小：`btn-sm`（小按钮）
+- 支持响应式换行
+
+### 4.3 双面板
+
+```css
+.panels-container {
+  display: flex;
+  flex: 1;
+  overflow: hidden;
+}
+
+.panel {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  border-right: 1px solid #dee2e6;
+  background-color: #ffffff;
+}
+
+.panel:last-child {
+  border-right: none;
+}
+```
+
+**规范**：
+- 等宽分布：`flex: 1`
+- 面板间分割线：1px 实线
+- 背景色：白色
+- 支持垂直滚动
+
+### 4.4 文件列表项
+
+```css
+.file-item {
+  padding: 8px 12px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  border-bottom: 1px solid #f0f0f0;
+  transition: background-color 0.15s ease;
+  user-select: none;
+}
+
+.file-item:hover {
+  background-color: #f8f9fa;
+}
+
+.file-item.selected {
+  background-color: #0d6efd;
+  color: #ffffff;
+}
+```
+
+**规范**：
+- 最小高度：44px（触摸目标）
+- 悬停效果：浅灰背景
+- 选中状态：主色背景 + 白色文字
+- 过渡动画：150ms
+
+### 4.5 按钮
+
+```css
+.btn-primary {
+  background-color: #0d6efd;
+  border-color: #0d6efd;
+  color: #ffffff;
+  padding: 6px 12px;
+  border-radius: 4px;
+  font-size: 14px;
+  transition: all 0.15s ease;
+}
+
+.btn-primary:hover {
+  background-color: #0b5ed7;
+  border-color: #0a58ca;
+}
+
+.btn-primary:focus {
+  box-shadow: 0 0 0 0.25rem rgba(13, 110, 253, 0.25);
+}
+```
+
+**规范**：
+- 圆角：4px
+- 过渡动画：150ms
+- 焦点状态：可见的焦点环
+- 禁用状态：降低透明度至 0.65
+
+### 4.6 模态框
+
+```css
+.modal-content {
+  border-radius: 8px;
+  border: none;
+  box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
+}
+
+.modal-header {
+  border-bottom: 1px solid #dee2e6;
+  padding: 16px;
+}
+
+.modal-body {
+  padding: 16px;
+}
+
+.modal-footer {
+  border-top: 1px solid #dee2e6;
+  padding: 12px 16px;
+}
+```
+
+**规范**：
+- 圆角：8px
+- 阴影：中等深度
+- 内边距：16px
+- 头部/底部边框：1px 浅灰
+
+---
+
+## 5. 交互规范
+
+### 5.1 悬停效果
+
+- **文件项**：背景色变化（`#f8f9fa`）
+- **按钮**：颜色加深 + 轻微阴影
+- **链接**：下划线显示
+- **过渡时间**：150ms
+
+### 5.2 点击反馈
+
+- **按钮**：按下时轻微缩放（scale: 0.98）
+- **文件项**：选中状态立即显示
+- **禁用状态**：不响应点击
+
+### 5.3 加载状态
+
+```css
+.loading {
+  opacity: 0.6;
+  pointer-events: none;
+  position: relative;
+}
+
+.loading::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 20px;
+  height: 20px;
+  margin: -10px 0 0 -10px;
+  border: 2px solid #0d6efd;
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: spin 0.6s linear infinite;
+}
+```
+
+### 5.4 键盘导航
+
+- **Tab键**：按顺序聚焦可交互元素
+- **Enter键**：激活按钮、打开文件/目录
+- **Delete键**：删除选中文件
+- **F2键**：重命名文件
+- **F5键**：刷新文件列表
+- **Esc键**：关闭模态框、取消选择
+
+### 5.5 拖拽操作
+
+```css
+.file-item.dragging {
+  opacity: 0.5;
+}
+
+.file-list.drag-over {
+  background-color: #e7f3ff;
+  border: 2px dashed #0d6efd;
+}
+```
+
+---
+
+## 6. 响应式设计
+
+### 6.1 断点
+
+| 设备类型 | 宽度范围 | 布局调整 |
+|---------|---------|---------|
+| 移动端 | < 768px | 双面板垂直排列 |
+| 平板 | 768px - 1024px | 双面板水平排列，字体稍小 |
+| 桌面 | > 1024px | 标准布局 |
+
+### 6.2 移动端适配
+
+```css
+@media (max-width: 768px) {
+  .panels-container {
+    flex-direction: column;
+  }
+
+  .panel {
+    height: 50%;
+    border-right: none;
+    border-bottom: 1px solid #dee2e6;
+  }
+
+  .file-size,
+  .file-date {
+    display: none; /* 隐藏次要信息 */
+  }
+
+  .toolbar {
+    flex-wrap: wrap;
+  }
+
+  .navbar-brand {
+    font-size: 16px;
+  }
+}
+```
+
+### 6.3 触摸优化
+
+- **触摸目标**：最小 44x44px
+- **间距**：触摸元素间距 ≥ 8px
+- **手势**：支持滑动、长按
+
+---
+
+## 7. 图标系统
+
+### 7.1 图标库
+
+使用 **Bootstrap Icons** 或 **Heroicons**，确保图标风格统一。
+
+### 7.2 图标大小
+
+| 用途 | 大小 | 说明 |
+|------|------|------|
+| 文件图标 | 20px | 文件列表中的文件类型图标 |
+| 操作图标 | 16px | 工具栏按钮图标 |
+| 状态图标 | 12px | 连接状态指示器 |
+
+### 7.3 图标颜色
+
+- **默认**：`#6c757d`（中灰）
+- **悬停**：`#212529`（深灰）
+- **选中**：`#ffffff`（白色，在深色背景上）
+- **状态**：使用对应的状态颜色
+
+---
+
+## 8. 阴影系统
+
+| 层级 | 阴影值 | 用途 |
+|------|--------|------|
+| 无 | `none` | 默认状态 |
+| 小 | `0 1px 2px rgba(0, 0, 0, 0.05)` | 卡片、按钮悬停 |
+| 中 | `0 0.5rem 1rem rgba(0, 0, 0, 0.15)` | 模态框、下拉菜单 |
+| 大 | `0 1rem 3rem rgba(0, 0, 0, 0.175)` | 大型弹窗 |
+
+---
+
+## 9. 动画规范
+
+### 9.1 过渡时间
+
+| 动画类型 | 时间 | 缓动函数 |
+|---------|------|---------|
+| 颜色变化 | 150ms | `ease` |
+| 位置变化 | 200ms | `ease-out` |
+| 缩放变化 | 200ms | `ease-in-out` |
+| 淡入淡出 | 300ms | `ease` |
+
+### 9.2 动画原则
+
+- **减少动画**：尊重 `prefers-reduced-motion` 设置
+- **性能优先**：使用 `transform` 和 `opacity`，避免 `width`/`height`
+- **适度使用**：动画应增强体验，而非干扰操作
+
+---
+
+## 10. 可访问性规范
+
+### 10.1 颜色对比度
+
+- 正文文字：≥ 4.5:1
+- 大号文字：≥ 3:1
+- 交互元素：≥ 3:1
+
+### 10.2 焦点状态
+
+所有可交互元素必须有可见的焦点指示器：
+
+```css
+*:focus {
+  outline: 2px solid #0d6efd;
+  outline-offset: 2px;
+}
+
+*:focus:not(:focus-visible) {
+  outline: none; /* 鼠标点击时不显示 */
+}
+```
+
+### 10.3 ARIA标签
+
+- 图标按钮：添加 `aria-label`
+- 表单输入：关联 `label` 元素
+- 状态信息：使用 `aria-live` 区域
+
+### 10.4 键盘导航
+
+- Tab顺序：符合视觉顺序
+- 快捷键：提供清晰的提示
+- 跳过链接：长页面提供跳转到主要内容
+
+---
+
+## 11. 设计令牌（Design Tokens）
+
+### 11.1 CSS变量定义
+
+```css
+:root {
+  /* 颜色 */
+  --color-primary: #0d6efd;
+  --color-success: #198754;
+  --color-warning: #ffc107;
+  --color-danger: #dc3545;
+  --color-dark: #212529;
+  --color-gray-600: #6c757d;
+  --color-gray-200: #e9ecef;
+  --color-gray-100: #f8f9fa;
+  --color-white: #ffffff;
+
+  /* 间距 */
+  --spacing-xs: 4px;
+  --spacing-sm: 8px;
+  --spacing-md: 16px;
+  --spacing-lg: 24px;
+  --spacing-xl: 32px;
+
+  /* 字体 */
+  --font-size-base: 14px;
+  --font-size-sm: 12px;
+  --font-size-lg: 18px;
+  --line-height-base: 1.5;
+
+  /* 圆角 */
+  --border-radius-sm: 4px;
+  --border-radius-md: 8px;
+
+  /* 阴影 */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);
+
+  /* 过渡 */
+  --transition-base: 150ms ease;
+}
+```
+
+---
+
+## 12. 实施检查清单
+
+### 视觉质量
+- [ ] 所有颜色符合对比度要求
+- [ ] 字体大小符合规范
+- [ ] 间距使用 8px 倍数
+- [ ] 图标风格统一
+- [ ] 阴影使用适度
+
+### 交互质量
+- [ ] 所有可点击元素有 `cursor-pointer`
+- [ ] 悬停效果流畅（150ms）
+- [ ] 焦点状态可见
+- [ ] 加载状态有反馈
+- [ ] 错误信息清晰
+
+### 响应式
+- [ ] 移动端布局测试通过
+- [ ] 触摸目标 ≥ 44px
+- [ ] 无水平滚动
+- [ ] 文字大小可读
+
+### 可访问性
+- [ ] 键盘导航完整
+- [ ] ARIA标签正确
+- [ ] 颜色对比度达标
+- [ ] 屏幕阅读器友好
+
+---
+
+## 更新日志
+
+### v1.0.0 (2026-02-02)
+- ✅ 初始设计系统发布
+- ✅ 定义颜色、字体、间距系统
+- ✅ 制定组件和交互规范
+- ✅ 建立响应式和可访问性标准