design-system

デザインシステム

価値： コミュニケーション -- 文書化されたデザインシステムは、あらゆるビジュアル上の判断に共通の語彙をもたらします。理念が明確で、トークンに名前が付けられていれば、貢献者は意図を推測することなく、一貫性を保ちながらシステムを拡張できます。

目的

デザインシステム仕様の共同作成を促進します。理念、トークン、アトムからテンプレートまでのコンポーネント階層全体を記録する成果物を生成します。Pencil MCP が利用可能な場合は docs/design-system.pen に、利用できない場合は単一ファイルの代替形式として docs/design-system.html に生成します。

実践方法

成果物の形式を判定する

mcp__pencil__get_editor_state ツールが利用可能かどうかを確認します。

• 利用可能： .pen 形式を使用します。references/pencil-workflow.md に従います。
• 利用不可： HTML 形式を使用します。references/html-artifact.md に従います。

デザイン作業を始める前に形式を決定します。作業の途中で形式を切り替えてはいけません。

7 フェーズの共同プロセスに従う

方法論の全容については、必ず references/design-phases.md に従ってください。各フェーズを完了してから次のフェーズに進みます。

各フェーズの概要：

1. 理念と制約 -- ブランド、原則、アクセシビリティ、レスポンシブ戦略、制約を定めます。以降のすべての判断は、ここに基づきます。
2. デザイントークン -- 色、タイポグラフィ、間隔、角丸、エレベーション、モーション、ブレークポイント、不透明度を定めます。各トークンには、根拠となる理念の原則を示します。
3. アトム -- 分割できない要素（ボタン、入力欄、ラベル、アイコン）です。それぞれの状態を記録し、トークンのみを参照します。
4. モレキュール -- アトムで構成される機能単位（フォームフィールド、検索バー）です。構成とインタラクションを記録します。
5. オーガニズム -- モレキュールとアトムで構成される独立した UI セクション（ヘッダー、フォーム、データテーブル）です。レイアウトの振る舞いを記録します。
6. テンプレート -- オーガニズムを配置したページレイアウトです。構造、コンテンツの配置領域、ブレークポイントごとの振る舞いを定義します。
7. 成果物の組み立て -- 理念を最初のセクションとして、選択した形式にまとめます。

決めつけず、ファシリテーションする

あなたの役割は書記ではなく、ファシリテーターです。各フェーズで掘り下げた質問をしてください。表明された理念に反する選択には異議を唱えてください。質問集として references/facilitation-questions.md を使用します。

1. ビジュアルの好みを決めつけず、質問する
2. ユーザーの回答が部分的でも先に進まず、さらに掘り下げる
3. docs/event_model/ にイベントモデルのワイヤーフレームがある場合は、必要なコンポーネントを特定するために使用します。ただし、ユーザーへの確認は必ず行います
4. 理念に基づいたトークン案を提示し、調整が必要か確認する

理念とのトレーサビリティを徹底する

すべてのデザイン上の判断を理念に結び付けます。

• トークンには、対応する理念の原則（例：P1）を記載します
• アトムには、使用するトークンを記載します
• モレキュールには、構成するアトムを記載します
• オーガニズムには、構成するモレキュールとアトムを記載します
• テンプレートには、配置するオーガニズムを記載します

トークンの根拠となる原則を示せない場合、そのトークンが不要か、理念が不完全です。次に進む前に解決してください。

行うこと：

• ビジュアル上の判断を始める前に理念を定める
• コンポーネントではトークン参照のみを使用し、具体的な値は直接指定しない
• 次のフェーズを始める前に、各フェーズを完了する
• すべての階層でトレーサビリティを確認する
• トークンに関する包括的なガイダンスとして references/token-categories.md を参照する

行わないこと：

• 技術上の判断（CSS フレームワーク、コンポーネントライブラリ）を行う -- これらはアーキテクチャの意思決定で扱います
• 理念のフェーズを省略したり、任意のものとして扱ったりしない
• コンポーネントで色コード、ピクセル値、フォント名を直接使用しない
• 複数のフェーズを同時に進めない
• 不明点を残したまま進めない -- 定義されていないことがあれば質問する

適用に関する注記

すべてのモードで助言として適用されます。フェーズゲートは自己管理です。エージェントは各フェーズの成果物を完成させ、次に進む前にユーザーの確認を得る必要があります。トークンの追跡可能性も自己管理です。エージェントは、各コンポーネントが生の値ではなくトークンを参照していることを確認する必要があります。

厳格な制約：

• フェーズの順序（次のフェーズを開始する前に各フェーズを完了する）：[RP]

制約

• 「コンポーネントに生の値を含めない」：これは、コンポーネント定義内のどこにも、色コード、ピクセル値、フォントサイズ、間隔の値を直接記述しないという意味です。「そのためのトークンを定義した」だけでは不十分です。コンポーネントファイルにトークン参照ではなく生の値が含まれている場合は、違反になります。再利用性を損なう単回使用のトークンを多数定義して、形式的にこのルールを満たすことも違反です。
• 哲学フェーズ：哲学とは、意思決定の指針となる十分な具体性を備えた、名前付きの原則を意味します。「モダンでクリーン」は哲学ではありません。何の制約にもならないからです。各原則は検証可能である必要があります。あるデザイン上の決定に対して、その原則が選択肢を選ぶ助けになるかどうかを確認してください。どの選択肢も除外できないのであれば、具体性が不十分です。

検証

このスキルに沿った作業を完了した後、次の項目を確認してください。

• コンポーネントを作成する前に、名前付きの原則を用いて哲学を文書化した
• すべてのビジュアルカテゴリ（色、タイポグラフィ、間隔、角丸、エレベーション、モーション、ブレークポイント、不透明度）にトークンを定義した
• すべてのトークンに哲学の原則を引用した
• アトムはトークンのみを参照している（生の値なし）
• 分子はカタログ内のアトムのみで構成されている
• 有機体はカタログ内の分子とアトムのみで構成されている
• テンプレートはカタログ内の有機体のみを配置している
• すべてのコンポーネントの状態（該当する場合はデフォルト、ホバー、フォーカス、無効、エラー）を文書化した
• イベントモデルがある場合、ワイヤーフレームのフィールドをコンポーネントに対応付けた
• docs/design-system.pen または docs/design-system.html に成果物がある
• 成果物では哲学が最初のセクションになっている

基準を満たしていない項目がある場合は、該当するフェーズに戻って作業してください。

依存関係

このスキルは単独で機能します。より高度なワークフローでは、次のスキルと連携します。

• event-modeling： イベントモデリングのセッションで作成するワイヤーフレームにより、デザインシステムに含める必要のあるコンポーネントを特定できます。最良の結果を得るには、先に event-modeling を実行してください。
• architecture-decisions： デザインシステムの仕様は、UI 実装に用いる技術（CSS フレームワーク、コンポーネントライブラリ、ビルドツール）に関する意思決定の参考になります。architecture-decisions より先に design-system を実行してください。
• atomic-design： デザインシステムの仕様から、atomic-design がコードで実装するトークン定義、コンポーネントカタログ、階層が提供されます。
• tdd： トークンの値とコンポーネントの仕様は、テスト可能な契約になります。ビジュアルリグレッションテストでトークンへの準拠を確認します。

依存関係が不足していますか？次のコマンドでインストールしてください：

npx skills add jwilger/agent-skills --skill event-modeling