design-guide

Paperclip UI 設計系統指南，用於建立一致且可重複使用的前端元件。當您需要建立新的 UI 元件、修改現有元件、為前端新增頁面或功能、設定 UI 元素樣式，或需要了解設計語言與慣例時使用。涵蓋：元件建立、設計代碼、排版、狀態/優先級系統、組合模式，以及 /design-guide 展示頁面。請務必與 frontend-design 技能（視覺品質）和 web-design-guidelines 技能（網頁最佳實踐）一起使用。

1星標

0分支

更新於 2026/7/10

獲取技能源代碼

Paperclip 設計指南

Paperclip 的 UI 是專業級的控制面板——資訊密集、鍵盤驅動、預設深色主題。每個像素都必須有其存在的價值。

務必搭配使用： frontend-design（視覺打磨）和 web-design-guidelines（網頁最佳實踐）。

1. 設計原則

資訊密集但易於掃讀。 在不需點擊即可顯示的前提下，呈現最大資訊量。空白用於區隔，而非填充。
鍵盤優先。 全域快捷鍵（Cmd+K、C、[、]）。進階使用者幾乎不碰滑鼠。
情境式，非模態。 行內編輯取代對話框。下拉選單取代頁面導航。
預設深色主題。 中性灰色（OKLCH），而非純黑。強調色僅用於狀態/優先級。文字是主要的視覺元素。
元件驅動。 偏好可重複使用的元件，以封裝樣式慣例。在適當的抽象層級建立——不過度細碎，也不過度龐大。

2. 技術棧

React 19 + TypeScript + Vite
Tailwind CSS v4 搭配 CSS 變數（OKLCH 色彩空間）
shadcn/ui（new-york 風格，中性基底，啟用 CSS 變數）
Radix UI 基礎元件（無障礙、焦點管理）
Lucide React 圖示（16px 導航、14px 行內）
class-variance-authority（CVA）用於元件變體
clsx + tailwind-merge 透過 cn() 工具函式

設定檔：ui/components.json（別名：@/components、@/components/ui、@/lib、@/hooks）

3. 設計代碼

所有代碼定義為 ui/src/index.css 中的 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	綠色系	代理、目標、問題、核准
running	青色	代理
paused	橙色	代理
idle、pending	黃色	代理、核准
failed、error、rejected、blocked	紅色系	執行、代理、核准、問題
archived、planned、backlog、cancelled	中性灰	各種
todo	藍色	問題
in_progress	靛色	問題
in_review	紫色	問題

優先級圖示

定義於 PriorityIcon.tsx：critical（紅色/AlertTriangle）、high（橙色/ArrowUp）、medium（黃色/Minus）、low（藍色/ArrowDown）。

代理狀態點

行內彩色點：running（青色、animate-pulse）、active（綠色）、paused（黃色）、error（紅色）、offline（中性色）。

6. 元件階層

三個層級：

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。

何時建立新元件

當以下情況發生時，建立可重複使用的元件：

相同的視覺模式出現在 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={() => {}}
/>

leading 插槽順序：先 StatusIcon，再 PriorityIcon。trailing 插槽：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：

┌──────────┬──────────────────────────────┬──────────────────────┐
│ 側邊欄   │  麵包屑列                    │                      │
│ (w-60)   ├──────────────────────────────┤  屬性面板            │
│          │  主要內容 (flex-1)            │  (w-80，可選)        │
└──────────┴──────────────────────────────┴──────────────────────┘

側邊欄：w-60，可折疊，包含 CompanySwitcher 和 SidebarSections
屬性面板：w-80，顯示於詳細檢視，隱藏於列表
主要內容：可滾動，flex-1

10. /design-guide 頁面

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

這是應用程式中每個元件與模式的即時展示頁面。它是視覺呈現的真相來源。

規則

當您新增一個可重複使用的元件時，必須將其加入設計指南頁面。 顯示所有變體、尺寸與狀態。
當您修改現有元件的 API 時，請更新其設計指南區段。
當您新增一個組合模式時，請加入展示該模式的區段。
遵循現有結構：使用 <Section title="..."> 包裝，並以 <SubSection> 進行分組。
區段按邏輯順序排列：基礎（顏色、排版）優先，接著是基礎元件、複合元件，最後是模式。

新增區段

<Section title="My New Component">
  <SubSection title="Variants">
    {/* 顯示所有變體 */}
  </SubSection>
  <SubSection title="Sizes">
    {/* 顯示所有尺寸 */}
  </SubSection>
  <SubSection title="States">
    {/* 顯示互動/停用狀態 */}
  </SubSection>
</Section>

11. 元件索引

完整元件清單請參閱 references/component-index.md。

當您建立新的可重複使用元件時：

將其加入元件索引參考檔案
將其加入 /design-guide 頁面
遵循現有的命名與檔案慣例

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
Hook： ui/src/hooks/{useName}.ts
API 模組： ui/src/api/{entity}.ts
Context 提供者： 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）
忘記深色模式——始終使用語意代碼，絕不硬編碼淺色/深色值

您可能也喜歡

design-taste-frontend

78Kfrontend

Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check.

Leonxlnx

獲取

vue-patterns

240Kfrontend

Vue.js 3 Composition API patterns, component architecture, reactivity best practices, Pinia state management, Vue Router navigation, and Nuxt SSR patterns. Activates for Vue, Nuxt, Vite, or Pinia projects. Use when building or reviewing Vue 3, Nuxt, or Pinia code — Composition API, reactivity, or router navigation.

affaan-m

獲取

motion-advanced

237Kfrontend

適用於 React / Next.js 的進階動效模式 — 涵蓋拖曳（drag & drop）、手勢、文字動畫、SVG 路徑繪製、自訂 Hooks、命令式序列動畫（useAnimate）、載入器（loaders）以及完整的 API 決策樹。需搭配 motion-foundations 使用。