19 KiB

Raw Blame History

AgentKit 全局 UI/UX 规范

基于 Skymetrics / Twenty 风格参考图提炼，适用于 AgentKit Web GUI 与 Tauri 桌面端。目标：建立跨页面一致的设计语言，减少「风格不统一」「组件各行其是」的返工。

与 Bitable 多维表格 UI/UX 规范互补：本规范覆盖全局框架与通用组件，Bitable 规范覆盖表格细节。

1. 设计原则

克制用色：近黑/纯白做主色，彩色仅用于语义信号（成功、警告、错误、accent）。
大圆角、柔阴影：卡片与容器使用 12–16px 圆角；阴影极轻，主要靠背景层级区分。
密度适中：数据行 40–44px、表单控件 32–40px，避免信息拥挤。
对齐优先：所有列表、卡片、表格坚持统一的 12/16/24px 栅格与左对齐。
暗色原生：所有颜色使用 token，禁止硬编码；深色模式不是反色，而是独立灰阶。

2. 颜色系统

2.1 品牌色

Token	浅色值	深色值	用途
`--color-primary`	`#1a1a1a`	`#fbfbfa`	主按钮、关键文字、强调图标
`--color-primary-hover`	`#2f2f2f`	`#ededec`	主按钮 hover
`--color-primary-active`	`#000000`	`#ffffff`	主按钮 active
`--color-primary-bg`	`#fbfbfa`	`#1a1a1a`	反转背景

2.2 语义色

Token	浅色值	深色值	用途
`--color-success`	`#22c55e`	`#4ade80`	正向、上升、成功
`--color-success-light`	`#dcfce7`	`#14532d`	正向标签背景
`--color-warning`	`#f59e0b`	`#fbbf24`	警告、需注意
`--color-warning-light`	`#fef9c3`	`#422006`	警告标签背景
`--color-error`	`#ef4444`	`#f87171`	错误、下降、失败
`--color-error-light`	`#fee2e2`	`#450a0a`	错误标签背景
`--color-info`	`#3b82f6`	`#60a5fa`	信息、链接
`--color-info-light`	`#dbeafe`	`#172554`	信息标签背景

Dashboard 中的上升/下降指标统一使用绿色/红色，不得自定义其他正负色。

2.3 中性灰阶

Token	浅色值	深色值	用途
`--color-gray-50`	`#fbfbfa`	`#1a1a1a`	最浅背景
`--color-gray-100`	`#f7f7f5`	`#2f2f2f`	次级背景
`--color-gray-200`	`#ededec`	`#3a3a3a`	边框、分隔
`--color-gray-300`	`#dfdfde`	`#4a4a4a`	hover 边框
`--color-gray-400`	`#cececd`	`#6b6b6a`	禁用、次要图标
`--color-gray-500`	`#9b9b9a`	`#9b9b9a`	placeholder
`--color-gray-600`	`#6b6b6a`	`#b0b0af`	说明文字
`--color-gray-700`	`#4a4a4a`	`#cececd`	次级文字
`--color-gray-800`	`#2f2f2f`	`#ededec`	标题文字
`--color-gray-900`	`#1a1a1a`	`#fbfbfa`	主文字

2.4 背景层级

Token	浅色值	深色值	用途
`--bg-canvas`	`#f3f4f6`	`#111111`	页面画布（参考图浅灰/深黑）
`--bg-primary`	`#ffffff`	`#1a1a1a`	卡片、弹窗、输入框
`--bg-secondary`	`#fbfbfa`	`#1f1f1f`	次级卡片、sidebar
`--bg-tertiary`	`#f7f7f5`	`#2a2a2a`	hover、选中、第三层背景
`--bg-elevated`	`#ffffff`	`#252525`	浮层、下拉菜单

ponytail: --bg-canvas 是新增 token，用于替代当前页面背景 #f7f7f5 以贴近参考图冷灰。如一次性迁移成本高，可先在新建页面使用，旧页面逐步替换。

2.5 文字色

Token	浅色值	深色值	用途
`--text-primary`	`#1a1a1a`	`#fbfbfa`	标题、正文
`--text-secondary`	`#4a4a4a`	`#cececd`	次级说明
`--text-tertiary`	`#6b6b6a`	`#9b9b9a`	图标、辅助文字
`--text-placeholder`	`#9b9b9a`	`#6b6b6a`	placeholder、禁用
`--text-inverse`	`#ffffff`	`#1a1a1a`	深色背景上的文字

2.6 边框

Token	浅色值	深色值	用途
`--border-color`	`#ededec`	`#3a3a3a`	默认分隔线
`--border-color-hover`	`#dfdfde`	`#4a4a4a`	hover 边框
`--border-color-strong`	`#e0e0e0`	`#555555`	表格列分隔等需要更明显的地方
`--border-color-active`	`var(--color-primary)`	`var(--color-primary)`	聚焦/激活边框

3. 字体与排版

3.1 字体栈

--font-sans: -apple-system, BlinkMacSystemFont, 'Inter', 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
--font-mono: 'SF Mono', 'Fira Code', Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;

全局默认使用 --font-sans，代码块使用 --font-mono。

3.2 字号规范

Token	大小	行高	用途
`--font-xs`	12px	1.5	辅助说明、时间戳、徽章
`--font-sm`	13px	1.5	表单标签、表格列头、小按钮
`--font-base`	14px	1.5	正文、列表、输入框
`--font-md`	16px	1.5	小标题、 emphasized 正文
`--font-lg`	20px	1.3	页面/卡片标题
`--font-xl`	24px	1.25	大标题、Dashboard 主指标
`--font-2xl`	32px	1.2	超大指标（如 €123,927.85）

3.3 字重规范

Token	值	用途
`--font-weight-normal`	400	正文
`--font-weight-medium`	500	列头、按钮、强调
`--font-weight-semibold`	600	页面标题、数字指标
`--font-weight-bold`	700	极少使用，仅用于营销/关键数据

4. 间距系统

Token	值	用途
`--space-1`	4px	图标与文字间距、紧凑内边距
`--space-2`	8px	按钮内部、小间距
`--space-3`	12px	卡片内边距、列表项间距
`--space-4`	16px	默认卡片内边距、表单间距
`--space-5`	20px	大卡片内边距
`--space-6`	24px	区块间距、页面边距
`--space-8`	32px	大区块间距
`--space-10`	40px	页面级间距
`--space-12`	48px	超大间距

页面边距统一使用 --space-6（24px），卡片内部默认 --space-4（16px）。

5. 圆角系统

Token	值	用途
`--radius-sm`	4px	小标签、小按钮
`--radius-md`	6px	输入框、小卡片
`--radius-lg`	10px	按钮、弹窗
`--radius-xl`	14px	大输入框、聊天框
`--radius-2xl`	16px	卡片、大容器
`--radius-card`	12px	通用卡片（保留旧 token 兼容）
`--radius-full`	9999px	pill、头像、状态点

参考图中大卡片圆角约 14–16px，聊天输入框圆角约 16px，发送按钮为圆形。

6. 阴影系统

参考图阴影极轻，主要靠背景层级和 1px 边框区分。

Token	值	用途
`--shadow-none`	`none`	扁平卡片
`--shadow-sm`	`0 1px 2px rgba(0, 0, 0, 0.04)`	轻微抬升
`--shadow-md`	`0 2px 8px rgba(0, 0, 0, 0.06), 0 1px 2px rgba(0, 0, 0, 0.04)`	下拉、浮层
`--shadow-lg`	`0 4px 16px rgba(0, 0, 0, 0.06), 0 2px 4px rgba(0, 0, 0, 0.04)`	弹窗、抽屉
`--shadow-card`	`0 1px 3px rgba(0, 0, 0, 0.04), 0 0 0 1px rgba(0, 0, 0, 0.04)`	卡片（带 1px 描边感）

Dashboard 卡片优先使用 --shadow-none 或 --shadow-sm，配合 --bg-primary 与 --bg-canvas 的层级差。

7. 布局框架

7.1 应用级布局

┌─────────────────────────────────────────────┐
│ Sidebar (240–260px) │ Header (56–64px)      │
│                     ├───────────────────────┤
│                     │ Content (bg-canvas)   │
│                     │                       │
└─────────────────────────────────────────────┘

Token	值	用途
`--sidebar-width`	240px	左侧导航宽度
`--sidebar-collapsed-width`	64px	折叠后宽度
`--header-height`	56px	顶部栏高度
`--topnav-height`	48px	顶部小导航高度

7.2 Sidebar 规范

宽度 240px，背景 --bg-secondary（浅色）或 --bg-canvas（深色）。
Logo 区高度 56–64px，与 header 对齐。
导航项高度 40px，圆角 8px，内边距 8px 12px。
默认状态：color: var(--text-secondary)。
Hover：background: var(--bg-tertiary)。
Active：background: var(--bg-tertiary); color: var(--text-primary); font-weight: 500。
当前项左侧可加 3px 品牌色条作为视觉锚点（可选）。

7.3 Header 规范

高度 56px，背景 --bg-primary。
左侧为页面标题，字号 --font-lg（20px），字重 500。
右侧放置筛选器、工作区切换、用户头像等操作。
与 content 之间用 1px --border-color 分隔。

7.4 Content 规范

背景 --bg-canvas。
页面内边距 --space-6（24px）。
卡片网格：默认 gap --space-4（16px），Dashboard 大卡片可用 --space-5（20px）。

8. 组件规范

8.1 Card 卡片

背景 --bg-primary。
圆角 --radius-2xl（16px），必要时回退 --radius-card（12px）。
内边距：--space-5（20px）用于 Dashboard 大卡片；--space-4（16px）用于普通卡片。
阴影：--shadow-none 或 --shadow-sm。
标题：字号 --font-md（16px），字重 500，颜色 --text-primary。
副标题/说明：字号 --font-xs（12px），颜色 --text-tertiary。

Metric Card 指标卡

指标数字：字号 --font-2xl（32px），字重 600。
指标标签：字号 --font-sm（13px），颜色 --text-tertiary。
环比徽章：pill 形状，绿色/红色背景，文字与背景同色系深色/浅色。
单位与货币使用 --font-sm 与主数字保持同一行基线。

8.2 Chat 聊天

消息气泡

用户消息：右对齐，背景 --bg-primary（白色），文字 --text-primary。
AI 消息：左对齐，背景 --bg-secondary（浅灰/灰底），文字 --text-primary。
圆角 12px，内边距 12px 16px。
最大宽度 80%，单条消息宽度按内容自适应（而非固定宽度）。

输入框

底部固定，背景 --bg-primary。
输入区域：圆角 --radius-2xl（16px），边框 1px --border-color。
左侧显示「AI Assistant」标识或当前技能 pill。
发送按钮：圆形，直径 32–36px，背景 --color-primary，图标白色。

快捷操作

以卡片形式展示在输入框上方，3 列网格。
卡片圆角 --radius-xl（14px），hover 边框变为 --border-color-hover。

8.3 Button 按钮

类型	背景	文字	边框	圆角	高度
Primary	`--color-primary`	`--text-inverse`	none	`--radius-lg`	32px
Secondary	`--bg-primary`	`--text-primary`	1px `--border-color`	`--radius-lg`	32px
Ghost	transparent	`--text-secondary`	none	`--radius-md`	24px
Icon	`--bg-secondary`	`--text-secondary`	1px `--border-color`	`--radius-md`	28px

当前参考图中发送按钮为圆形 icon button，直径 32–36px。

8.4 Input 输入框

高度 40px（标准）/ 32px（紧凑）。
背景 --bg-primary。
边框 1px --border-color，圆角 --radius-md（6px）。
Focus：border-color: var(--border-color-active)，无发光阴影。
Placeholder：var(--text-placeholder)。

8.5 Table 表格

详见 Bitable 多维表格 UI/UX 规范。核心摘要：

行高 44px，列头高 40px。
列头背景 --bg-secondary，下边框 1px --border-color-strong。
数据单元格右边框 1px --border-color。
Select/Multiselect 渲染为 pill chip。
主字段列 hover 下划线。

8.6 Tag / Badge 标签

默认 pill 圆角（--radius-full）。
内边距 2px 10px（小）/ 4px 12px（标准）。
高度 20px（小）/ 24px（标准）。
状态色：success / warning / error / info，使用对应 --color-*-light 背景与 --color-* 文字/边框。

背景 --bg-elevated。
圆角 --radius-lg（10px）。
阴影 --shadow-lg。
选项 hover：--bg-tertiary。
选中项：--bg-secondary，文字 --text-primary。

9. 数据可视化

9.1 图表配色

Token	浅色值	深色值	用途
`--data-viz-primary`	`#22c55e`	`#4ade80`	主折线/主柱状
`--data-viz-secondary`	`#6b6b6a`	`#9b9b9a`	对比线、辅助线
`--data-viz-positive`	`#22c55e`	`#4ade80`	上升、完成
`--data-viz-negative`	`#ef4444`	`#f87171`	下降、异常
`--data-viz-neutral`	`#9b9b9a`	`#6b6b6a`	中性数据
`--data-viz-palette-1`	`#22c55e`	`#4ade80`	分类色 1
`--data-viz-palette-2`	`#3b82f6`	`#60a5fa`	分类色 2
`--data-viz-palette-3`	`#f59e0b`	`#fbbf24`	分类色 3
`--data-viz-palette-4`	`#a855f7`	`#c084fc`	分类色 4
`--data-viz-palette-5`	`#ec4899`	`#f472b6`	分类色 5

9.2 图表样式

坐标轴与网格线使用 --border-color。
标签文字使用 --text-tertiary，字号 12px。
Tooltip 背景 --bg-elevated，圆角 --radius-md，阴影 --shadow-lg。
折线图点 hover 放大 1.5 倍，显示当前数值。

10. 暗色 / 浅色主题

所有组件必须通过 CSS 变量切换，禁止在 JS 中写死颜色。
深色模式不是简单反色：背景层级从 #111111 到 #252525，文字从 #fbfbfa 到 #9b9b9a。
阴影在深色模式下应更暗、更柔和。
切换主题时，同步设置 data-theme="dark" 到 html 或 body。

11. 动效与交互

过渡时长：--transition-fast 150ms、--transition-normal 200ms、--transition-slow 300ms。
hover 背景/边框变化使用 ease 缓动。
按钮 active 轻微缩放 0.98（可选）。
禁止无意义的弹跳、闪烁动画。

12. 响应式断点

Token	断点	行为
`--breakpoint-sm`	640px	手机，sidebar 变为抽屉
`--breakpoint-md`	768px	平板，卡片两列
`--breakpoint-lg`	1024px	小桌面，三列卡片
`--breakpoint-xl`	1280px	大桌面，完整布局

14. 组件库（components/ui）

为避免每个页面重复写样式，项目提供了一组基于本规范的通用 UI 组件。新增页面应优先使用这些组件，而不是在页面内手写卡片/标题/指标样式。

14.1 可用组件

组件	路径	用途
`UiCard`	`components/ui/UiCard.vue`	通用卡片容器
`UiMetricCard`	`components/ui/UiMetricCard.vue`	Dashboard 指标卡
`UiTrendBadge`	`components/ui/UiTrendBadge.vue`	趋势徽章（↑/↓/−）
`UiPageHeader`	`components/ui/UiPageHeader.vue`	页面顶部标题栏
`UiPageShell`	`components/ui/UiPageShell.vue`	页面外壳（Header + Content）

统一从 components/ui/index.ts 导出：

import { UiCard, UiMetricCard, UiPageShell, UiTrendBadge } from '@/components/ui'

14.2 UiCard

<UiCard title="卡片标题" subtitle="辅助说明">
  内容区域
  <template #extra>
    <a-button type="link">查看更多</a-button>
  </template>
</UiCard>

Props：

Prop	类型	默认值	说明
`title`	`string`	—	卡片标题
`subtitle`	`string`	—	标题下方小字
`padding`	`'sm' \| 'md' \| 'lg'`	`'md'`	内边距
`shadow`	`'none' \| 'sm'`	`'none'`	阴影
`hoverable`	`boolean`	`false`	hover 抬升效果

14.3 UiMetricCard

<UiMetricCard
  label="总销售额"
  value="25430"
  prefix="$"
  :trend="7.5"
  trend-label="较上月"
  caption="过去 30 天"
  hoverable
  @click="openDetail"
/>

Props：

Prop	类型	默认值	说明
`label`	`string`	必填	指标名称
`value`	`string \| number`	必填	指标值
`prefix`	`string`	—	前缀（如 $、€）
`suffix`	`string`	—	后缀（如 %）
`caption`	`string`	—	底部说明
`trend`	`number`	—	趋势百分比（正绿负红）
`trendLabel`	`string`	—	趋势标签
`hoverable`	`boolean`	`false`	是否可点击

14.4 UiPageShell

<UiPageShell title="General metrics" subtitle="实时数据概览">
  <template #header-extra>
    <a-select :options="dateRanges" />
    <a-button type="primary">导出</a-button>
  </template>

  <div class="metric-grid">
    <UiMetricCard label="Profit Margin" value="123927.85" prefix="€" :trend="38" />
    <UiMetricCard label="Orders" value="2792" :trend="11" />
    <!-- ... -->
  </div>
</UiPageShell>

Props：同 UiPageHeader（title、subtitle、back）。

14.5 页面迁移示例

Before（每个页面各自写样式）：

<template>
  <div class="my-page">
    <div class="my-page__header">
      <h1>页面标题</h1>
    </div>
    <div class="my-page__cards">
      <a-card class="my-card">...</a-card>
      <a-card class="my-card">...</a-card>
    </div>
  </div>
</template>

<style scoped>
.my-page { padding: 24px; background: #f7f7f5; }
.my-page__header { margin-bottom: 16px; }
.my-page__header h1 { font-size: 20px; font-weight: 500; }
.my-card { border-radius: 16px; }
</style>

After（使用 UI 组件）：

<template>
  <UiPageShell title="页面标题">
    <div class="my-page__cards">
      <UiCard title="卡片 A">...</UiCard>
      <UiCard title="卡片 B">...</UiCard>
    </div>
  </UiPageShell>
</template>

<style scoped>
.my-page__cards {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: var(--space-4, 16px);
}
</style>

ponytail: 组件只负责「外观规范」，布局（grid/flex）仍由页面决定，避免组件过度封装。

15. 检查清单（Code Review 用）

新增/修改页面或组件时逐项确认：

是否全部使用 --* token，无硬编码 hex
新增页面是否优先使用 components/ui 组件
页面背景是否使用 --bg-canvas
卡片背景是否使用 --bg-primary，圆角是否 ≥ 12px
阴影是否克制（优先 --shadow-none / --shadow-sm）
文字层级是否使用 --text-primary/secondary/tertiary
按钮高度是否为 32px/40px，圆角是否一致
表单输入框高度是否为 40px（标准）
表格是否遵循 Bitable 规范
聊天消息气泡是否有明确用户/AI 区分
Dashboard 指标卡数字是否使用 --font-2xl
正向/负向数据是否使用绿色/红色语义色
深色模式下颜色是否自然（非简单反色）
动效是否克制，过渡时长是否使用 token

19 KiB Raw Blame History Unescape Escape

AgentKit 全局 UI/UX 规范

1. 设计原则

2. 颜色系统

2.1 品牌色

2.2 语义色

2.3 中性灰阶

2.4 背景层级

2.5 文字色

2.6 边框

3. 字体与排版

3.1 字体栈

3.2 字号规范

3.3 字重规范

4. 间距系统

5. 圆角系统

6. 阴影系统

7. 布局框架

7.1 应用级布局

7.2 Sidebar 规范

7.3 Header 规范

7.4 Content 规范

8. 组件规范

8.1 Card 卡片

Metric Card 指标卡

8.2 Chat 聊天

消息气泡

输入框

快捷操作

8.3 Button 按钮

8.4 Input 输入框

8.5 Table 表格

8.6 Tag / Badge 标签

8.7 Dropdown / Select

9. 数据可视化

9.1 图表配色

9.2 图表样式

10. 暗色 / 浅色主题

11. 动效与交互

12. 响应式断点

14. 组件库（components/ui）

14.1 可用组件

14.2 UiCard

14.3 UiMetricCard

14.4 UiPageShell

14.5 页面迁移示例

15. 检查清单（Code Review 用）

19 KiB

Raw Blame History