# 七虎AI · DESIGN.md

> **用途**：这是七虎 AI PaaS 平台的**唯一设计事实源（single source of truth）**。任何 AI 编码代理在新增/修改前端页面或组件时，必须读取本文件并严格遵守其中的设计 token、组件规范与 Do/Don't。
> **风格方向**：温暖科技感 + 极简主义（Warm Tech Minimalism）。浅色为主（护眼雾白底），靛蓝 `#5B5FED` 为唯一品牌色；允许克制的「淡蓝紫→淡青蓝」渐变与轻量玻璃拟态（Glassmorphism）；前台必须符合 SEO/GEO 语义规范。
> **生成方式**：基于平台现有 `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` | 侧栏项激活 |

### 渐变 / Gradients（新增，源自"护眼科技感 + 渐变"需求）
平台允许**克制**的渐变，用于背景 / 装饰 / 主行动点，绝非赛博朋克式高饱和。所有渐变必须先定义为 token：
| 语义名 | 值 | 角色 |
|---|---|---|
| `--gradient-brand` | `linear-gradient(135deg, #EEEDFF 0%, #E3F0FF 100%)` | Hero / 区块浅底（淡蓝紫 → 淡青蓝） |
| `--gradient-brand-strong` | `linear-gradient(135deg, #5B5FED 0%, #4F8DF9 100%)` | 主 CTA / Banner 强调（品牌色渐变，不刺眼） |
| `--gradient-aurora` | `radial-gradient(60% 60% at 30% 20%, rgba(91,95,237,.10), transparent 70%)` | 仅 Hero 装饰光斑，绝不直接衬文字 |

**渐变铁律**：
- 渐变只作背景 / 装饰 / CTA；**承载正文文字的表面必须纯色**（`#FFFFFF` / `#F8F9FB`），确保 ≥4.5:1。
- 拒绝全屏流动 / 循环渐变动画（aurora 8–12s loop）作用于文字区；装饰光斑在 `prefers-reduced-motion` 下静止。
- 不引入品牌色之外的第三色相做渐变（仅「靛蓝 → 青蓝」的同系过渡）。

**对比度约束**：文本在浅色表面上至少 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/技能详情。

### Glassmorphism（轻量玻璃拟态变体）
用于浮层 / 导航 / Hero 叠加 / 横幅，营造通透科技感（技能库 Glassmorphism 条目：backdrop blur 10–20px、半透明白 15–30%、细边框）。
```css
.glass {
  background: rgba(255,255,255,0.65);
  backdrop-filter: blur(16px) saturate(140%);
  -webkit-backdrop-filter: blur(16px) saturate(140%);
  border: 1px solid rgba(255,255,255,0.7);
  box-shadow: var(--shadow-md);
}
```
- 浮层导航 / 横幅 / Hero 卡片用 `.glass`；**正文内容卡保持纯白 `#FFFFFF`**（对比与清晰度优先）。
- 文字在玻璃面上必须 ≥4.5:1（玻璃面下若为渐变底，需加深文字或加底纹）。

### Neumorphism（默认禁用）
用户原话提到"轻拟态（Neumorphism）或玻璃拟态的轻量化变体"。技能库明确标注 Neumorphism **对比度低（⚠ Low contrast）**，不利护眼。
**决策：默认禁用完整新拟态**；若需"轻量"立体感，仅允许在**无文字的装饰表面**用极淡 inset 阴影，且不得影响可读性。优先采用 Glassmorphism 轻量变体。

## 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 栏**（前台门户）或**左侧抽屉**（后台，因菜单项多）；主内容单列；触摸目标 ≥44px。
- 平板：sidebar 折叠 64px，悬停展开。
- 栅格在窄屏降列数（12→6→1）。
- 禁止横向滚动；表格在窄屏转卡片或横向滚动容器（包 `overflow-x-auto`）。
- 必须 `<meta name="viewport" content="width=device-width, initial-scale=1">`；固定导航需 `padding-top` 补偿高度，避免遮挡首屏内容。

## 10. SEO & GEO 规范（前台必须）

平台需"不推广也能被搜索引擎与各大模型联网搜索（GEO）发现"。

### 结构（语义化 HTML5）
- 每页一个 `<h1>`；区块用 `<section>` / `<article>`；技能卡用 `<article>` 包裹（标题 `<h2>`/`<h3>`）。
- 必须 `<meta name="viewport">`、`<title>`、`<meta name="description">`、Open Graph 标签。
- 前台用 `<header><nav><main><footer>` 语义骨架；后台为应用壳，SEO 权重低。

### 富媒体摘要（Rich Snippets / JSON-LD）
- 技能页 / 技能卡：`SoftwareApplication` schema，含 `aggregateRating`、`offers`（`price:0` / 订阅）、`downloadCount`。
- 技能市场：`BreadcrumbList`；痛点 / FAQ 区：`FAQPage`。
- 预留展示槽：评分星、价格、下载量在卡片右上角（Lucide 图标 + 数字，非 emoji）。

### 关键词突出（GEO 友好）
- 核心词「无限Token」「AI变现」「办公提效」「低成本养龙虾（= 低成本微调 / 托管模型）」用 `.kw` 样式（品牌色 + 600 字重）在首页价值区高亮。
- `.kw { color: var(--color-accent); font-weight:600; }`

### 技术
- `sitemap.xml` + `robots.txt`；技能详情独立可索引 URL；所有图片 `alt`。

## 11. 页面级布局总览（前台 + 后台）

> 详细页级 override 将在实际开发时落入 `design-system/pages/*.md`（Master + Overrides）。此处为总览与验收基准。

### 前台首页（Home）
1. 浮层玻璃顶栏（logo + 主导航 + 登录 / 注册）
2. Hero：轮播 Banner（技能广告位）+ 平台定位一句话 + 主 CTA
3. 平台定位区：图标 + 短文网格（痛点：API 贵 / Prompt 难调试 / 数据孤岛 / 无变现渠道）
4. 平台价值区：可视化数据点（低价订阅 / 无限 Token / 垂直办公模板 / 交易市场 / 低成本养龙虾）
5. 热门技能榜 Top5（排行榜 / 徽章）
6. Footer（SEO 链接 + 富媒体摘要）

### 技能市场（Skill Market）
- 顶部广告位 → 左侧筛选（分类 / 场景标签）→ 右侧卡片流（每排 5，图标 / 名称 / 简介 / 下载量）
- 分页：每页 100，上下翻页；每个技能 = `<article>` + JSON-LD

### 应用服务（Apps）
- 网格布局；每应用独立卡片（名称 / 介绍 / 「进入应用」按钮）

### 用户工作台（Workspace，登录后）
- 左侧固定导航：AI 聊天 / IM Bot（子：微信 / 企微 / 飞书 / QQ / 悟空 IM）/ 知识库 / 技能市场 / 应用服务 / Token 驾驶舱 / 会员订阅 / 进化看板 / 个人设置
- 右侧内容区留白；移动端导航转抽屉

### 后台数据驾驶舱（Admin Dashboard）
- 6 张 KPI 卡：总用户 / 7日活跃、模型统计（启用 / 全部）、对话统计（有效 / 活跃窗口）、知识库文档数、今日订阅（成功）、Token 消耗（今日 / 本周）
- 大模型消耗趋势（近 30 天 面积图）
- 操作日志 + 审计日志 双栏（每 20 条 / 页，可下载）
- 其余后台：AI 技能中心 / 平台运营 / 商业变现 / 系统管理（标准 B 端布局，侧栏分类清晰）

## 12. 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
grad    --gradient-brand (淡紫→淡青) / --gradient-brand-strong (靛蓝→青蓝 CTA)
glass   .glass (rgba(255,255,255,.65) + blur(16px) + 1px 白边)
kw      .kw 高亮关键词(无限Token/AI变现/办公提效)
```

**推荐 prompt 模板**
- "在七虎AI 中新增一个 [页面]，遵循 DESIGN.md 的 Warm Tech Minimalism 风格，品牌色用 #5B5FED，图标用 Lucide，间距用 token。"
- "把 [组件] 改成符合 DESIGN.md §4 的卡片规范，hover 用 --shadow-lg + translateY(-2px)。"
- "新增前台 [页面] 时遵循 DESIGN.md §10 的 SEO/GEO 规范：语义化 HTML5 + JSON-LD 富媒体摘要 + `.kw` 高亮核心词；Hero/Banner 可用 `.glass` 与 `--gradient-brand`。"