ui-design-system

デザインシステム

このスキルでは、完全なデザインシステムを提供します。デザインの考え方を示す理念と、継続的に更新できるスタイルガイドのテンプレートであるドキュメントが含まれています。どのインターフェースも、1ピクセルの違いにまでこだわるチームがデザインしたように見えるべきです。

ワークフロー

1. デザインの方向性から始める — パート1を読み、コードを書く前に方向性を決めます
2. クラフトの原則を適用する — 構築する際は、パート2の基本ルールに従います
3. スタイルガイドに記録する — すべてのコンポーネントをスタイルガイドに追加します（パート3）

---

パート1：デザインの方向性

コードを書く前に、デザインの方向性を決めてください。 既定の選択肢に頼ってはいけません。この製品にどのような印象が必要かを考えましょう。

コンテキストについて考える

• この製品は何をするものですか？ 金融ツールとクリエイティブツールでは、必要な雰囲気が異なります。
• 誰が使いますか？ パワーユーザーは情報密度を求めます。たまに使うユーザーは案内を求めます。
• どのような感情的ニーズに応えますか？ 信頼でしょうか？ 効率でしょうか？ 楽しさでしょうか？ 集中でしょうか？
• 何があれば記憶に残るでしょうか？ どの製品にも、際立った印象を与えるチャンスがあります。

パーソナリティを選ぶ

エンタープライズ／SaaS の UI には、思っている以上に幅広い表現があります。次の方向性を検討してください。

精密さと情報密度 — 余白を詰め、モノクロで、情報を前面に出します。ツールを常用するパワーユーザー向けです。Linear、Raycast、ターミナルの美学をイメージしてください。

温かみと親しみやすさ — 余白を広く取り、柔らかなシャドウ、親しみやすい色を使います。人間味のある印象を目指す製品向けです。Notion、Coda、共同作業ツールをイメージしてください。

洗練と信頼 — 寒色系、重なりによる奥行き、金融にふさわしい重厚感を取り入れます。金銭や機密データを扱う製品向けです。Stripe、Mercury、エンタープライズ向け B2B をイメージしてください。

大胆さと明快さ — 高いコントラスト、印象的なネガティブスペース、自信を感じさせるタイポグラフィを取り入れます。モダンで決断力のある印象を目指す製品向けです。Vercel、ミニマルなダッシュボードをイメージしてください。

実用性と機能性 — 落ち着いた配色、機能性を重視した情報密度、明確な階層構造を取り入れます。装飾よりも作業が重要な製品向けです。GitHub、開発者向けツールをイメージしてください。

データと分析 — チャートに最適化し、技術的でありながら使いやすく、数値を主役として扱います。分析、指標、ビジネスインテリジェンス向けです。

1つ選びましょう。2つを組み合わせてもかまいません。ただし、製品に合った方向性を必ず決めてください。

カラーファンデーションを選ぶ

温かみのあるニュートラルカラーを無条件に選ばないでください。 製品に合わせて検討しましょう。

• 温かみのあるファンデーション（クリーム色、暖色系のグレー） — 親しみやすく、心地よく、人間味がある
• 寒色系のファンデーション（スレート、青みがかったグレー） — プロフェッショナルで、信頼でき、落ち着いている
• 純粋なニュートラルカラー（純粋なグレー、黒／白） — ミニマルで、大胆で、技術的
• 色味のあるファンデーション（わずかに色味を加えた色） — 独自性があり、記憶に残り、ブランドらしい

ライトとダークのどちらにしますか？ ダークモードは、単にライトモードを反転したものではありません。ダークは技術的で、集中でき、上質な印象を与えます。ライトは開放的で、親しみやすく、すっきりした印象を与えます。コンテキストに応じて選びましょう。

アクセントカラー — 意味のある色を1つ選びます。信頼には青、成長には緑、エネルギーにはオレンジ、創造性には紫が適しています。いつも同じアクセントカラーを安易に選ばないでください。

レイアウトの方針を選ぶ

コンテンツに合わせてレイアウトを決めます。

• 情報量が多く、ユーザーが一覧して比較するインターフェースには、高密度なグリッド
• ユーザーが集中する必要のあるタスクには、広めの余白
• 遷移先が多く、複数のセクションがあるアプリには、サイドバーナビゲーション
• セクションが少ないシンプルなツールには、トップナビゲーション
• コンテキストが重要なリストと詳細のパターンには、分割パネル

タイポグラフィを選ぶ

タイポグラフィは全体の印象を決めます。常に同じ選択肢を既定にしないでください。

• システムフォント — 高速で、ネイティブで、目立たない（実用性を重視する製品に適しています）
• ジオメトリックサンセリフ（Geist、Inter） — モダンで、すっきりしていて、技術的
• ヒューマニストサンセリフ（SF Pro、Satoshi） — 温かみがあり、親しみやすい
• モノスペースの影響を取り入れた書体 — 技術的で、開発者向けで、データ量の多い製品に適しています

---

パート2：クラフトの原則

これらは、デザインの方向性にかかわらず適用されます。これが品質の最低基準です。

4px グリッド

すべての間隔に、4px を基準とするグリッドを使用します。

• 4px - ごく小さな間隔（アイコン間の隙間）
• 8px - 狭い間隔（コンポーネント内）
• 12px - 標準的な間隔（関連要素間）
• 16px - ゆとりのある間隔（セクションのパディング）
• 24px - 広めの間隔（セクション間）
• 32px - 大きく区切る間隔

対称的なパディング

上・左・下・右の値を揃えます。 上のパディングが16pxなら、左・下・右も16pxにします。ただし、コンテンツによって自然な視覚的バランスが生まれる場合は例外です。

/* Good */
padding: 16px;
padding: 12px 16px; /* Only when horizontal needs more room */

/* Bad */
padding: 24px 16px 12px 16px;

角丸の一貫性

4px グリッドに沿ってください。角が鋭いほど技術的な印象になり、丸みが強いほど親しみやすい印象になります。ルールを決めて、一貫して使いましょう。

• シャープ：4px、6px、8px
• ソフト：8px、12px
• ミニマル：2px、4px、6px

複数のルールを混在させないでください。一貫性がまとまりを生みます。

奥行きと高さの方針

デザインの方向性に合わせて、奥行きの表現を選びます。 奥行きはあくまで手段であり、必須ではありません。

ボーダーのみ（フラット） — すっきりとして技術的で、情報密度の高い表現です。視覚的な浮き上がりよりも情報密度が重要な、実用性重視のツールに適しています。Linear、Raycast、多くの開発者向けツールでは、シャドウをほとんど使わず、領域を区切るための控えめなボーダーのみを使用しています。

控えめな単一シャドウ — 複雑さを加えずに、柔らかな浮き上がりを演出します。シンプルな 0 1px 3px rgba(0,0,0,0.08) だけで十分な場合もあります。

レイヤー化したシャドウ — 豊かで上質な、立体感のある表現です。複数のシャドウレイヤーによって、リアルな奥行きを作り出します。Stripe と Mercury がこの方法を採用しています。

サーフェスカラーの変化 — 背景の色合いを変えることで、シャドウを使わずに階層を表現します。#f8fafc の背景に #fff のカードを置くだけでも、浮き上がった印象になります。

いずれか1つを選び、一貫して使ってください。

/* Borders-only approach */
--border: rgba(0, 0, 0, 0.08);
border: 0.5px solid var(--border);

/* Single shadow approach */
--shadow: 0 1px 3px rgba(0, 0, 0, 0.08);

/* Layered shadow approach */
--shadow-layered:
  0 0 0 0.5px rgba(0, 0, 0, 0.05),
  0 1px 2px rgba(0, 0, 0, 0.04),
  0 2px 4px rgba(0, 0, 0, 0.03),
  0 4px 8px rgba(0, 0, 0, 0.02);

カードレイアウト

単調なカードレイアウトは、手抜きのデザインです。カードごとに、内容に合った内部構造を設計してください。ただし、サーフェスのスタイルは統一します。ボーダーの太さ、シャドウの深さ、角丸、パディングのスケール、タイポグラフィを揃えてください。

独立したコントロール

UI コントロールには、コンテナーのスタイルを適用します。日付ピッカー、フィルター、ドロップダウンは、丁寧に作り込まれたオブジェクトのように見える必要があります。

スタイルを適用する UI に、ネイティブのフォーム要素を使わないでください。 代わりにカスタムコンポーネントを作成します。

• カスタムセレクト：トリガーボタン＋配置したドロップダウンメニュー
• カスタム日付ピッカー：入力欄＋カレンダーのポップオーバー
• カスタムチェックボックス／ラジオボタン：状態管理を備えたスタイル付きの div

タイポグラフィの階層

• 見出し：ウェイト600、文字間隔を狭める（-0.02em）
• 本文：ウェイト400～500、標準の字間
• ラベル：ウェイト500、大文字表記では字間をわずかに広げる
• スケール：11px、12px、13px、14px（基準）、16px、18px、24px、32px

データには等幅フォントを使用

数値、ID、コード、タイムスタンプには等幅フォントを使用します。列を揃えるには tabular-nums を使用してください。

アイコン

Phosphor Icons（@phosphor-icons/react）または Lucide（lucide-react）を使用します。アイコンは意味を明確にするためのものであり、装飾ではありません。アイコンを削除しても意味が変わらないなら、削除してください。

アニメーション

• マイクロインタラクションには150ms、大きめのトランジションには200～250ms
• イージング：cubic-bezier(0.25, 1, 0.5, 1)
• エンタープライズ向け UI では、スプリングやバウンドの効果を使わない

コントラストの階層

4段階のシステムを作ります。前景色（プライマリ）→ セカンダリ → ミュート → フェイント。この4段階を一貫して使ってください。

色は意味を伝えるときだけ使う

グレーで構造を作ります。色は、ステータス、アクション、エラー、成功を伝える場合にのみ使います。装飾目的の色はノイズになります。

ナビゲーションの文脈

画面には、現在の状況がわかる手がかりが必要です。

• ナビゲーション — 現在位置を示すサイドバーまたはトップナビゲーション
• 位置インジケーター — パンくずリスト、ページタイトル、またはアクティブなナビゲーション状態
• ユーザーの文脈 — ログイン中のユーザー、ワークスペース／組織

ダークモードでの考慮事項

シャドウよりボーダーを優先 — 暗い背景ではシャドウが見えにくくなります。ボーダーをより活用してください。

セマンティックカラーを調整 — ステータスカラーは、暗い背景では彩度を少し下げる必要がある場合があります。

---

パート3：アンチパターン

決して行わないこと

• 極端に強いドロップシャドウ（box-shadow: 0 25px 50px...）
• 小さな要素に大きな角丸（16px以上）を設定する
• 明確な理由のない非対称なパディング
• 色付きの背景に純白のカードを配置する
• 装飾目的で太いボーダー（2px以上）を使う
• 過剰な余白（セクション間のマージンが48pxを超える）
• バネのように弾むアニメーション
• 装飾目的のグラデーション
• 1つのインターフェースで複数のアクセントカラーを使う

常に問いかけること

• 「このプロダクトに何が必要か考えたのか、それとも安易に決めつけたのか？」
• 「この方向性は、コンテキストとユーザーに合っているか？」
• 「この要素には丁寧な作り込みが感じられるか？」
• 「奥行きの表現は一貫していて、意図的か？」
• 「すべての要素がグリッドに揃っているか？」

---

パート4：スタイルガイドのテンプレート

スタイルガイドは、デザインシステムを記録する生きたドキュメントです。 作成するすべてのコンポーネントを、ここに記録してください。

テンプレートで作成されるもの

次の内容を含む /style-guide ページです。

• 左側のナビゲーション — 階層的なセクションナビゲーションを備えた、固定表示のサイドバー
• 色 — ブランドパレット、カテゴリカラー、システムカラー
• タイポグラフィ — フォントファミリー、サイズ、ウェイト
• ボタン — すべてのバリエーション、サイズ、状態
• 入力欄 — デフォルト、フォーカス、エラー、無効の各状態
• カード — レイアウトのバリエーション
• アバター — サイズとフォールバック状態
• ダイアログ — モーダルのパターン
• 読み込み／思考中 — スピナー、インジケーター、アニメーション状態
• デザイントークン — 余白のスケール、角丸、シャドウ

テンプレートの使用方法

1. プロジェクトにコピーする

cp templates/style-guide-page.tsx your-app/app/style-guide/page.tsx

2. カスタマイズする

1. ヘッダーのタイトルを更新する — 「STYLE GUIDE」をプロジェクト名に置き換えます
2. ブランドカラーを追加する — Colors セクションを更新して、パレットを設定します
3. フォントを追加する — Typography セクションを更新します
4. コンポーネントをインポートする — プレースホルダーのインポートを実際のコンポーネントに置き換えます
5. プロジェクト固有のセクションを追加する — カスタムコンポーネントのセクションを追加します

3. 維持する

スタイルガイドは、すべての UI コンポーネントの正式な情報源です。

コンポーネントを作成または変更するときは、次のことを行います。

1. まずスタイルガイドを確認する — 新規作成する前に、コンポーネントがすでに存在するか確認します
2. 新しいコンポーネントを追加する — 再利用可能なすべてのコンポーネントにセクションを設けます
3. すべての状態を示す — 通常、ホバー、フォーカス、無効、エラー、読み込み
4. 変更時に更新する — コンポーネントを変更したら、スタイルガイドの該当項目も更新します

テンプレートの構成

ナビゲーション項目でサイドバーの構成を定義します。

const NAV_ITEMS = [
  { id: 'colors', label: 'Colors', icon: Palette, children: [
    { id: 'brand', label: 'Brand' },
    { id: 'system', label: 'System' },
  ]},
  { id: 'typography', label: 'Typography', icon: Type },
  { id: 'buttons', label: 'Buttons', icon: MousePointer },
  // ... more sections
]

各セクションは次のパターンに従います。

<section id="buttons">
  <SectionHeader title="Buttons" />
  <div>
    <h4 className="text-xs font-medium text-muted-foreground mb-3 uppercase tracking-wide">
      Variants
    </h4>
    <div className="flex flex-wrap gap-3">
      <Button variant="default">Default</Button>
      <Button variant="secondary">Secondary</Button>
    </div>
  </div>
</section>

カスタムセクションの追加

1. NAV_ITEMS に追加します。

{ id: 'my-component', label: 'My Component', icon: Box },

2. セクションを追加します。

<section id="my-component">
  <SectionHeader title="My Component" />
  {/* Component variations */}
</section>

保守チェックリスト

UI を変更するたびに、次の項目を確認します。

• コンポーネントがスタイルガイドに追加されている（新規の場合）
• すべての状態が示されている（通常、ホバー、無効、読み込み、エラー）
• デザイントークンを使用している（テーマの色、余白、角丸）
• コンポーネントのインデックスから正しくエクスポートされている

ベストプラクティス

1. 常に最新の状態に保つ — 古くなったスタイルガイドは、ないよりも悪いものです
2. 実際のデータを示す — 「Lorem ipsum」ではなく、現実的なモックデータを使います
3. インタラクションをテストする — ダイアログは開き、ボタンはクリックできるようにします
4. エッジケースを記録する — 長いテキスト、空の状態、読み込み
5. モバイルでの考慮事項 — 該当する場合は、レスポンシブなバリエーションを示します

---

基準

すべてのインターフェースは、1ピクセルの違いにもこだわるチームがデザインしたように見えるべきです。削ぎ落とすのではなく、丁寧に作り込む。そして、それぞれのコンテキストに合わせてデザインします。

目指すのは、適切な個性を備えた緻密なミニマリズムです。同じ品質基準を保ちながら、コンテキストに応じて実現します。