From e7dc9808c0daf511a3fe78e9e0404f7567fba295 Mon Sep 17 00:00:00 2001 From: qyyfw Date: Mon, 13 Jul 2026 09:10:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B2=89=E6=B7=80=E4=B8=83=E8=99=8EAI?= =?UTF-8?q?=20=E8=AE=BE=E8=AE=A1=E7=B3=BB=E7=BB=9F(DESIGN.md/MASTER.md/.im?= =?UTF-8?q?peccable.md)=20=E4=BD=9C=E4=B8=BAUI=E5=8D=95=E4=B8=80=E4=BA=8B?= =?UTF-8?q?=E5=AE=9E=E6=BA=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .impeccable.md | 29 ++++++ DESIGN.md | 189 ++++++++++++++++++++++++++++++++++++ design-system/MASTER.md | 206 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 424 insertions(+) create mode 100644 .impeccable.md create mode 100644 DESIGN.md create mode 100644 design-system/MASTER.md diff --git a/.impeccable.md b/.impeccable.md new file mode 100644 index 0000000..0a9cf42 --- /dev/null +++ b/.impeccable.md @@ -0,0 +1,29 @@ +# .impeccable.md — 七虎AI 设计上下文 + +本文件为 `impeccable` 技能提供项目级设计上下文。完整规范见 **`DESIGN.md`**（单一事实源）与 `design-system/MASTER.md`。 + +## Audience & Use Case +七虎 AI 是面向企业与开发者的 **AI PaaS 平台**：智能体编排、技能/市场、模型库、工作流、IM Bot（个人微信）。使用者是开发者与运营人员，需要高密度、可信、精密的控制台界面。 + +## Brand & Tone +- **风格**：温暖科技感 + 极简主义（Warm Tech Minimalism）。 +- **唯一品牌色**：靛蓝 `#5B5FED`（hover `#4A4ECC`，浅底 `#EEEDFF`）。语义色仅表状态（成功 `#219B5E` / 警告 `#E8922C` / 错误 `#D9383A` / 信息 `#3B82F6`）。 +- **基调**：专业、可信、有温度；留白与柔和阴影营造呼吸感；动效克制（150–300ms）。 + +## Tech & Constraints +- 前端：React 18 + TypeScript + Vite 5，HashRouter，浅色主题。 +- 设计 token 全在 `frontend/src/styles/global.css` 的 `:root`（颜色/间距/圆角/字体/阴影）。**新增视觉必须先加 token，禁止散落 hex。** +- 字体：Inter（文本）+ JetBrains Mono（代码/ID/参数）。 +- 图标：**Lucide**，禁止 emoji 当图标。 +- 布局：左侧 sidebar（240/折叠64）+ 顶 header（56）+ 主内容区；详情用右侧 drawer。 + +## Build & Verify（交付铁律） +1. 改完 `frontend/src` 后必须在容器内 `npm run build`。 +2. 校验新 `dist` 确实含改动（grep 标记或构建日志），再请用户**硬刷新验收**。 +3. 每轮收工：`git commit + push` 到 `git.qihuyun.com`，并 `docker commit` 同名镜像（`qihuaiflow:with-deps`）+ 备份上一版，确保容器重建不丢。 + +## Quality Bar（impeccable 验收） +- 所有可点击元素有 `cursor:pointer` + hover + 可见 focus 环。 +- 对比度 ≥4.5:1；尊重 `prefers-reduced-motion`。 +- 响应式：375 / 768 / 1024 / 1440；无横向滚动。 +- 不引入第二品牌色、不用 emoji 图标、不用布局位移的 scale hover。 diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..0db1244 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,189 @@ +# 七虎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)。" diff --git a/design-system/MASTER.md b/design-system/MASTER.md new file mode 100644 index 0000000..288c1b8 --- /dev/null +++ b/design-system/MASTER.md @@ -0,0 +1,206 @@ +# Design System Master File + +> **LOGIC:** When building a specific page, first check `design-system/pages/[page-name].md`. +> If that file exists, its rules **override** this Master file. +> If not, strictly follow the rules below. + +--- + +**Project:** 七虎AI +**Generated:** 2026-07-13 09:07:15 +**Category:** AI PaaS Platform / Developer Console + +--- + +## Global Rules + +### Color Palette + +| Role | Hex | CSS Variable | +|------|-----|--------------| +| Primary | `#5B5FED` | `--color-primary` | +| Secondary | `#3B82F6` | `--color-secondary` | +| CTA/Accent | `#5B5FED` | `--color-cta` | +| Background | `#F8F9FB` | `--color-background` | +| Text | `#101214` | `--color-text` | + +**Color Notes:** Indigo #5B5FED is the single brand hue. Success #219B5E / Warning #E8922C / Error #D9383A / Info #3B82F6 are semantic only. Do not introduce extra brand colors. + +### Typography + +- **Heading Font:** Inter +- **Body Font:** Inter +- **Mood:** neutral, precise, technical +- **Google Fonts:** [Inter + Inter](https://fonts.google.com/share?selection.family=Inter:wght@300;400;500;600;700;800;900|JetBrains+Mono:wght@400;500;600) + +**CSS Import:** +```css +@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'); +``` + +### Spacing Variables + +| Token | Value | Usage | +|-------|-------|-------| +| `--space-xs` | `4px` / `0.25rem` | Tight gaps | +| `--space-sm` | `8px` / `0.5rem` | Icon gaps, inline spacing | +| `--space-md` | `16px` / `1rem` | Standard padding | +| `--space-lg` | `24px` / `1.5rem` | Section padding | +| `--space-xl` | `32px` / `2rem` | Large gaps | +| `--space-2xl` | `48px` / `3rem` | Section margins | +| `--space-3xl` | `64px` / `4rem` | Hero padding | + +### Shadow Depths + +| Level | Value | Usage | +|-------|-------|-------| +| `--shadow-sm` | `0 1px 2px rgba(0,0,0,0.05)` | Subtle lift | +| `--shadow-md` | `0 4px 6px rgba(0,0,0,0.1)` | Cards, buttons | +| `--shadow-lg` | `0 10px 15px rgba(0,0,0,0.1)` | Modals, dropdowns | +| `--shadow-xl` | `0 20px 25px rgba(0,0,0,0.15)` | Hero images, featured cards | + +--- + +## Component Specs + +### Buttons + +```css +/* Primary Button */ +.btn-primary { + background: #5B5FED; + color: white; + padding: 12px 24px; + border-radius: 8px; + font-weight: 600; + transition: all 200ms ease; + cursor: pointer; +} + +.btn-primary:hover { + opacity: 0.9; + transform: translateY(-1px); +} + +/* Secondary Button */ +.btn-secondary { + background: transparent; + color: #5B5FED; + border: 2px solid #5B5FED; + padding: 12px 24px; + border-radius: 8px; + font-weight: 600; + transition: all 200ms ease; + cursor: pointer; +} +``` + +### Cards + +```css +.card { + background: #F8F9FB; + border-radius: 12px; + padding: 24px; + box-shadow: var(--shadow-md); + transition: all 200ms ease; + cursor: pointer; +} + +.card:hover { + box-shadow: var(--shadow-lg); + transform: translateY(-2px); +} +``` + +### Inputs + +```css +.input { + padding: 12px 16px; + border: 1px solid #E2E8F0; + border-radius: 8px; + font-size: 16px; + transition: border-color 200ms ease; +} + +.input:focus { + border-color: #5B5FED; + outline: none; + box-shadow: 0 0 0 3px #5B5FED20; +} +``` + +### Modals + +```css +.modal-overlay { + background: rgba(0, 0, 0, 0.5); + backdrop-filter: blur(4px); +} + +.modal { + background: white; + border-radius: 16px; + padding: 32px; + box-shadow: var(--shadow-xl); + max-width: 500px; + width: 90%; +} +``` + +--- + +## Style Guidelines + +**Style:** Warm Tech Minimalism + +**Keywords:** clean, precise, data-dense, soft surfaces, indigo accent, generous whitespace + +**Best For:** AI PaaS consoles, developer platforms, agent/workflow editors + +**Key Effects:** Subtle hover lift (translateY -1 to -2px), 150-300ms ease transitions, soft shadow escalation, skeleton shimmer for loading, fade/slide micro-entrances. + +### Page Pattern + +**Pattern Name:** App Shell + Dashboard Grid + +- **Conversion Strategy:** Core value shown immediately via workspace/chat; primary action (新建对话/部署) persistent in header and sidebar. +- **CTA Placement:** Sticky header + sidebar primary action; contextual CTAs inside cards. +- **Section Order:** Sidebar > Workspace(Chat/Agents/Skills/MCP) > Main content grid > Detail drawer + +--- + +## Anti-Patterns (Do NOT Use) + +- ❌ Ornate decoration +- ❌ Low contrast text +- ❌ Missing focus states +- ❌ Emojis as icons +- ❌ Layout-shifting scale hovers +- ❌ Instant state changes + +### Additional Forbidden Patterns + +- ❌ **Emojis as icons** — Use SVG icons (Heroicons, Lucide, Simple Icons) +- ❌ **Missing cursor:pointer** — All clickable elements must have cursor:pointer +- ❌ **Layout-shifting hovers** — Avoid scale transforms that shift layout +- ❌ **Low contrast text** — Maintain 4.5:1 minimum contrast ratio +- ❌ **Instant state changes** — Always use transitions (150-300ms) +- ❌ **Invisible focus states** — Focus states must be visible for a11y + +--- + +## Pre-Delivery Checklist + +Before delivering any UI code, verify: + +- [ ] No emojis as icons (use SVG: Heroicons/Lucide) +- [ ] cursor-pointer on all clickable elements +- [ ] Hover states with smooth transitions (150-300ms) +- [ ] Light mode: text contrast 4.5:1 minimum +- [ ] Focus states visible for keyboard nav +- [ ] prefers-reduced-motion respected +- [ ] Responsive: 375px, 768px, 1024px, 1440px +- [ ] No content hidden behind fixed navbars +- [ ] No horizontal scroll on mobile