# Jointo（jointo）UI/UX 设计规范文档

> **项目名称**：Jointo（jointo）  
> **项目域名**：https://www.jointo.ai  
> **文档版本**：v1.0  
> **创建日期**：2025-01-08

---

## 目录

1. [设计原则](#1-设计原则)
2. [颜色系统](#2-颜色系统)
3. [字体系统](#3-字体系统)
4. [间距系统](#4-间距系统)
5. [圆角系统](#5-圆角系统)
6. [阴影系统](#6-阴影系统)
7. [交互状态](#7-交互状态)
8. [动画与过渡](#8-动画与过渡)
9. [响应式设计](#9-响应式设计)
10. [可访问性](#10-可访问性)
11. [图标规范](#11-图标规范)
12. [组件样式规范](#12-组件样式规范)

---

## 1. 设计原则

### 1.1 核心设计原则

- **一致性**：整个应用保持统一的视觉语言和交互模式
- **清晰性**：界面元素层次分明，信息传达清晰
- **高效性**：减少用户操作步骤，提升工作效率
- **专业性**：面向视频创作专业用户，界面简洁专业
- **可访问性**：遵循 WCAG 标准，确保所有用户可用

### 1.2 设计风格

- **双主题支持**：支持深色主题（默认）和亮色主题，可跟随系统自动切换
- **扁平化设计**：简洁的扁平化风格，减少视觉干扰
- **内容为王**：最大化内容展示区域，控件最小化
- **视觉层次**：通过颜色、大小、间距建立清晰的视觉层次

### 1.3 主题模式

| 模式                   | 说明               | 使用场景                     |
| ---------------------- | ------------------ | ---------------------------- |
| **深色主题（Dark）**   | 默认主题，深色背景 | 减少视觉疲劳，适合长时间工作 |
| **亮色主题（Light）**  | 浅色背景           | 光线充足的环境               |
| **跟随系统（System）** | 自动检测系统偏好   | 用户无需手动切换             |

---

## 2. 颜色系统

我们采用 Element Plus 风格的分级颜色系统，将颜色变量分为 7 个核心体系，以支持更灵活的主题定制和更清晰的语义表达。

### 2.1 颜色变量层级架构

| 体系                     | 前缀                      | 描述                 | 示例                               |
| ------------------------ | ------------------------- | -------------------- | ---------------------------------- |
| **1. 文字 (Text)**       | `--text-`                 | 4级文字层级          | `--text-primary`, `--text-regular` |
| **2. 边框 (Border)**     | `--border-`               | 4级边框层级          | `--border-base`, `--border-light`  |
| **3. 背景 (Background)** | `--bg-` / `--fill-`       | 页面/元素背景与填充  | `--bg-page`, `--fill-default`      |
| **4. 品牌 (Brand)**      | `--brand-`                | 品牌主色             | `--brand-default`, `--brand-hover` |
| **5. 功能 (Functional)** | `--success`, `--error` 等 | 状态反馈色           | `--success`, `--error`             |
| **6. 组件 (Component)**  | `--input-` 等             | 特定组件专用变量     | `--input-bg`, `--input-border`     |
| **7. 轨道 (Track)**      | `--track-`                | 业务专用（如分镜看板） | `--track-storyboard`               |

### 2.2 详细变量定义 (CSS Variables)

> **注意**: 项目使用 Tailwind v4 的 `@theme` 语法，变量通过 `--color-*` 前缀自动映射为工具类。

```css
/* 深色模式 (默认) */
:root {
  color-scheme: dark;

  /* 
   * 1. 文字体系 (Typography) - Zinc 色系
   * 分为主要、常规、次要、极弱、占位符 5 个等级
   */
  --text-primary: #fafafc; /* 主要文字 (标题, 重要信息) - Zinc-50 */
  --text-regular: #e4e4e7; /* 常规文字 (正文, 默认文本) - Zinc-200 */
  --text-secondary: #a1a1aa; /* 次要文字 (说明, 辅助信息) - Zinc-400 */
  --text-tertiary: #71717a; /* 极弱文字 (弱化信息) - Zinc-500 */
  --text-placeholder: #71717a; /* 占位符/禁用文字 - Zinc-500 */

  /* 
   * 2. 边框体系 (Borders) - Zinc 色系
   * 分为深色、基础、浅色、极浅 4 个等级
   */
  --border-dark: #52525b; /* 深色边框 (强调, 选中) - Zinc-600 */
  --border-base: #3f3f46; /* 基础边框 (默认) - Zinc-700 */
  --border-light: #27272a; /* 浅色边框 (分割线, 卡片) - Zinc-800 */
  --border-lighter: #18181b; /* 极浅边框 (极弱分割) - Zinc-900 */

  /* 
   * 3. 背景体系 (Backgrounds & Fills) - Zinc 色系
   */
  /* 页面级背景 */
  --bg-page: #09090b; /* 页面背景 (最底层) - Zinc-950 */
  --bg-overlay: #18181b; /* 浮层背景 (对话框, 下拉菜单) - Zinc-900 */
  --bg-element: #18181b; /* 元素背景 (卡片, 面板) - Zinc-900 */

  /* 填充色 (用于交互元素背景) */
  --fill-default: #27272a; /* 默认填充 (Tag, Badge) - Zinc-800 */
  --fill-darker: #121214; /* 深色填充 (Input 内部) */
  --fill-lighter: #3f3f46; /* 浅色填充 (悬停状态) - Zinc-700 */
  --fill-tertiary: #18181b; /* 第三级填充 - Zinc-900 */

  /* 
   * 4. 品牌色 (Primary/Brand) - 星际蓝
   */
  --primary: #3b82f6; /* 品牌主色 - Blue-500 */
  --primary-foreground: #ffffff; /* 品牌色前景 (文字) */
  --primary-hover: #2563eb; /* 品牌色悬停 - Blue-600 */
  --primary-active: #1d4ed8; /* 品牌色激活 - Blue-700 */

  /* 
   * 5. 功能色 (Functional)
   */
  --success: #22c55e; /* 成功 - Green-500 */
  --warning: #f59e0b; /* 警告 - Amber-500 */
  --error: #ef4444; /* 错误/破坏性操作 - Red-500 */
  --info: #3b82f6; /* 信息 - Blue-500 */
  --destructive: #7f1d1d; /* 破坏性操作背景 - Red-900 */
  --destructive-foreground: #fef2f2; /* 破坏性操作文字 - Red-50 */

  /* 
   * 6. 组件专用 (Components)
   * 针对常用组件的特定定义，提高自由度
   */
  /* 输入框 */
  --input-bg: var(--fill-darker);
  --input-bg-hover: var(--fill-default);
  --input-border: var(--border-light);
  --input-border-hover: var(--border-dark);
  --input-text: var(--text-regular);
  --input-placeholder: var(--text-placeholder);

  /* 
   * 7. Jointo - 轨道专用色
   */
  --track-storyboard: #60a5fa; /* 分镜轨道 - Blue-400 */
  --track-resource: #a78bfa; /* 资源轨道 - Violet-400 */
  --track-video: #34d399; /* 视频轨道 - Emerald-400 */
  --track-sound: #fbbf24; /* 音频轨道 - Amber-400 */
  --track-subtitle: #f87171; /* 字幕轨道 - Red-400 */
  --track-voice: #22d3ee; /* 配音轨道 - Cyan-400 */

  /* 其他变量 */
  --radius-sm: 0.125rem; /* 2px */
  --radius: 0.5rem; /* 8px */
  --radius-md: 0.375rem; /* 6px */
  --radius-lg: 0.5rem; /* 8px */
  --radius-xl: 0.75rem; /* 12px */
}

/* 亮色模式 */
.light {
  color-scheme: light;

  /* 1. 文字体系 */
  --text-primary: #09090b; /* Zinc-950 */
  --text-regular: #18181b; /* Zinc-900 */
  --text-secondary: #71717a; /* Zinc-500 */
  --text-tertiary: #a1a1aa; /* Zinc-400 */
  --text-placeholder: #a1a1aa; /* Zinc-400 */

  /* 2. 边框体系 */
  --border-dark: #a1a1aa; /* Zinc-400 */
  --border-base: #e4e4e7; /* Zinc-200 */
  --border-light: #f4f4f5; /* Zinc-100 */
  --border-lighter: #fafafa; /* Zinc-50 */

  /* 3. 背景体系 */
  --bg-page: #f4f4f5; /* Zinc-100 */
  --bg-overlay: #ffffff; /* White */
  --bg-element: #ffffff; /* White */

  --fill-default: #f4f4f5; /* Zinc-100 */
  --fill-darker: #fafafa; /* Zinc-50 */
  --fill-lighter: #e4e4e7; /* Zinc-200 */
  --fill-tertiary: #fafafa; /* Zinc-50 */

  /* 4. 品牌色 */
  --primary: #2563eb; /* Blue-600 */
  --primary-foreground: #ffffff;
  --primary-hover: #1d4ed8; /* Blue-700 */
  --primary-active: #1e40af; /* Blue-800 */

  /* 5. 功能色 */
  --destructive: #ef4444; /* Red-500 */
  --destructive-foreground: #ffffff;

  /* 6. 组件专用 */
  --input-bg: var(--fill-darker);
  --input-bg-hover: var(--bg-overlay);
  --input-border: var(--border-base);
  --input-border-hover: var(--border-dark);
  --input-text: var(--text-regular);
  --input-placeholder: var(--text-placeholder);
}
```

### 2.3 工具类映射 (Tailwind CSS)

项目使用 **Tailwind v4** 的 `@theme` 语法，CSS 变量通过 `--color-*` 前缀自动映射为工具类。

#### 自动映射规则

```css
/* globals.css 中的映射定义 */
@theme {
  --color-text-primary: var(--text-primary);
  --color-bg-page: var(--bg-page);
  --color-border-base: var(--border-base);
  --color-primary: var(--primary);
  /* ... 其他映射 */
}
```

#### 可用工具类

**文字颜色**:

- `text-text-primary` - 主要文字
- `text-text-regular` - 常规文字
- `text-text-secondary` - 次要文字
- `text-text-tertiary` - 极弱文字
- `text-text-placeholder` - 占位符

**背景颜色**:

- `bg-bg-page` - 页面背景
- `bg-bg-overlay` - 浮层背景
- `bg-bg-element` - 元素背景
- `bg-fill-default` - 默认填充
- `bg-fill-darker` - 深色填充
- `bg-fill-lighter` - 浅色填充

**边框颜色**:

- `border-border-dark` - 深色边框
- `border-border-base` - 基础边框
- `border-border-light` - 浅色边框
- `border-border-lighter` - 极浅边框

**品牌色**:

- `text-primary` / `bg-primary` - 品牌主色
- `text-brand-default` / `bg-brand-default` - 品牌色别名

**功能色**:

- `text-success` / `bg-success` - 成功
- `text-warning` / `bg-warning` - 警告
- `text-error` / `bg-error` - 错误
- `text-info` / `bg-info` - 信息

#### 实际使用示例

```tsx
// 页面容器
<div className="min-h-screen bg-bg-page">
  {/* 卡片 */}
  <div className="bg-bg-element border border-border-base rounded-lg p-4">
    {/* 标题 */}
    <h2 className="text-text-primary text-xl font-semibold">项目标题</h2>

    {/* 描述 */}
    <p className="text-text-secondary mt-2">项目描述信息</p>

    {/* 主要按钮 */}
    <button className="bg-primary text-white hover:bg-primary-hover px-4 py-2 rounded">
      确认
    </button>

    {/* 次要按钮 */}
    <button className="bg-fill-default text-text-primary hover:bg-fill-lighter border border-border-base px-4 py-2 rounded">
      取消
    </button>
  </div>
</div>
```

---

## 3. 字体系统

### 3.1 字体家族

```css
:root {
  /* 主字体 - 中英文混排 */
  --font-family-sans:
    "Inter", "PingFang SC", "Microsoft YaHei", "Helvetica Neue", Arial,
    sans-serif;

  /* 等宽字体 - 代码、时间码 */
  --font-family-mono:
    "JetBrains Mono", "Fira Code", "SF Mono", Monaco, monospace;
}
```

### 3.2 字体大小

```css
:root {
  /* 字体大小 */
  --font-size-xs: 0.75rem; /* 12px - 辅助文字 */
  --font-size-sm: 0.875rem; /* 14px - 次要文字、标签 */
  --font-size-base: 1rem; /* 16px - 正文 */
  --font-size-lg: 1.125rem; /* 18px - 小标题 */
  --font-size-xl: 1.25rem; /* 20px - 标题 */
  --font-size-2xl: 1.5rem; /* 24px - 大标题 */
  --font-size-3xl: 1.875rem; /* 30px - 页面标题 */
}
```

### 3.3 字重

```css
:root {
  --font-weight-normal: 400; /* 正常 */
  --font-weight-medium: 500; /* 中等 */
  --font-weight-semibold: 600; /* 半粗 */
  --font-weight-bold: 700; /* 粗体 */
}
```

### 3.4 行高

```css
:root {
  --line-height-tight: 1.25; /* 紧凑 - 标题 */
  --line-height-normal: 1.5; /* 正常 - 正文 */
  --line-height-relaxed: 1.75; /* 宽松 - 段落 */
}
```

### 3.5 字体使用规范

| 用途     | 大小 | 字重 | 行高 | 颜色                |
| -------- | ---- | ---- | ---- | ------------------- |
| 页面标题 | 24px | 600  | 1.25 | text-primary        |
| 区域标题 | 18px | 600  | 1.25 | text-primary        |
| 卡片标题 | 16px | 500  | 1.5  | text-primary        |
| 正文内容 | 14px | 400  | 1.5  | text-primary        |
| 辅助说明 | 14px | 400  | 1.5  | text-secondary      |
| 标签文字 | 12px | 500  | 1.25 | text-secondary      |
| 时间码   | 14px | 500  | 1    | text-primary (mono) |
| 按钮文字 | 14px | 500  | 1    | text-primary        |

---

## 4. 间距系统

### 4.1 基础间距单位

基础单位：`4px`，所有间距为基础单位的倍数。

```css
:root {
  --spacing-0: 0;
  --spacing-0.5: 0.125rem; /* 2px */
  --spacing-1: 0.25rem; /* 4px */
  --spacing-1.5: 0.375rem; /* 6px */
  --spacing-2: 0.5rem; /* 8px */
  --spacing-2.5: 0.625rem; /* 10px */
  --spacing-3: 0.75rem; /* 12px */
  --spacing-3.5: 0.875rem; /* 14px */
  --spacing-4: 1rem; /* 16px */
  --spacing-5: 1.25rem; /* 20px */
  --spacing-6: 1.5rem; /* 24px */
  --spacing-7: 1.75rem; /* 28px */
  --spacing-8: 2rem; /* 32px */
  --spacing-9: 2.25rem; /* 36px */
  --spacing-10: 2.5rem; /* 40px */
  --spacing-12: 3rem; /* 48px */
  --spacing-16: 4rem; /* 64px */
  --spacing-20: 5rem; /* 80px */
}
```

### 4.2 组件内边距

| 组件类型     | 水平内边距 | 垂直内边距 |
| ------------ | ---------- | ---------- |
| 按钮（小）   | 12px       | 6px        |
| 按钮（默认） | 16px       | 8px        |
| 按钮（大）   | 24px       | 12px       |
| 输入框       | 12px       | 8px        |
| 卡片         | 16px       | 16px       |
| 面板         | 16px       | 12px       |
| 弹窗内容     | 24px       | 20px       |
| Tab 项       | 16px       | 8px        |

### 4.3 组件间距

| 场景       | 间距 |
| ---------- | ---- |
| 相关元素间 | 8px  |
| 组间       | 16px |
| 区块间     | 24px |
| 面板与内容 | 16px |
| 列表项间   | 8px  |
| 按钮组间   | 8px  |

---

## 5. 圆角系统

```css
:root {
  --radius-none: 0;
  --radius-sm: 0.125rem; /* 2px - 小标签 */
  --radius-default: 0.25rem; /* 4px - 按钮、输入框 */
  --radius-md: 0.375rem; /* 6px - 卡片 */
  --radius-lg: 0.5rem; /* 8px - 面板 */
  --radius-xl: 0.75rem; /* 12px - 弹窗 */
  --radius-2xl: 1rem; /* 16px - 大弹窗 */
  --radius-full: 9999px; /* 圆形 - 头像、徽章 */
}
```

### 5.1 组件圆角规范

| 组件     | 圆角 |
| -------- | ---- |
| 按钮     | 4px  |
| 输入框   | 4px  |
| 标签     | 2px  |
| 卡片     | 6px  |
| 面板     | 8px  |
| 弹窗     | 12px |
| 头像     | 圆形 |
| 分镜看板块 | 4px  |
| 缩略图   | 4px  |

---

## 6. 阴影系统

```css
:root {
  /* 阴影 - 深色主题专用 */
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.3);
  --shadow-default:
    0 1px 3px 0 rgb(0 0 0 / 0.4), 0 1px 2px -1px rgb(0 0 0 / 0.4);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.4), 0 2px 4px -2px rgb(0 0 0 / 0.4);
  --shadow-lg:
    0 10px 15px -3px rgb(0 0 0 / 0.4), 0 4px 6px -4px rgb(0 0 0 / 0.4);
  --shadow-xl:
    0 20px 25px -5px rgb(0 0 0 / 0.4), 0 8px 10px -6px rgb(0 0 0 / 0.4);

  /* 焦点环 */
  --shadow-focus:
    0 0 0 2px var(--color-bg-primary), 0 0 0 4px var(--color-primary);
}
```

### 6.1 组件阴影规范

| 组件/场景 | 阴影         |
| --------- | ------------ |
| 默认状态  | 无           |
| 卡片悬停  | shadow-sm    |
| 下拉菜单  | shadow-md    |
| 弹窗      | shadow-lg    |
| 抽屉      | shadow-xl    |
| 焦点状态  | shadow-focus |

---

## 7. 交互状态

### 7.1 按钮状态

```css
/* 主要按钮 */
.btn-primary {
  /* 默认状态 */
  background: var(--color-primary);
  color: white;

  /* 悬停状态 */
  &:hover {
    background: var(--color-primary-hover);
  }

  /* 激活状态 */
  &:active {
    background: var(--color-primary-active);
  }

  /* 禁用状态 */
  &:disabled {
    background: var(--color-bg-tertiary);
    color: var(--color-text-disabled);
    cursor: not-allowed;
  }

  /* 加载状态 */
  &.loading {
    pointer-events: none;
    opacity: 0.7;
  }
}

/* 次要按钮 */
.btn-secondary {
  background: var(--color-bg-secondary);
  color: var(--color-text-primary);
  border: 1px solid var(--color-border-default);

  &:hover {
    background: var(--color-bg-tertiary);
    border-color: var(--color-border-hover);
  }
}

/* 幽灵按钮 */
.btn-ghost {
  background: transparent;
  color: var(--color-text-secondary);

  &:hover {
    background: var(--color-bg-tertiary);
    color: var(--color-text-primary);
  }
}
```

### 7.2 输入框状态

```css
.input {
  /* 默认状态 */
  background: var(--color-bg-secondary);
  border: 1px solid var(--color-border-default);
  color: var(--color-text-primary);

  /* 占位符 */
  &::placeholder {
    color: var(--color-text-tertiary);
  }

  /* 悬停状态 */
  &:hover {
    border-color: var(--color-border-hover);
  }

  /* 焦点状态 */
  &:focus {
    border-color: var(--color-border-focus);
    outline: none;
    box-shadow: var(--shadow-focus);
  }

  /* 错误状态 */
  &.error {
    border-color: var(--color-error);
  }

  /* 禁用状态 */
  &:disabled {
    background: var(--color-bg-tertiary);
    color: var(--color-text-disabled);
    cursor: not-allowed;
  }
}
```

### 7.3 选中状态

```css
/* 分镜选中 */
.storyboard-item {
  &.selected {
    background: var(--color-bg-tertiary);
    border-left: 3px solid var(--color-primary);
  }
}

/* Tab 选中 */
.tab-item {
  &.active {
    color: var(--color-primary);
    border-bottom: 2px solid var(--color-primary);
  }
}

/* 列表项选中 */
.list-item {
  &.selected {
    background: var(--color-primary);
    background-opacity: 0.1;
    color: var(--color-primary);
  }
}

/* 分镜看板块选中 */
.timeline-block {
  &.selected {
    outline: 2px solid var(--color-primary);
    outline-offset: 1px;
  }
}
```

---

## 8. 动画与过渡

### 8.1 过渡时间

```css
:root {
  --duration-instant: 0ms;
  --duration-fast: 100ms;
  --duration-normal: 200ms;
  --duration-slow: 300ms;
  --duration-slower: 500ms;
}
```

### 8.2 缓动函数

```css
:root {
  --ease-linear: linear;
  --ease-in: cubic-bezier(0.4, 0, 1, 1);
  --ease-out: cubic-bezier(0, 0, 0.2, 1);
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
  --ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
}
```

### 8.3 常用过渡

```css
/* 颜色过渡 - 按钮、链接 */
.transition-colors {
  transition:
    background-color var(--duration-fast) var(--ease-in-out),
    border-color var(--duration-fast) var(--ease-in-out),
    color var(--duration-fast) var(--ease-in-out);
}

/* 透明度过渡 - 显示/隐藏 */
.transition-opacity {
  transition: opacity var(--duration-normal) var(--ease-in-out);
}

/* 变换过渡 - 缩放、移动 */
.transition-transform {
  transition: transform var(--duration-normal) var(--ease-out);
}

/* 全部过渡 */
.transition-all {
  transition: all var(--duration-normal) var(--ease-in-out);
}
```

### 8.4 动画效果

```css
/* 淡入 */
@keyframes fadeIn {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

/* 淡出 */
@keyframes fadeOut {
  from {
    opacity: 1;
  }
  to {
    opacity: 0;
  }
}

/* 向上滑入 */
@keyframes slideInUp {
  from {
    opacity: 0;
    transform: translateY(10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* 向下滑入 */
@keyframes slideInDown {
  from {
    opacity: 0;
    transform: translateY(-10px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* 缩放进入 */
@keyframes scaleIn {
  from {
    opacity: 0;
    transform: scale(0.95);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

/* 旋转加载 */
@keyframes spin {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

/* 脉冲效果 */
@keyframes pulse {
  0%,
  100% {
    opacity: 1;
  }
  50% {
    opacity: 0.5;
  }
}
```

### 8.5 动画使用场景

| 场景         | 动画               | 时长          |
| ------------ | ------------------ | ------------- |
| 弹窗打开     | scaleIn + fadeIn   | 200ms         |
| 弹窗关闭     | scaleOut + fadeOut | 150ms         |
| 下拉菜单打开 | slideInDown        | 200ms         |
| Toast 出现   | slideInUp          | 300ms         |
| 按钮点击     | scale(0.98)        | 100ms         |
| 加载中       | spin               | 1000ms (循环) |
| 骨架屏       | pulse              | 2000ms (循环) |

---

## 9. 响应式设计

### 9.1 断点设置

```css
:root {
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-2xl: 1536px;
}
```

### 9.2 Tailwind 配置

项目使用 **Tailwind v4**，配置通过 `@theme` 指令在 `globals.css` 中定义，无需单独的 `tailwind.config.js` 文件。

```css
/* client/src/styles/globals.css */
@theme {
  /* 断点配置 (Tailwind v4 默认值) */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-2xl: 1536px;

  /* 颜色映射 */
  --color-text-primary: var(--text-primary);
  --color-bg-page: var(--bg-page);
  /* ... */
}
```

**使用方式**:

```tsx
<div className="w-full md:w-1/2 lg:w-1/3">响应式布局</div>
```

### 9.3 布局适配策略

| 屏幕尺寸     | 断点    | 布局策略                       |
| ------------ | ------- | ------------------------------ |
| 超大屏       | ≥1536px | 完整布局，所有面板展开         |
| 大屏（默认） | ≥1280px | 完整布局                       |
| 中屏         | ≥1024px | 侧边栏可折叠                   |
| 小屏         | ≥768px  | 侧边栏默认收起，可展开覆盖     |
| 移动端       | <768px  | 单列布局，面板切换（可选实现） |

### 9.4 面板宽度

```css
:root {
  /* 侧边栏宽度 */
  --sidebar-width-collapsed: 60px;
  --sidebar-width-expanded: 280px;

  /* 右侧面板宽度 */
  --right-panel-width: 320px;

  /* 分镜看板高度 */
  --timeline-height-collapsed: 48px;
  --timeline-height-expanded: 300px;
}
```

---

## 10. 可访问性

### 10.1 颜色对比度

- **文字对比度**：主文字与背景对比度 ≥ 4.5:1（WCAG AA 级）
- **大文字对比度**：标题与背景对比度 ≥ 3:1
- **交互元素**：与背景对比度 ≥ 3:1

### 10.2 焦点指示器

```css
/* 焦点可见性 */
*:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

/* 鼠标操作隐藏焦点环 */
*:focus:not(:focus-visible) {
  outline: none;
}
```

### 10.3 键盘导航

| 按键              | 功能               |
| ----------------- | ------------------ |
| `Tab`             | 在可交互元素间前进 |
| `Shift + Tab`     | 在可交互元素间后退 |
| `Enter` / `Space` | 激活按钮、链接     |
| `Esc`             | 关闭弹窗、取消操作 |
| `↑` / `↓`         | 列表项导航         |
| `←` / `→`         | Tab 切换、滑块调节 |

### 10.4 ARIA 标签规范

```html
<!-- 按钮带图标 -->
<button aria-label="新建项目">
  <PlusIcon />
</button>

<!-- 区域标识 -->
<nav aria-label="主导航">...</nav>
<main aria-label="主内容区">...</main>
<aside aria-label="侧边栏">...</aside>

<!-- 状态指示 -->
<button aria-pressed="true">播放</button>
<input aria-invalid="true" aria-describedby="error-message" />

<!-- 动态内容 -->
<div role="alert" aria-live="polite">保存成功</div>

<!-- 弹窗 -->
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">新建项目</h2>
</div>
```

### 10.5 屏幕阅读器友好

- 所有图片提供 `alt` 文本
- 表单元素关联 `label`
- 隐藏装饰性元素：`aria-hidden="true"`
- 使用语义化 HTML 标签

---

## 11. 图标规范

### 11.1 图标库

使用 **lucide-react** 图标库，与 shadcn/ui 配套。

```bash
npm install lucide-react
```

### 11.2 图标尺寸

```css
:root {
  --icon-xs: 12px;
  --icon-sm: 16px;
  --icon-md: 20px;
  --icon-lg: 24px;
  --icon-xl: 32px;
}
```

### 11.3 图标使用规范

| 场景         | 尺寸 | strokeWidth |
| ------------ | ---- | ----------- |
| 按钮内图标   | 16px | 2           |
| 菜单项图标   | 16px | 2           |
| 标签内图标   | 14px | 2           |
| 工具栏图标   | 20px | 2           |
| 面板头部图标 | 20px | 2           |
| 空状态图标   | 48px | 1.5         |

### 11.4 常用图标映射

| 功能    | 图标名称         |
| ------- | ---------------- |
| 新建    | `Plus`           |
| 删除    | `Trash2`         |
| 编辑    | `Pencil`         |
| 搜索    | `Search`         |
| 设置    | `Settings`       |
| 关闭    | `X`              |
| 返回    | `ArrowLeft`      |
| 更多    | `MoreHorizontal` |
| 播放    | `Play`           |
| 暂停    | `Pause`          |
| 上一帧  | `SkipBack`       |
| 下一帧  | `SkipForward`    |
| 放大    | `ZoomIn`         |
| 缩小    | `ZoomOut`        |
| 导出    | `Download`       |
| 上传    | `Upload`         |
| 文件夹  | `Folder`         |
| 文件    | `File`           |
| 用户    | `User`           |
| 通知    | `Bell`           |
| AI/魔法 | `Sparkles`       |

---

## 12. 组件样式规范

### 12.1 按钮组件

```tsx
// 按钮变体
type ButtonVariant = "primary" | "secondary" | "ghost" | "destructive" | "link";

// 按钮大小
type ButtonSize = "sm" | "default" | "lg" | "icon";

// 样式规范
const buttonStyles = {
  // 大小
  sm: "h-8 px-3 text-xs",
  default: "h-9 px-4 text-sm",
  lg: "h-10 px-6 text-base",
  icon: "h-9 w-9",

  // 变体
  primary: "bg-primary text-white hover:bg-primary-hover",
  secondary:
    "bg-background-secondary border border-border hover:bg-background-tertiary",
  ghost: "hover:bg-background-tertiary",
  destructive: "bg-error text-white hover:bg-error/90",
  link: "text-primary underline-offset-4 hover:underline",
};
```

### 12.2 卡片组件

```tsx
// 卡片样式
const cardStyles = {
  base: `
    bg-background-secondary 
    rounded-md 
    border border-border
  `,
  hover: `
    hover:border-border-hover 
    hover:shadow-sm 
    transition-all
  `,
  selected: `
    border-primary 
    bg-primary/5
  `,
};
```

### 12.3 面板组件

```tsx
// 面板样式
const panelStyles = {
  header: `
    flex items-center justify-between
    px-4 py-3
    border-b border-border
  `,
  content: `
    p-4
    overflow-auto
  `,
  footer: `
    flex items-center justify-end gap-2
    px-4 py-3
    border-t border-border
  `,
};
```

### 12.4 弹窗组件

```tsx
// 弹窗样式
const dialogStyles = {
  overlay: `
    fixed inset-0
    bg-black/80
    backdrop-blur-sm
  `,
  content: `
    fixed left-1/2 top-1/2 
    -translate-x-1/2 -translate-y-1/2
    bg-background-secondary
    rounded-xl
    border border-border
    shadow-xl
    max-h-[85vh]
    overflow-hidden
  `,
  sizes: {
    sm: "w-[400px]",
    md: "w-[500px]",
    lg: "w-[600px]",
    xl: "w-[800px]",
    full: "w-[90vw] max-w-[1200px]",
  },
};
```

---

## 附录

### A. CSS 变量完整清单

所有 CSS 变量应在 `globals.css` 中定义：

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    /* 在此定义所有 CSS 变量 */
  }
}
```

### B. 设计稿参考

- **Figma 文件**：`https://www.figma.com/make/xgPuMR3GZzHpYh0RZJdiYK/kaidong.ai`
- **密码**：`0592`

### C. 变更记录

- **v1.0** (2025-01-08)：初始版本，从 PRD 文档中拆分

---

**文档结束**

> 本文档定义Jointo产品的视觉设计规范，所有前端开发应遵循本规范确保界面一致性。