design-guide

Paperclip 设计指南

Paperclip 的 UI 是专业级控制平面——信息密集、以键盘操作为主，默认采用深色主题。每个像素都有其用处。

始终搭配使用： frontend-design（视觉润色）和 web-design-guidelines（Web 最佳实践）。

---

1. 设计原则

• 信息密集，但易于浏览。 无需点击即可呈现尽可能多的信息。留白用于分隔，而不是填充。
• 键盘优先。 全局快捷键（Cmd+K、C、[、]）。高级用户很少使用鼠标。
• 注重上下文，而非模态弹窗。 使用行内编辑，而不是对话框；使用下拉菜单，而不是页面跳转。
• 默认采用深色主题。 使用中性灰色（OKLCH），而非纯黑。强调色仅用于状态和优先级。文本是主要的视觉元素。
• 组件驱动。 优先使用能够体现样式约定的可复用组件。选择恰当的抽象粒度——既不要过于细碎，也不要过于庞大。

---

2. 技术栈

• React 19 + TypeScript + Vite
• 使用 CSS 变量的 Tailwind CSS v4（OKLCH 色彩空间）
• shadcn/ui（new-york 风格、中性色基底、启用 CSS 变量）
• Radix UI 基元（无障碍支持、焦点管理）
• Lucide React 图标（导航图标为 16px，行内图标为 14px）
• 使用 class-variance-authority（CVA）定义组件变体
• 通过 cn() 工具函数使用 clsx + tailwind-merge

配置：ui/components.json（别名：@/components、@/components/ui、@/lib、@/hooks）

---

3. 设计令牌

所有令牌均以 CSS 变量的形式定义在 ui/src/index.css 中。浅色和深色主题均使用 OKLCH。

颜色

使用语义化令牌名称，不要使用原始颜色值：

令牌	用途
--background / --foreground	页面背景和主要文本
--card / --card-foreground	卡片表面
--primary / --primary-foreground	主要操作、强调内容
--secondary / --secondary-foreground	次要表面
--muted / --muted-foreground	弱化文本、标签
--accent / --accent-foreground	悬停状态、当前导航项
--destructive	危险操作
--border	所有边框
--ring	焦点环
--sidebar-*	侧边栏专用变体
--chart-1 至 --chart-5	数据可视化

圆角

使用单一的 --radius 变量（0.625rem），并派生出以下尺寸：

• rounded-sm — 小型输入框、胶囊标签
• rounded-md — 按钮、输入框、小型组件
• rounded-lg — 卡片、对话框
• rounded-xl — 卡片容器、大型组件
• rounded-full — 徽章、头像、状态圆点

阴影

阴影应保持轻微：shadow-xs（轮廓按钮）、shadow-sm（卡片）。不要使用厚重的阴影。

---

4. 字体排印层级

使用以下精确样式模式，不要自行创造新的模式：

模式	类名	用途
页面标题	text-xl font-bold	页面顶部
分区标题	text-lg font-semibold	主要分区
分区小标题	text-sm font-semibold text-muted-foreground uppercase tracking-wide	设计指南、侧边栏中的分区标题
卡片标题	text-sm font-medium 或 text-sm font-semibold	卡片标题、列表项标题
正文	text-sm	默认正文文本
弱化文本	text-sm text-muted-foreground	描述、次要文本
微型标签	text-xs text-muted-foreground	元数据、时间戳、属性标签
等宽标识符	text-xs font-mono text-muted-foreground	问题键（PAP-001）、CSS 变量
大型统计数据	text-2xl font-bold	仪表板指标值
代码/日志	font-mono text-xs	日志输出、代码片段

---

5. 状态与优先级系统

状态颜色（所有实体保持一致）

在 StatusBadge.tsx 和 StatusIcon.tsx 中定义：

状态	颜色	实体类型
active、achieved、completed、succeeded、approved、done	绿色系	Agent、目标、问题、审批
running	青色	Agent
paused	橙色	Agent
idle、pending	黄色	Agent、审批
failed、error、rejected、blocked	红色系	运行、Agent、审批、问题
archived、planned、backlog、cancelled	中性灰	各类
todo	蓝色	问题
in_progress	靛蓝色	问题
in_review	紫罗兰色	问题

优先级图标

在 PriorityIcon.tsx 中定义：critical（红色/AlertTriangle）、high（橙色/ArrowUp）、medium（黄色/Minus）、low（蓝色/ArrowDown）。

Agent 状态圆点

行内彩色圆点：running（青色，animate-pulse）、active（绿色）、paused（黄色）、error（红色）、offline（中性）。

---

6. 组件层级

分为三个层级：

1. shadcn/ui 基础组件（ui/src/components/ui/）—— Button、Card、Input、Badge、Dialog、Tabs 等。不要直接修改这些组件；应通过组合进行扩展。
2. 自定义组合组件（ui/src/components/）—— StatusBadge、EntityRow、MetricCard 等。这些组件体现了 Paperclip 特有的设计语言。
3. 页面组件（ui/src/pages/）—— 将基础组件和组合组件组合成完整视图。

完整组件清单及使用指南请参阅 references/component-index.md。

何时创建新组件

在以下情况下创建可复用组件：

• 相同的视觉模式出现在 2 个或更多位置
• 该模式包含交互行为（状态更改、行内编辑）
• 该模式包含领域逻辑（状态颜色、优先级图标）

以下情况不要创建组件：

• 仅适用于单个页面的一次性布局
• 简单的 className 组合（直接使用 Tailwind）
• 没有增加语义价值的薄封装

---

7. 组合模式

这些模式描述组件如何协同工作。它们不一定是独立组件，但必须在整个应用中保持一致。

带状态和优先级的问题行

问题及类似实体的标准列表项：

<EntityRow
  leading={<><StatusIcon status="in_progress" /><PriorityIcon priority="high" /></>}
  identifier="PAP-001"
  title="Implement authentication flow"
  subtitle="Assigned to Agent Alpha"
  trailing={<StatusBadge status="in_progress" />}
  onClick={() => {}}
/>

前置槽位始终先放 StatusIcon，再放 PriorityIcon。后置槽位放 StatusBadge 或时间戳。

分组列表

按状态标题和实体行对问题进行分组：

<div className="flex items-center gap-2 px-4 py-2 bg-muted/50 rounded-t-md">
  <StatusIcon status="in_progress" />
  <span className="text-sm font-medium">In Progress</span>
  <span className="text-xs text-muted-foreground ml-1">2</span>
</div>
<div className="border border-border rounded-b-md">
  <EntityRow ... />
  <EntityRow ... />
</div>

属性行

属性面板中的键值对：

<div className="flex items-center justify-between py-1.5">
  <span className="text-xs text-muted-foreground">Status</span>
  <StatusBadge status="active" />
</div>

标签始终使用 text-xs text-muted-foreground，值靠右显示。将其放在带有 space-y-1 的容器中。

指标卡片网格

响应式网格中的仪表板指标：

<div className="grid md:grid-cols-2 xl:grid-cols-4 gap-4">
  <MetricCard icon={Bot} value={12} label="Active Agents" description="+3 this week" />
  ...
</div>

进度条（预算）

根据阈值设置颜色：绿色（<60%）、黄色（60-85%）、红色（>85%）：

<div className="w-full h-2 bg-muted rounded-full overflow-hidden">
  <div className="h-full rounded-full bg-green-400" style={{ width: `${pct}%` }} />
</div>

评论串

作者标题栏（姓名 + 时间戳）后接正文，置于带边框且使用 space-y-3 的卡片中。在下方添加评论文本区域和按钮。

费用表格

使用标准 <table>，设置 text-xs，标题行使用 bg-accent/20，数值使用 font-mono。

日志查看器

使用 bg-neutral-950 rounded-lg p-3 font-mono text-xs 容器。按级别为日志行着色：默认（前景色）、WARN（yellow-400）、ERROR（red-400）、SYS（blue-300）。流式传输时显示实时状态圆点。

---

8. 交互模式

悬停状态

• 实体行：hover:bg-accent/50
• 导航项：hover:bg-accent/50 hover:text-accent-foreground
• 当前导航项：bg-accent text-accent-foreground

焦点

focus-visible:ring-ring focus-visible:ring-[3px] —— 标准 Tailwind focus-visible 焦点环。

禁用状态

disabled:opacity-50 disabled:pointer-events-none

行内编辑

使用 InlineEditor 组件——点击文本进行编辑，按 Enter 保存，按 Escape 取消。

弹出选择器

StatusIcon 和 PriorityIcon 使用 Radix Popover 进行行内选择。对于任何点击后会打开选择器的属性，都遵循此模式。

9. 布局系统

在 Layout.tsx 中定义的三区域布局：

┌──────────┬──────────────────────────────┬──────────────────────┐
│ Sidebar  │  Breadcrumb bar              │                      │
│ (w-60)   ├──────────────────────────────┤  Properties panel    │
│          │  Main content (flex-1)       │  (w-80, optional)    │
└──────────┴──────────────────────────────┴──────────────────────┘

• 侧边栏：w-60，可折叠，包含 CompanySwitcher + SidebarSections
• 属性面板：w-80，在详情视图中显示，在列表视图中隐藏
• 主内容区：可滚动，flex-1

---

10. /design-guide 页面

位置：ui/src/pages/DesignGuide.tsx 路由：/design-guide

这是应用中所有组件和模式的动态展示页，也是界面外观的权威参考。

规则

1. **添加新的可复用组件时，必须将其添加到设计指南页面。**展示所有变体、尺寸和状态。
2. 修改现有组件的 API 时，更新其设计指南部分。
3. 添加新的组合模式时，添加一个展示该模式的章节。
4. 遵循现有结构：使用 <Section title="..."> 包装，并使用 <SubSection> 进行分组。
5. 按逻辑顺序排列章节：先介绍基础内容（颜色、字体排印），再介绍基本组件、复合组件，最后介绍模式。

添加新章节

<Section title="My New Component">
  <SubSection title="Variants">
    {/* Show all variants */}
  </SubSection>
  <SubSection title="Sizes">
    {/* Show all sizes */}
  </SubSection>
  <SubSection title="States">
    {/* Show interactive/disabled states */}
  </SubSection>
</Section>

---

11. 组件索引

完整组件清单请参阅 references/component-index.md。

创建新的可复用组件时：

1. 将其添加到组件索引参考文件
2. 将其添加到 /design-guide 页面
3. 遵循现有的命名和文件规范

---

12. 文件规范

• shadcn 基本组件：ui/src/components/ui/{component}.tsx — 小写，使用 kebab-case
• 自定义组件：ui/src/components/{ComponentName}.tsx — PascalCase
• 页面：ui/src/pages/{PageName}.tsx — PascalCase
• 实用工具：ui/src/lib/{name}.ts
• Hooks：ui/src/hooks/{useName}.ts
• API 模块：ui/src/api/{entity}.ts
• 上下文提供程序：ui/src/context/{Name}Context.tsx

所有组件都使用 @/lib/utils 中的 cn() 合并 className。具有多个视觉变体的组件都使用 CVA 定义变体。

---

13. 应避免的常见错误

• 使用原始的十六进制/RGB 颜色，而不是 CSS 变量令牌
• 不使用既定的字体排印比例，而是创建临时字体样式
• 硬编码状态颜色，而不是使用 StatusBadge/StatusIcon
• 在已有可复用组件的情况下，仍创建一次性样式元素
• 添加组件时未更新设计指南页面
• 使用 shadow-md 或更强的阴影 — 阴影应尽量轻微（仅 xs、sm）
• 使用 rounded-2xl 或更大的圆角 — 最大为 rounded-xl（药丸形元素的 rounded-full 除外）
• 忽略深色模式 — 始终使用语义令牌，绝不硬编码浅色/深色值