design-guide

Name: design-guide
Author: paperclipai

github.com/paperclipaiデザイン・UI108.3k372 回インストール今日更新

リポジトリ

design-guide について

PaperclipのUIを開発・保守するためのデザインガイドスキルです。ダークテーマとキーボード操作を基本に、デザイントークン、コンポーネント階層、操作パターンを定めています。

主な機能

01情報密度が高く見渡しやすいレイアウト
02キーボード操作を優先する規則
03ダークテーマとセマンティックトークン
04コンポーネント階層と再利用の指針
05状態・優先度・文字組みの統一

活用シーン

01PaperclipのUIページの実装
02再利用可能なUIコンポーネントの追加
03状態と優先度表示の統一
04変更に合わせたデザインガイドの更新

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/paperclipai/paperclip --skill design-guide

インストール後、Claude Code で/design-guideを入力して読み込まれたか確認します。

同梱ファイルreferences/component-index.md

詳細

Paperclip デザインガイド

Paperclip の UI はプロフェッショナル品質のコントロールプレーンです。情報密度が高く、キーボード操作を中心とし、デフォルトでダークテーマです。すべてのピクセルに意味があります。

必ず併用してください： frontend-design（ビジュアルの仕上がり）と web-design-guidelines（Web のベストプラクティス）。

1. デザイン原則

高密度でも見やすく。 クリックして表示する情報を最小限に抑えます。余白は区切りに使い、埋めるためには使いません。
キーボードを優先。 グローバルショートカット（Cmd+K、C、[、]）を用意します。パワーユーザーがマウスを使うことはほとんどありません。
モーダルではなく、コンテキストに沿って。 ダイアログボックスよりインライン編集を、ページ遷移よりドロップダウンを優先します。
ダークテーマをデフォルトに。 真っ黒ではなく、ニュートラルなグレー（OKLCH）を使います。アクセントカラーはステータスと優先度にのみ使います。テキストを視覚要素の中心にします。
コンポーネント主導。 スタイルの規約を取り入れた再利用可能なコンポーネントを優先します。適切な抽象度で構築し、細分化しすぎず、モノリシックにしすぎないようにします。

2. 技術スタック

React 19 + TypeScript + Vite
CSS 変数（OKLCH 色空間）を使った Tailwind CSS v4
shadcn/ui（new-york スタイル、neutral ベース、CSS 変数を有効化）
Radix UI プリミティブ（アクセシビリティ、フォーカス管理）
Lucide React アイコン（ナビゲーションは 16px、インラインは 14px）
コンポーネントのバリアントに class-variance-authority（CVA）
cn() ユーティリティ経由の clsx + tailwind-merge

設定：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`	Issue キー（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. コンポーネント階層

3 つの階層があります：

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

先頭のスロットは常に 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 のコンテナを使用します。レベルに応じて行の色を設定します：デフォルト（foreground）、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 で定義されている3ゾーンのレイアウトです。

┌──────────┬──────────────────────────────┬──────────────────────┐
│ 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

このページは、アプリ内のすべてのコンポーネントとパターンを紹介する、常に更新されるショーケースです。各要素の見た目を決める信頼できる情報源です。

ルール

再利用可能なコンポーネントを新しく追加した場合は、必ずデザインガイドページにも追加してください。 すべてのバリエーション、サイズ、状態を表示します。
既存コンポーネントの API を変更した場合は、デザインガイド内の該当セクションを更新してください。
新しい合成パターンを追加した場合は、それを紹介するセクションを追加してください。
既存の構造に従い、<Section title="..."> で囲み、グループ化には <SubSection> を使用します。
セクションは論理的な順序で並べます。まず基礎（色、タイポグラフィ）、次にプリミティブ、複合要素、パターンの順にします。

新しいセクションの追加

<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 を参照してください。

再利用可能なコンポーネントを新しく作成する場合は、次の手順に従ってください。

コンポーネント索引のリファレンスファイルに追加します
/design-guide ページに追加します
既存の命名規則とファイル規則に従います

12. ファイル規則

shadcn プリミティブ： ui/src/components/ui/{component}.tsx — 小文字のケバブケース
カスタムコンポーネント： ui/src/components/{ComponentName}.tsx — パスカルケース
ページ： ui/src/pages/{PageName}.tsx — パスカルケース
ユーティリティ： ui/src/lib/{name}.ts
フック： ui/src/hooks/{useName}.ts
API モジュール： ui/src/api/{entity}.ts
コンテキストプロバイダー： ui/src/context/{Name}Context.tsx

すべてのコンポーネントで、className の結合に @/lib/utils の cn() を使用します。複数の見た目のバリエーションがある場合は、すべてのコンポーネントでバリエーションの定義に CVA を使用します。

13. 避けるべきよくある間違い

CSS 変数トークンを使わず、生の hex/rgb 色を使用する
確立されたスケールを使わず、場当たり的なタイポグラフィのスタイルを作成する
StatusBadge/StatusIcon を使わず、ステータスの色をハードコードする
再利用可能なコンポーネントがあるのに、一度限りのスタイル付き要素を作成する
デザインガイドページを更新せずにコンポーネントを追加する
shadow-md 以上を使用する — 影は最小限（xs、sm のみ）にします
rounded-2xl 以上を使用する — 上限は rounded-xl です（ピル型の rounded-full を除く）
ダークモードを忘れる — 常にセマンティックトークンを使用し、ライト／ダークの値をハードコードしないでください

Markdown 対応

ログインしてコメント

基本情報

作者: paperclipai
リポジトリ: paperclipai/paperclip
カテゴリ: デザイン・UI
インストール数: 372
GitHub スター: 108,278

問題を報告