# 七虎AI · DESIGN.md

> **用途**：这是七虎 AI PaaS 平台的**唯一设计事实源（single source of truth）**。任何 AI 编码代理在新增/修改前端页面或组件时，必须读取本文件并严格遵守其中的设计 token、组件规范与 Do/Don't。
> **风格方向**：温暖科技感 + 极简主义（Warm Tech Minimalism）。浅色为主，靛蓝 `#5B5FED` 为唯一品牌色。
> **生成方式**：基于平台现有 `frontend/src/styles/global.css` 的真实 token 固化升华，并经由 `ui-ux-pro-max` 技能的数据驱动生成器校验风格一致性。
> 关联文件：`design-system/MASTER.md`（Master+Overrides 模式，含组件 CSS 样板）、`.impeccable.md`（impeccable 技能入口）。

---

## 1. Visual Theme & Atmosphere

七虎 AI 是一个面向企业与开发者的 AI PaaS 平台（智能体编排、技能市场、模型库、工作流、IM Bot）。界面需要传达**专业、可信、精密**，同时带有**温度**（不冰冷）。

- **Mood**：沉着、秩序、精密、可信任；用留白与柔和表面营造呼吸感。
- **Density**：中高密度（开发者控制台），信息密集但不拥挤；关键操作常驻（header + sidebar）。
- **Design philosophy**：
  - 单一品牌色（靛蓝）贯穿全站，语义色只用于状态（成功/警告/错误/信息）。
  - 表面层级用极浅灰阶 + 柔和阴影区分，而非重边框。
  - 动效克制：150–300ms 缓动，仅做"提示"不抢戏。
  - 全站浅色主题；深色模式暂不在范围内。

## 2. Color Palette & Roles

所有色值以 CSS 变量定义在 `global.css` 的 `:root`。**新增颜色必须先定义为 token，禁止散落硬编码 hex。**

### 中性 / 表面
| 语义名 | Hex | 角色 |
|---|---|---|
| `--color-bg-primary` | `#F8F9FB` | 页面主背景（最浅） |
| `--color-bg-secondary` | `#FFFFFF` | 卡片 / 浮层表面 |
| `--color-bg-tertiary` | `#F1F3F7` | 输入框底 / 次级表面 |
| `--color-bg-hover` | `#EBEEF3` | hover 表面 |
| `--color-bg-active` | `#E3E7F0` | 选中 / 激活表面 |

### 文本
| 语义名 | Hex | 角色 |
|---|---|---|
| `--color-text-primary` | `#101214` | 主文本 / 标题 |
| `--color-text-secondary` | `#545A65` | 次要文本 |
| `--color-text-tertiary` | `#8B919E` | 提示 / 占位 |
| `--color-text-disabled` | `#BFC4CE` | 禁用 |
| `--color-text-inverse` | `#FFFFFF` | 深色表面上的文本 |

### 品牌 / 语义
| 语义名 | Hex | 角色 |
|---|---|---|
| `--color-accent` | `#5B5FED` | **唯一品牌色**（主按钮、激活态、链接、焦点环） |
| `--color-accent-hover` | `#4A4ECC` | 品牌色 hover |
| `--color-accent-light` | `#EEEDFF` | 品牌色浅底（tag / 选中背景） |
| `--color-accent-subtle` | `#F6F5FF` | 品牌色极浅底 |
| `--color-success` | `#219B5E` | 成功 / 在线 |
| `--color-warning` | `#E8922C` | 警告 |
| `--color-error` | `#D9383A` | 错误 / 危险 |
| `--color-info` | `#3B82F6` | 信息 |
| （各语义的 `-light` 变体） | `#E6F7EE` / `#FEF4E8` / `#FDEBEB` / `#EBF2FE` | 浅底色块 |

### 边框 / 侧栏
| 语义名 | Hex | 角色 |
|---|---|---|
| `--color-border` | `#E3E6EB` | 默认边框 |
| `--color-border-light` | `#EEF0F4` | 极浅分隔线 |
| `--color-border-hover` | `#CDD2DA` | 边框 hover |
| `--color-sidebar-bg` | `#F5F6F9` | 侧栏背景 |
| `--color-sidebar-hover` | `#EAECF2` | 侧栏项 hover |
| `--color-sidebar-active` | `#E1E3F0` | 侧栏项激活 |

**对比度约束**：文本在浅色表面上至少 4.5:1（WCAG AA）。`--color-text-tertiary` 仅用于非关键提示，不用于正文。

## 3. Typography Rules

- **字体**：`Inter`（正文/标题）+ `JetBrains Mono`（代码、模型 ID、token、技术参数）。中文回退系统字体。
  - CSS import：`@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&family=JetBrains+Mono:wght@400;500;600&display=swap');`
- **字阶（scale）**：
  | Token | 尺寸 | 用途 |
  |---|---|---|
  | `--text-xs` | 11px | 角标 / 极次要 |
  | `--text-sm` | 13px | 辅助文本 / 列表项 |
  | `--text-base` | 14px | 正文默认 |
  | `--text-md` | 15px | 稍强调正文 |
  | `--text-lg` | 18px | 小标题 |
  | `--text-xl` | 22px | 区块标题 |
  | `--text-2xl` | 28px | 页面标题 |
  | `--text-3xl` | 36px | Hero / 大标题 |
- **字重**：正文 400，标题/强调 500–600，数字/统计可 700–800。避免过度加粗（≤600 为主）。
- **行高**：正文 `line-height: 1.6`；标题 1.3–1.4。
- **中文**：优先 Inter 的拉丁字形 + 系统中文回退；避免中文用 mono。

## 4. Component Stylings

（完整 CSS 样板见 `design-system/MASTER.md`；此处为快速参考。所有组件需 `cursor: pointer`、hover 过渡 150–300ms、可见 focus 环。）

### Buttons
- **Primary**：`background: var(--color-accent); color:#fff; border-radius: var(--radius-md); padding: 10px 18px; font-weight:500;` hover → `--color-accent-hover` + `translateY(-1px)`。
- **Secondary**：透明底 + `1px solid var(--color-accent)` + 品牌色文字；hover 浅底 `--color-accent-subtle`。
- **Ghost**：无边框无底，hover 仅 `--color-bg-hover`；用于工具栏图标按钮。
- **Danger**：`var(--color-error)` 文本/边框，确认类操作用。

### Cards / Panels
- `background: var(--color-bg-secondary); border:1px solid var(--color-border); border-radius: var(--radius-lg); padding: var(--space-2xl);`
- hover（可点击卡片）：`box-shadow: var(--shadow-lg); translateY(-2px)`。
- 数据卡（KPI）：上方 label（tertiary）+ 大数字（text-2xl, weight 700）+ 趋势小标。

### Inputs / Textarea / Select
- `padding:10px 14px; border:1px solid var(--color-border); border-radius: var(--radius-md); font-size: var(--text-base); background: var(--color-bg-secondary);`
- focus：`border-color: var(--color-accent); box-shadow: 0 0 0 3px var(--color-accent-light); outline:none;`
- placeholder：`var(--color-text-tertiary)`。

### Navigation / Sidebar
- 宽 `--sidebar-width: 240px`（折叠 64px）；项高 ~40px，圆角 `--radius-md`，hover/active 用 `--color-sidebar-hover` / `--color-sidebar-active`；激活项左或文字用品牌色。
- 顶部 header 高 `--header-height: 56px`，承载主操作与全局搜索。

### Tags / Badges / Chips
- 用 `--color-accent-light` 浅底 + 品牌色文字表示"能力/标签"；语义状态用对应 `-light` 底（success/warning/error/info）。
- 图标统一用 **Lucide**（见 §7），禁止 emoji 当图标。

### Modals / Drawers
- overlay：`rgba(0,0,0,0.5)` + `backdrop-filter: blur(4px)`。
- 弹窗：`background:#fff; border-radius: var(--radius-xl); padding: var(--space-3xl); box-shadow: var(--shadow-xl);` 右侧抽屉（detail drawer）用于 Agent/技能详情。

## 5. Layout Principles

- **间距阶梯**（必须用语义 token，禁止随意像素）：`xs4 / sm8 / md12 / lg16 / xl20 / 2xl24 / 3xl32 / 4xl40 / 5xl48`。
- **栅格**：内容最大宽度 1440px 居中；主工作区用 12 列弹性栅格；卡片间距 `--space-lg`。
- **留白哲学**：区块间 `--space-3xl`~`--space-5xl`；卡片内 `--space-2xl`；避免贴边，页面左右留 `--space-2xl`+。
- **圆角**：小组件 `sm6/md8`，卡片/面板 `lg12`，弹窗 `xl16`，全圆 `--radius-full`（头像/徽标/药丸按钮）。
- **App Shell**：左侧 sidebar（工作区导航）+ 顶 header（全局操作）+ 主内容区；IM Bot / 技能详情用右侧 drawer 不离开上下文。

## 6. Depth & Elevation

阴影层级（柔和、低透明，营造"浮起"而非"描边"）：
| Token | 值 | 用途 |
|---|---|---|
| `--shadow-xs` | `0 1px 2px rgba(0,0,0,.04)` | 内部分隔 |
| `--shadow-sm` | `0 1px 3px rgba(0,0,0,.06)` | 静态卡 |
| `--shadow-md` | `0 4px 12px rgba(0,0,0,.06)` | 卡片 / 按钮 |
| `--shadow-lg` | `0 12px 32px rgba(0,0,0,.08)` | hover 卡 / 下拉 |
| `--shadow-xl` | `0 20px 48px rgba(0,0,0,.10)` | 弹窗 / 浮层 |

规则：表面层级靠"背景明度 + 阴影"双信号区分；禁用重投影与硬黑边。

## 7. Do's and Don'ts

**Do**
- 所有可点击元素加 `cursor: pointer` 与可见 hover/focus 态。
- 用 Lucide SVG 图标；技术参数用 JetBrains Mono。
- 状态用语义色；品牌表达只用 `--color-accent`。
- 动效克制（150–300ms ease），尊重 `prefers-reduced-motion`。
- 加载态用 skeleton shimmer，避免生硬 spinner。

**Don't**
- ❌ 用 emoji 当图标。
- ❌ 引入除靛蓝外的第二个"品牌色"（除非语义状态）。
- ❌ 低对比文本（<4.5:1）。
- ❌ hover 用 `scale` 导致布局位移。
- ❌ 瞬时状态切换（无过渡）。
- ❌ 焦点态不可见（键盘可达性）。
- ❌ 在 `global.css` 之外散落硬编码 hex。

## 8. Responsive Behavior

断点：`375px`（手机）/ `768px`（折叠 sidebar 为 64px 或抽屉）/ `1024px`（平板）/ `1440px`（桌面最大宽）。
- 移动端：sidebar 转底部 tab 或抽屉；主内容单列；触摸目标 ≥40px。
- 平板：sidebar 折叠 64px，悬停展开。
- 栅格在窄屏降列数（12→6→1）。
- 禁止横向滚动；表格在窄屏转卡片或横向滚动容器。

## 9. Agent Prompt Guide

> 当被要求"做/改一个七虎AI 的页面或组件"时，代理必须：
> 1. 先读本文件（DESIGN.md）与 `design-system/MASTER.md`；
> 2. 颜色/间距/圆角/字体一律引用 `:root` token，禁止新硬编码；
> 3. 品牌色固定 `#5B5FED`，语义色仅表状态；
> 4. 图标用 Lucide；代码/ID 用 JetBrains Mono；
> 5. 组件带 hover + focus + 150–300ms 过渡；
> 6. 完成后 `npm run build` 并确认 `dist` 含改动，再请用户硬刷新验收。

**快捷色板（供 prompt 引用）**
```
brand   #5B5FED  hover #4A4ECC  light #EEEDFF
bg      #F8F9FB  surface #FFFFFF  tertiary #F1F3F7
text    #101214  secondary #545A65  tertiary #8B919E
ok #219B5E  warn #E8922C  err #D9383A  info #3B82F6
border #E3E6EB  sidebar #F5F6F9
font    Inter / JetBrains Mono
```

**推荐 prompt 模板**
- "在七虎AI 中新增一个 [页面]，遵循 DESIGN.md 的 Warm Tech Minimalism 风格，品牌色用 #5B5FED，图标用 Lucide，间距用 token。"
- "把 [组件] 改成符合 DESIGN.md §4 的卡片规范，hover 用 --shadow-lg + translateY(-2px)。"