design-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paperclip Design Guide

Paperclip设计指南

Paperclip's UI is a professional-grade control plane — dense, keyboard-driven, dark-themed by default. Every pixel earns its place.

Always use with:

frontend-design

(visual polish) and

web-design-guidelines

(web best practices).

Paperclip的UI是专业级别的控制平面——信息密度高、以键盘操作为核心、默认采用深色主题。每一个像素都有其存在的意义。

请始终结合以下技能使用：

frontend-design

（视觉优化）和

web-design-guidelines

（Web最佳实践）。

1. Design Principles

1. 设计原则

Dense but scannable. Maximum information without clicks to reveal. Whitespace separates, not pads.
Keyboard-first. Global shortcuts (Cmd+K, C, [, ]). Power users rarely touch the mouse.
Contextual, not modal. Inline editing over dialog boxes. Dropdowns over page navigations.
Dark theme default. Neutral grays (OKLCH), not pure black. Accent colors for status/priority only. Text is the primary visual element.
Component-driven. Prefer reusable components that capture style conventions. Build at the right abstraction — not too granular, not too monolithic.

高密度但易扫描：无需点击展开即可呈现最大信息量。留白用于区分内容，而非填充空间。
键盘优先：全局快捷键（Cmd+K、C、[、]）。高级用户几乎无需使用鼠标。
上下文式而非模态式：优先使用内联编辑，而非对话框；优先使用下拉菜单，而非页面跳转。
默认深色主题：使用中性灰色（OKLCH色彩空间），而非纯黑色。仅将强调色用于状态/优先级标识。文本是主要视觉元素。
组件驱动：优先选用可复用组件来承载样式规范。以合适的抽象层级构建组件——既不过于细碎，也不过于庞大。

2. Tech Stack

2. 技术栈

React 19 + TypeScript + Vite
Tailwind CSS v4 with CSS variables (OKLCH color space)
shadcn/ui (new-york style, neutral base, CSS variables enabled)
Radix UI primitives (accessibility, focus management)
Lucide React icons (16px nav, 14px inline)
class-variance-authority (CVA) for component variants
clsx + tailwind-merge via
```
cn()
```
utility

Config:

ui/components.json

(aliases:

@/components

@/components/ui

@/lib

@/hooks

)

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

配置文件：

ui/components.json

（别名：

@/components

、

@/components/ui

、

@/lib

、

@/hooks

）

3. Design Tokens

3. 设计令牌

All tokens defined as CSS variables in

ui/src/index.css

. Both light and dark themes use OKLCH.

所有令牌均在

ui/src/index.css

中定义为CSS变量。浅色和深色主题均使用OKLCH色彩空间。

Colors

颜色

Use semantic token names, never raw color values:

Token	Usage
`--background` / `--foreground`	Page background and primary text
`--card` / `--card-foreground`	Card surfaces
`--primary` / `--primary-foreground`	Primary actions, emphasis
`--secondary` / `--secondary-foreground`	Secondary surfaces
`--muted` / `--muted-foreground`	Subdued text, labels
`--accent` / `--accent-foreground`	Hover states, active nav items
`--destructive`	Destructive actions
`--border`	All borders
`--ring`	Focus rings
`--sidebar-*`	Sidebar-specific variants
`--chart-1` through `--chart-5`	Data visualization

使用语义化令牌名称，切勿直接使用原始颜色值：

令牌	用途
`--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

圆角

Single

--radius

variable (0.625rem) with derived sizes:

```
rounded-sm
```
— small inputs, pills
```
rounded-md
```
— buttons, inputs, small components
```
rounded-lg
```
— cards, dialogs
```
rounded-xl
```
— card containers, large components
```
rounded-full
```
— badges, avatars, status dots

单一

--radius

变量（0.625rem），衍生出以下尺寸：

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

Shadows

阴影

Minimal shadows:

shadow-xs

(outline buttons),

shadow-sm

(cards). No heavy shadows.

使用极简阴影：

shadow-xs

（轮廓按钮）、

shadow-sm

（卡片）。禁止使用厚重阴影。

4. Typography Scale

4. 排版规范

Use these exact patterns — do not invent new ones:

Pattern	Classes	Usage
Page title	`text-xl font-bold`	Top of pages
Section title	`text-lg font-semibold`	Major sections
Section heading	`text-sm font-semibold text-muted-foreground uppercase tracking-wide`	Section headers in design guide, sidebar
Card title	`text-sm font-medium` or `text-sm font-semibold`	Card headers, list item titles
Body	`text-sm`	Default body text
Muted	`text-sm text-muted-foreground`	Descriptions, secondary text
Tiny label	`text-xs text-muted-foreground`	Metadata, timestamps, property labels
Mono identifier	`text-xs font-mono text-muted-foreground`	Issue keys (PAP-001), CSS vars
Large stat	`text-2xl font-bold`	Dashboard metric values
Code/log	`font-mono text-xs`	Log output, code snippets

请严格遵循以下样式，切勿自行创建新样式：

样式模式	类名	用途
页面标题	`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. Status & Priority Systems

5. 状态与优先级系统

Status Colors (consistent across all entities)

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

Defined in

StatusBadge.tsx

and

StatusIcon.tsx

Status	Color	Entity types
active, achieved, completed, succeeded, approved, done	Green shades	Agents, goals, issues, approvals
running	Cyan	Agents
paused	Orange	Agents
idle, pending	Yellow	Agents, approvals
failed, error, rejected, blocked	Red shades	Runs, agents, approvals, issues
archived, planned, backlog, cancelled	Neutral gray	Various
todo	Blue	Issues
in_progress	Indigo	Issues
in_review	Violet	Issues

定义于

StatusBadge.tsx

和

StatusIcon.tsx

：

状态	颜色	实体类型
active、achieved、completed、succeeded、approved、done	绿色系	智能体（Agents）、目标、问题、审批
running	青色	智能体（Agents）
paused	橙色	智能体（Agents）
idle、pending	黄色	智能体（Agents）、审批
failed、error、rejected、blocked	红色系	运行任务、智能体、审批、问题
archived、planned、backlog、cancelled	中性灰色	多种实体
todo	蓝色	问题
in_progress	靛蓝色	问题
in_review	紫色	问题

Priority Icons

优先级图标

Defined in

PriorityIcon.tsx

: critical (red/AlertTriangle), high (orange/ArrowUp), medium (yellow/Minus), low (blue/ArrowDown).

定义于

PriorityIcon.tsx

：critical（红色/AlertTriangle）、high（橙色/ArrowUp）、medium（黄色/Minus）、low（蓝色/ArrowDown）。

Agent Status Dots

智能体状态点

Inline colored dots: running (cyan, animate-pulse), active (green), paused (yellow), error (red), offline (neutral).

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

6. Component Hierarchy

6. 组件层级

Three tiers:

shadcn/ui primitives (
```
ui/src/components/ui/
```
) — Button, Card, Input, Badge, Dialog, Tabs, etc. Do not modify these directly; extend via composition.
Custom composites (
```
ui/src/components/
```
) — StatusBadge, EntityRow, MetricCard, etc. These capture Paperclip-specific design language.
Page components (
```
ui/src/pages/
```
) — Compose primitives and composites into full views.

See references/component-index.md for the complete component inventory with usage guidance.

分为三层：

shadcn/ui基础组件（
```
ui/src/components/ui/
```
）—— Button、Card、Input、Badge、Dialog、Tabs等。请勿直接修改这些组件；通过组合方式扩展。
自定义复合组件（
```
ui/src/components/
```
）—— StatusBadge、EntityRow、MetricCard等。这些组件承载Paperclip专属的设计语言。
页面组件（
```
ui/src/pages/
```
）—— 将基础组件与复合组件组合成完整视图。

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

When to Create a New Component

何时创建新组件

Create a reusable component when:

The same visual pattern appears in 2+ places
The pattern has interactive behavior (status changing, inline editing)
The pattern encodes domain logic (status colors, priority icons)

Do NOT create a component for:

One-off layouts specific to a single page
Simple className combinations (use Tailwind directly)
Thin wrappers that add no semantic value

当满足以下条件时，创建可复用组件：

同一视觉模式出现在2个及以上位置
该模式包含交互行为（状态切换、内联编辑）
该模式承载领域逻辑（状态颜色、优先级图标）

请勿创建组件的场景：

仅适用于单个页面的一次性布局
简单的类名组合（直接使用Tailwind即可）
无语义价值的轻量包装器

7. Composition Patterns

7. 组合模式

These patterns describe how components work together. They may not be their own component, but they must be used consistently across the app.

这些模式描述组件的协作方式。它们本身可能不是独立组件，但必须在应用中保持一致使用。

Entity Row with Status + Priority

带状态+优先级的实体行

The standard list item for issues and similar entities:

tsx

<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={() => {}}
/>

Leading slot always: StatusIcon first, then PriorityIcon. Trailing slot: StatusBadge or timestamp.

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

tsx

<EntityRow
  leading={<><StatusIcon status="in_progress" /><PriorityIcon priority="high" /></>}
  identifier="PAP-001"
  title="实现认证流程"
  subtitle="分配给Agent Alpha"
  trailing={<StatusBadge status="in_progress" />}
  onClick={() => {}}
/>

前置插槽固定顺序：先StatusIcon，再PriorityIcon。后置插槽：StatusBadge或时间戳。

Grouped List

分组列表

Issues grouped by status header + entity rows:

tsx

<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>

按状态标题+实体行分组的问题列表：

tsx

<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">进行中</span>
  <span className="text-xs text-muted-foreground ml-1">2</span>
</div>
<div className="border border-border rounded-b-md">
  <EntityRow ... />
  <EntityRow ... />
</div>

Property Row

属性行

Key-value pairs in properties panels:

tsx

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

Label is always

text-xs text-muted-foreground

, value on the right. Wrap in a container with

space-y-1

属性面板中的键值对：

tsx

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

标签固定为

text-xs text-muted-foreground

，值显示在右侧。外层容器使用

space-y-1

。

Metric Card Grid

指标卡片网格

Dashboard metrics in a responsive grid:

tsx

<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>

响应式网格布局的仪表盘指标：

tsx

<div className="grid md:grid-cols-2 xl:grid-cols-4 gap-4">
  <MetricCard icon={Bot} value={12} label="活跃智能体" description="本周新增3个" />
  ...
</div>

Progress Bar (Budget)

进度条（预算）

Color by threshold: green (<60%), yellow (60-85%), red (>85%):

tsx

<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>

按阈值区分颜色：绿色（<60%）、黄色（60-85%）、红色（>85%）：

tsx

<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>

Comment Thread

评论线程

Author header (name + timestamp) then body, in bordered cards with

space-y-3

. Add comment textarea + button below.

作者头部（名称+时间戳）+ 正文，置于带边框的卡片中，使用

space-y-3

。下方添加评论输入框+按钮。

Cost Table

成本表格

Standard

<table>

with

text-xs

, header row with

bg-accent/20

font-mono

for numeric values.

标准

<table>

，使用

text-xs

，表头行使用

bg-accent/20

，数值使用

font-mono

。

Log Viewer

日志查看器

bg-neutral-950 rounded-lg p-3 font-mono text-xs

container. Color lines by level: default (foreground), WARN (yellow-400), ERROR (red-400), SYS (blue-300). Include live indicator dot when streaming.

容器使用

bg-neutral-950 rounded-lg p-3 font-mono text-xs

。按级别为行着色：默认（前景色）、WARN（yellow-400）、ERROR（red-400）、SYS（blue-300）。流式输出时显示实时状态点。

8. Interactive Patterns

8. 交互模式

Hover States

悬停状态

Entity rows:
```
hover:bg-accent/50
```

Nav items:

hover:bg-accent/50 hover:text-accent-foreground

Active nav:
```
bg-accent text-accent-foreground
```

实体行：
```
hover:bg-accent/50
```

导航项：

hover:bg-accent/50 hover:text-accent-foreground

活跃导航项：
```
bg-accent text-accent-foreground
```

Focus

焦点状态

focus-visible:ring-ring focus-visible:ring-[3px]

— standard Tailwind focus-visible ring.

focus-visible:ring-ring focus-visible:ring-[3px]

— 标准Tailwind focus-visible焦点环。

Disabled

禁用状态

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

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

Inline Editing

内联编辑

Use

InlineEditor

component — click text to edit, Enter saves, Escape cancels.

使用

InlineEditor

组件——点击文本即可编辑，按Enter保存，按Escape取消。

Popover Selectors

弹出选择器

StatusIcon and PriorityIcon use Radix Popover for inline selection. Follow this pattern for any clickable property that opens a picker.

StatusIcon和PriorityIcon使用Radix Popover实现内联选择。所有可点击并打开选择器的属性均需遵循此模式。

9. Layout System

9. 布局系统

Three-zone layout defined in

Layout.tsx

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

Sidebar:
```
w-60
```
, collapsible, contains CompanySwitcher + SidebarSections
Properties panel:
```
w-80
```
, shown on detail views, hidden on lists
Main content: scrollable,
```
flex-1
```

由

Layout.tsx

定义的三区域布局：

┌──────────┬──────────────────────────────┬──────────────────────┐
│ 侧边栏  │  面包屑导航栏                │                      │
│ (w-60)   ├──────────────────────────────┤  属性面板            │
│          │  主内容区 (flex-1)           │  (w-80, 可选)        │
└──────────┴──────────────────────────────┴──────────────────────┘

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

10. The /design-guide Page

10. /design-guide页面

Location:

ui/src/pages/DesignGuide.tsx

Route:

/design-guide

This is the living showcase of every component and pattern in the app. It is the source of truth for how things look.

位置：

ui/src/pages/DesignGuide.tsx

路由：

/design-guide

这是应用中所有组件和模式的实时展示页面，是视觉效果的唯一权威来源。

Rules

规则

When you add a new reusable component, you MUST add it to the design guide page. Show all variants, sizes, and states.
When you modify an existing component's API, update its design guide section.
When you add a new composition pattern, add a section demonstrating it.
Follow the existing structure:
```
<Section title="...">
```
wrapper with
```
<SubSection>
```
for grouping.
Keep sections ordered logically: foundational (colors, typography) first, then primitives, then composites, then patterns.

添加新的可复用组件时，必须同步更新设计指南页面。展示所有变体、尺寸和状态。
修改现有组件的API时，更新其在设计指南中的对应章节。
添加新的组合模式时，添加对应的演示章节。
遵循现有结构：使用
```
<Section title="...">
```
包裹，用
```
<SubSection>
```
进行分组。
章节顺序需符合逻辑：基础内容（颜色、排版）优先，其次是基础组件，然后是复合组件，最后是模式。

Adding a New Section

添加新章节

tsx

<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>

tsx

<Section title="我的新组件">
  <SubSection title="变体">
    {/* 展示所有变体 */}
  </SubSection>
  <SubSection title="尺寸">
    {/* 展示所有尺寸 */}
  </SubSection>
  <SubSection title="状态">
    {/* 展示交互/禁用状态 */}
  </SubSection>
</Section>

11. Component Index

11. 组件索引

See references/component-index.md for the full component inventory.

When you create a new reusable component:

Add it to the component index reference file
Add it to the /design-guide page
Follow existing naming and file conventions

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

创建新的可复用组件时：

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

12. File Conventions

12. 文件规范

shadcn primitives:
```
ui/src/components/ui/{component}.tsx
```
— lowercase, kebab-case
Custom components:
```
ui/src/components/{ComponentName}.tsx
```
— PascalCase
Pages:
```
ui/src/pages/{PageName}.tsx
```
— PascalCase
Utilities:
```
ui/src/lib/{name}.ts
```
Hooks:
```
ui/src/hooks/{useName}.ts
```
API modules:
```
ui/src/api/{entity}.ts
```
Context providers:
```
ui/src/context/{Name}Context.tsx
```

All components use

cn()

from

@/lib/utils

for className merging. All components use CVA for variant definitions when they have multiple visual variants.

shadcn基础组件：
```
ui/src/components/ui/{component}.tsx
```
— 小写、短横线命名法
自定义组件：
```
ui/src/components/{ComponentName}.tsx
```
— 大驼峰命名法
页面组件：
```
ui/src/pages/{PageName}.tsx
```
— 大驼峰命名法
工具函数：
```
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()

进行类名合并。当组件有多种视觉变体时，均使用CVA定义变体。

13. Common Mistakes to Avoid

13. 需避免的常见错误

Using raw hex/rgb colors instead of CSS variable tokens
Creating ad-hoc typography styles instead of using the established scale
Hardcoding status colors instead of using StatusBadge/StatusIcon
Building one-off styled elements when a reusable component exists
Adding components without updating the design guide page
Using
```
shadow-md
```
or heavier — keep shadows minimal (xs, sm only)
Using
```
rounded-2xl
```
or larger — max is
```
rounded-xl
```
(except
```
rounded-full
```
for pills)
Forgetting dark mode — always use semantic tokens, never hardcode light/dark values

使用原始十六进制/RGB颜色，而非CSS变量令牌
自行创建临时排版样式，而非使用既定的规范
硬编码状态颜色，而非使用StatusBadge/StatusIcon
已有可复用组件时，仍构建一次性样式元素
添加组件但未更新设计指南页面
使用
```
shadow-md
```
或更重的阴影——保持阴影极简（仅使用xs、sm）
使用
```
rounded-2xl
```
或更大的圆角——最大为
```
rounded-xl
```
（胶囊按钮除外，使用
```
rounded-full
```
）
忘记适配深色模式——始终使用语义化令牌，切勿硬编码浅色/深色值