design-system

デザインシステム

このスキルは、主な問いが**「個々の画面をデザインまたはリファクタリングする前に、この製品または製品ファミリーにどのような共通 UI ルールを適用すべきか？」**である場合に使用します。

これは、このリポジトリにおけるフロントエンド UI システムの正式な基準点です。 次のことを行います。

1. システム上の課題を分類する
2. 適切なデザインシステムのモードを選ぶ
3. 関連するフロントエンド作業を早い段階で適切な担当先に振り分ける
4. 別の人やエージェントが実行できる、簡潔なシステムパケットを定義する

アプローチを選ぶ前に、references/system-modes.mdを読んでください。 共通トークン、プリミティブ、または命名規則を変更する前に、references/token-and-governance-checklist.mdを読んでください。 作業がこのスキル、responsive-design、web-accessibilityのどれに該当するかを判断する際は、references/scope-boundaries.mdを読んでください。 最終的な引き継ぎ資料を作成する前に、references/design-system-packet-template.mdを読んでください。

このスキルを使用する場面

• 製品、製品スイート、またはアプリとマーケティング用画面に共通するデザインシステムを定義またはリファクタリングする
• 色、タイポグラフィ、間隔、角丸、エレベーション、モーション、ブレークポイントの各スケールに関するトークンの方針を定める
• プリミティブの命名規則、コントリビューションの境界、再利用可能なビジュアル言語の規約を選ぶ
• ランディングページ、ダッシュボード、フォーム、コンポーネントライブラリに一貫性を持たせるシステムの方向性を策定する
• 「UI に一貫性がない」といった曖昧な依頼を、単発のページ再設計ではなく、システムレベルの方針を示すパケットに落とし込む
• コンポーネント、アクセシビリティ、またはレスポンシブ対応の実装を始める前に、チームでシステムに関する判断が必要かどうかを検討する
• 再利用可能なプリミティブ、スロット、バリアントの API を設計し、場当たり的な UI からコンポーネントファミリーを抽出する
• Figma、コードトークン、プリミティブ、および後続のフロントエンド作業に向けたデザインシステムの引き継ぎを準備する

このスキルを使用しない場面

• 主な作業がビューポートへの適応、コンテナークエリ戦略、オーバーフロー、またはモバイルレイアウトの検証である → responsive-designを使用する
• 主な作業がキーボードやフォーカスの挙動、WCAG の修正、ラベル、セマンティクス、コントラスト、または手動での a11y 検証である → web-accessibilityを使用する
• 主な作業が、階層、CTA の明確さ、仕上がり、リリース準備状況を対象とした、ページまたはフロー全体の幅広いレビューである → web-accessibilityを使用する
• 作業が実装のみで、システムのルールがすでに明確である。この場合はシステムのガバナンスを再検討せず、直接実装する

基本的な考え方

優れたデザインシステムとは、無作為に選んだカラーパレットとヒーローセクションのモックの組み合わせではありません。 次のことを定義する、共有の意思決定レイヤーです。

• 何を一貫させるか
• 画面ごとに何を変えてよいか
• 次の実装ステップをどの関連スキルが担当するか
• 後続チームが従うべき成果物は何か

このスキルを、フロントエンドに関するあらゆる課題を扱うものにしないでください。 システムのガバナンスはここで扱い、専門的な修正は適切な担当先に振り分けます。

手順

ステップ 1：例を作成する前に、デザインシステムの依頼を分類する

回答の範囲を適切に保てるよう、主となるモードを 1 つ選びます。

モード：

• 基盤モード — トークン、スケール、命名、モーション、密度、ブレークポイントの方針
• 複数画面の整合モード — ランディングページ、ダッシュボード、アプリシェルの一貫性、共通の階層、共通のブランドやシステム言語
• プリミティブのガバナンスモード — プリミティブの命名、所有権、コントリビューションの境界、製品固有の UI を共通プリミティブに昇格させるためのルールが必要な場合
• システム引き継ぎモード — すでに決定済みのシステムルールを、デザインや開発ですぐに利用できる簡潔な成果物にまとめる
• システムレビュー・モード — 一貫性の欠如が本当にデザインシステムの課題なのか、関連スキルに振り分けるべきなのかを評価する

簡易フレーム：

Design-system request:
- Surface: marketing site + logged-in dashboard
- Primary mode: cross-surface alignment
- System question: shared tokens and hierarchy, separate page-specific layouts
- Likely route-outs: responsive verification to responsive-design, a11y remediation to web-accessibility

ステップ 2：共有するシステム境界を定義する

トークンやページの方向性を変更する前に、システムが実際に何を担うのかを決めます。

次の内容を定義する場合は、design-system に含めます。

• トークンのスケールと命名規則
• プリミティブの命名とコントリビューションポリシー
• 多くの画面に適用するビジュアル言語の原則
• 複数のサーフェスで継承すべきブレークポイントや密度のポリシー
• 多くのコンポーネントが依存するモーションの原則とアクセシビリティのベースライン

次のような内容になった場合は、ここで扱わないでください。

• 1 ページのレイアウト崩れ → responsive-design
• 1 件のアクセシビリティ上の問題や修正計画 → web-accessibility
• 広範な UX/UI の批評 → web-accessibility

ステップ 3：共有する最小限の決定事項から着手する

最初から大量のトークン例を並べないでください。

システムに関する依頼では、まず次の共有レイヤーを決めます。

1. 基盤 — 色、文字、間隔、角丸、エレベーション、モーション、密度、ブレークポイント
2. プリミティブポリシー — どのプリミティブを用意するか、どう命名するか、何を共有し、何を製品固有にするか
3. サーフェスのルール — 一貫性を保ちながら、ランディングページ、ダッシュボード、フォーム、ナビゲーション、データ量の多いサーフェスをどう使い分けるか
4. アクセシビリティのベースライン — コントラストの要件、フォーカスの視認性、動きを減らす設定への対応、セマンティクスの要件
5. ガバナンス — 誰がトークンやプリミティブを追加・変更できるか、何をレビューすべきか、どの時点で作業を別のスキルに引き継ぐか

あるレイヤーが不明な場合は、詳細を作り出さず、その旨を伝えて未決定事項として記録してください。

ステップ 4：例はルールを補足するものとして扱う

例が役立つのは、共有ルールを明確にした後だけです。

適切な例の使い方：

• トークンの命名パターンを 1 つ示す
• ランディングページとダッシュボードのサーフェスの違いを 1 つ示す
• プリミティブへの昇格ルールを 1 つ示す
• モーションまたはアクセシビリティのベースラインを 1 つ示す

不適切な例の使い方：

• システムが何の問題を解決するのかを説明する前に、完全なカラーパレット、TS トークンファイル、CSS アニメーションシート、JSX の画面モックを一気に並べる

次のルールに従います。

• 最初にルール、
• 次に 1 つか 2 つの例、
• 最後に引き継ぎ用資料。

ステップ 5：隣接するフロントエンド作業は早めに振り分ける

複数の内容が混在する依頼はよくあります。明示的に分割してください。

例：

• チームからボタンのバリアント、スロット構造、制御／非制御の振る舞いについて依頼された場合は、システムの命名規則やトークンと併せて、ここでプリミティブ API を定義します
• チームからカードをモバイルでどう折りたたむか尋ねられた場合は、共有するブレークポイントポリシーをここに残し、レイアウトへの適用は responsive-design に振り分けます
• アイコンのみのボタンがキーボード操作、フォーカス、ラベルの要件を満たすか尋ねられた場合は、アクセシビリティのベースライン要件をここに残し、修正作業は web-accessibility に振り分けます
• 「このダッシュボードを監査して、気になる点を教えてほしい」という依頼の場合は、広範な批評を web-accessibility に振り分けます

すべてを「design-system の作業」と呼んで、担当範囲が曖昧な状態を隠さないでください。

ステップ 6：design-system の資料を作成する

後続のデザイン／開発作業で参照できる、簡潔な成果物で締めくくります。

推奨形式：

# Design System Packet

## Scope
- Products / surfaces covered:
- Primary mode:
- Shared system goal:

## Foundations
- Color / semantic token rules:
- Typography / spacing / radius / elevation:
- Motion / density / breakpoint policy:

## Primitive policy
- Shared primitives:
- Naming rules:
- What stays product-local:

## Surface guidance
- Landing / marketing:
- Dashboard / app shell:
- Forms / workflows:

## Accessibility baseline
- Contrast / focus / reduced motion / semantics:

## Route-outs
- `responsive-design`:
- `web-accessibility`:

## Open decisions
- ...

ユーザーが簡潔な回答を求めている場合は、同じセクションを維持したまま、箇条書きに圧縮してください。

ステップ 7：必要な場合に限り、簡潔な例を追加する

例は 1 つか 2 つまでとし、資料を補足するものだと明確に分かるようにしてください。

適切な例の形式：

• 固定値の巨大なパレットではなく、セマンティックな色トークン（surface/default、surface/emphasis、text/muted）
• 階層は共通でも密度が異なることを示す、ランディングページのヒーローとダッシュボードのヘッダーの比較
• 「共通のボタンはプリミティブのままにし、請求のアップセルバナーは製品固有にする」といったプリミティブへの昇格ルール

ステップ 8：境界を示す一文で締めくくる

範囲の重複によるずれを防ぐ一文で締めくくります。

例：

• 「このパケットでは、共通 UI システムとそのプリミティブ API を定義します。機能ごとのプロダクトコンポーネントは、各プロダクト内で管理します。」
• 「このパケットでは、ブレークポイントと密度の方針を定めます。ページレベルのレイアウト調整は responsive-design の範囲です。」
• 「このパケットでは、アクセシビリティの基本的な期待事項を定めます。修正と検証は web-accessibility の範囲です。」

例

例 1：共有ランディングページとダッシュボードのシステム

入力：「マーケティングサイトと B2B ダッシュボードで 1 つのデザインシステムを使い、トークン、タイポグラフィ、動きに一貫性を持たせつつ、両方の画面を同じにせずに済むようにしたいです。」

望ましい回答の構成：

• 画面間の連携モードを選ぶ
• 共通の基盤と、画面ごとの違いを定義する
• コンパクトなデザインシステムのパケットを 1 つにまとめる
• 共通の基盤とともに、コンポーネントファミリーの API を定義する

例 2：トークンとプリミティブのガバナンス

入力：「チームが場当たり的に色や間隔の値を追加し続けています。共有プリミティブの命名規則とレビュー方針が必要です。」

望ましい回答の構成：

• 基盤またはプリミティブのガバナンスモードを選ぶ
• トークンと命名規則、レビューの基準を定義する
• 命名例は 1 つか 2 つにとどめる
• 回答をページの完全なモックアップにしない

例 3：デザインシステムとレスポンシブ対応の混在する依頼

入力：「ダッシュボードとモバイル向け Web アプリで、ブレークポイントの方針を共通化すべきでしょうか。また、小さい画面ではレイアウトをどのように折りたたむべきでしょうか？」

望ましい回答の構成：

• 共通のブレークポイントと密度の方針は design-system に含める
• 実際の折りたたみ方針と検証は responsive-design に委ねる
• パケット内で分担を明確にする

例 4：アクセシビリティに重点を置いた追加依頼

入力：「トークンはすでにありますが、フォームのフォーカス表示とエラー状態のアクセシビリティに問題があります。」

望ましい回答の構成：

• デザインシステムの基本事項に簡潔に触れる
• 実際の修正と手動検証は web-accessibility に委ねる
• このスキルにアクセシビリティ修正全体を取り込まない

ベストプラクティス

1. まずモードを決めます。スキルの範囲を明確に保てます。
2. 例より先に共通ルールを定義します。1 つのモックアップに過度に合わせるのを防げます。
3. ガバナンスを明確にします。トークンの変更、プリミティブへの昇格、所有権のルールもシステムの一部です。
4. 早めに別の担当範囲へ振り分けます。design-system がレイアウト、アクセシビリティ、広範な監査まで扱うのを防げます。
5. ほかの人やエージェントが従える、コンパクトなパケットにまとめます。

参考資料

• システムモード
• トークンとガバナンスのチェックリスト
• 範囲の境界
• デザインシステムのパケットテンプレート
• レスポンシブレイアウト関連
• アクセシビリティ関連