qyyfw/qihuaiflow
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e7dc9808c0daf511a3fe78e9e0404f7567fba295
qihuaiflow/DESIGN.md
T

10 KiB
Raw Blame History

七虎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)。"
Reference in new issue View Git Blame Copy Permalink