AI Skills
design-guide

design-guide

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

1星標
0分支
更新於 2026/7/10
獲取技能源代碼

相關技能

design-system11萬source-driven-development7.8萬nextjs-supabase-auth4.3萬
SKILL.md
readonlyread-only
name
design-guide
description

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

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. 元件階層

三個層級：

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

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

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

規則

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

新增區段

<Section title="My New Component">
  <SubSection title="Variants">
    {/* 顯示所有變體 */}
  </SubSection>
  <SubSection title="Sizes">
    {/* 顯示所有尺寸 */}
  </SubSection>
  <SubSection title="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
  • 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）
  • 忘記深色模式——始終使用語意代碼，絕不硬編碼淺色/深色值