agentic-design-systems

エージェント向けデザインシステム

このスキルが呼び出されたときは、主な利用者が AI エージェントであるコンポーネントライブラリの構築、拡張、監査を支援します。目指す水準は、*「破壊的なアクションを伴う確認モーダルを作って」*といった文章でのリクエストを受けたエージェントが、パターンを勝手に作り出すことなく、適切なコンポーネント、適切なバリアント、適切なトークンを選べることです。

このスキルでは、スキーマ、ワークフロー、原則を紹介します。ユーザーの状況に合わせて調整してください。

---

まず状況を見極める

何かを生成する前に、どのモードが当てはまるかを判断してください。

• 新規構築 — ユーザーはエージェントが利用することを想定した新しいシステムを始めようとしています。構築ワークフローに沿って進めます。スキーマと、動作例となるコンポーネントを1つ（標準は Button）から始め、すべてを一度にひな形化しようとしないでください。
• 既存ライブラリの改修 — ユーザーはコンポーネントライブラリを持っていて、エージェントが読み取れるようにしたいと考えています。ワークスペースのセットアップは省略します。まず meta.types.ts を追加し、次にコンポーネントごとに .meta.ts を作成してから、インデックスとバリデーターを構築します。アンチパターンから着手してください（Step 5を参照）。
• 監査 — ユーザーはすでにメタデータを用意しています。4つの柱とバリデーターのチェック項目に照らして、各コンポーネントを評価します。欠落している関係性、文章によるアンチパターン、グローバルトークンの直接使用、根拠のないバリアント軸を指摘してください。
• 単一コンポーネント — ユーザーは1つのコンポーネントを追加または修正したいと考えています。Step 3に従い、必要なファイル一式を生成します。メタデータはコンポーネントと一緒に含めるか、含めないかのどちらかです。

プロンプトが曖昧な場合は、的を絞った質問を1つしてください。推測で進めないでください。

---

4つの柱

すべてのコンポーネントを、4つの要素が交わるものとして扱ってください。ほとんどのメタデータスキーマがモデル化するのは最初の要素だけです。そのため、エージェントはコンポーネントを誤用します。

柱	答える内容	欠けている場合に起きる問題
Props	何を設定するか	（常に存在します）
Variants	どの組み合わせを選ぶか	エージェントが無効な組み合わせを選びます
Relationships	構造上およびアクセシビリティ上、コンポーネントがどこに位置するか	エージェントはコンパイルできても、構造的には誤ったコードを生成します
Tokens（コンポーネントスコープ）	どのデザイン値をこのコンポーネントに割り当てるか	エージェントが色や余白を勝手に作り出します

さらに aiHints があります。これは、コンポーネントをいつ使うか、どの状況にどのバリアントが適しているか、そして決してしてはいけないことをエージェントに伝えるメタレイヤーです。

スキーマに組み込まれた4つの設計上の決定事項

• 状態は独立した柱ではなく、トークンに暗黙的に含まれます。 button-primary-bg-hover、button-primary-bg-disabled などを定義します。テーマの切り替えはトークンの差し替えで済み、信頼できる唯一の情報源になります。
• バリアントはフラットな列挙型ではなく、マトリックスです。 軸（appearance × size × density）を定義し、エージェントがセルを選べるようにします。出荷すべきでないセルには invalidCombinations を使います。
• アクセシビリティは Relationships に含まれます。 ARIA の role、keyboardSupport、screenReader は、コンポーネントがドキュメントやインタラクションモデルにどのように適合するかを示すため、関係性に属します。アクセシビリティの柱を別に設ける必要はありません。
• アンチパターンは第一級の要素として構造化します。 文章で書いてはいけません。必ず {scenario, reason, alternative} の3要素の組にします。これにより、正確さが強制されます。

---

スキーマ（正式な契約）

これを meta.types.ts に一度だけ記述します。各コンポーネントの .meta.ts はこれをインポートし、型チェックを受けます。スキーマが契約そのものです。

interface ComponentMeta {
  component: {
    name: string;
    category: "atoms" | "molecules" | "organisms";
    type: "interactive" | "display" | "container" | "input" | "navigation";
    description: string;
    path: string;
    figma?: { nodeId: string | null };
  };

  props: Record<string, PropDef>;

  variants: {
    axes: Record<string, readonly string[]>;
    purpose: Record<`${string}.${string}`, string>;
    invalidCombinations?: { axes: Record<string, string>; reason: string }[];
  };

  relationships: {
    requires?: string[];           // contexts/providers above
    mustBeChildOf?: string[];
    mustBeParentOf?: string[];
    optionalSibling?: string[];
    commonPartners?: string[];
    triggers?: string[];           // events emitted
    blocksWhen?: { when: string; effect: string }[];
    exposesState?: string[];       // state descendants can read
    role: string;                  // a11y
    keyboardSupport: string;
    screenReader: string;
  };

  tokens: {
    color?: Record<string, string>;
    spacing?: Record<string, string>;
    typography?: Record<string, string>;
    border?: Record<string, string>;
    motion?: Record<string, string>;
    elevation?: Record<string, string>;
  };

  aiHints: {
    priority: "high" | "medium" | "low";
    keywords: string[];
    selectionCriteria: Record<string, string>;
    usage: {
      useCases: string[];
      commonPatterns: { name: string; composition: string }[];
      antiPatterns: { scenario: string; reason: string; alternative: string }[];
    };
  };
}

コンポーネントの .meta.ts を生成するときは、該当するフィールドをすべて埋めてください。空の配列は問題ありませんが、キーの欠落は許されません。バリデーターが検出するのはそれです。

---

構築ワークフロー

Step 1 — ワークスペースの構成

利用するアプリのモノレポ内に、隣接するパッケージ（packages/ui-next/）を作るよう提案します。後で切り替える場合も、インポートを書き換えるだけです。別リポジトリにするのは、独立したバージョン管理が必要な場合に限ります。

Step 2 — TypeScript の契約としてのスキーマ

コンポーネントを作る前に meta.types.ts を記述します。それ以外のすべては、ここから派生します。

ステップ 3 — コンポーネントを 1 つ、エンドツーエンドで構築する

小規模で利用頻度の高いものを選びます。ボタンが定番です。必要なもの一式をまとめて提供します。

Button/
  Button.tsx              ← implementation
  Button.meta.ts          ← four pillars + aiHints
  Button.tokens.css       ← component-scoped tokens
  Button.stories.tsx      ← visual test surface
  Button.test.tsx         ← behavior tests
  index.ts                ← single canonical export

Storybook を早い段階で設定します（ストーリーの検出には .storybook/main.ts、テーマのインポートには .storybook/preview.ts を使用します）。バリアントの組み合わせ表の各セルにストーリーを 1 つずつ用意すると、デザイン空間のリグレッションがひと目でわかります。

メタデータはコンポーネントと一緒に提供するか、提供しないかのどちらかです。後回しにしてはいけません。

ステップ 4 — 2 階層のトークン

• tokens/core.css — ブランドカラーの生のパレットとスケール（--color-brand-600、--space-4）。
• tokens/themes/*.css — コンポーネントスコープのトークン（--button-primary-bg）をコア値にマッピングします。

コンポーネントの CSS から参照するのは、コンポーネントスコープのトークンだけです。テーマの切り替えは機械的に行えます。

ステップ 5 — アンチパターンを先に

コンポーネントごとに、実装を書く前に antiPatterns 配列を記述します。構造化された 3 項目の形式（scenario、reason、alternative）によって、内容を正確に記述せざるを得ません。「プライマリボタンを使いすぎない」と書くのではなく、どのようなシナリオで、なぜ間違いで、代わりに何をすべきかを記述します。最終的に、アンチパターンが API の設計を導きます。

ステップ 6 — 座標系としてのバリアント軸

バリアントは文字列のフラットなリストではありません。軸（appearance × size × density）を宣言し、エージェントが独立した次元ごとに選択できるようにします。公開すべきではない組み合わせ（例：appearance: "ghost" × size: "xs" — タップするには小さすぎます）は invalidCombinations で除外します。

ステップ 7 — 機械で検証できるルールとしての関係性

• requires — 上位に存在しなければならないプロバイダー
• mustBeChildOf / mustBeParentOf — 構造上の制約
• triggers — 発行されるイベント
• blocksWhen — プロパティの状態に依存する振る舞い
• exposesState — 子孫が読み取れる状態

これが、コンパイルはできても構造的に誤ったコードをエージェントが生成するのを防ぐ柱です。

ステップ 8 — 階層型メタデータインデックス

metadata/index.json を生成します。内容は {name, category, path, keywords, priority} のフラットなリストです。エージェントはまずこれをスキャンして候補を絞り込み、関連するコンポーネントについてのみ、完全な .meta.ts を読み込みます。低コストの検索と、詳細な情報の取得を両立できます。

各 *.meta.ts を走査して動的にインポートし、JSON を書き出すスクリプト（scripts/build-index.ts）でビルドします。メタデータを変更するたびに実行し、インデックスが実際の内容と食い違わないようにします。

ステップ 9 — メタデータバリデーター

短いスクリプト（scripts/validate-metadata.ts）で *.meta.ts をすべて（fast-glob を使用して）走査し、動的にインポートして、エクスポートの形状をチェックし、以下を検証します。

• すべてのバリアント軸の組み合わせが aiHints.selectionCriteria または variants.purpose に記載されている
• すべての tokens.* キーがコンポーネントスコープになっている（コンポーネント名をケバブケースにしたもの）
• priority: "high" のコンポーネントでは antiPatterns が空でない
• relationships.role / keyboardSupport / screenReader が空でない（「アクセシビリティを Relationships に統合する」という決定を徹底します）
• invalidCombinations が宣言済みの軸の値のみを参照している

CI で実行します。メタデータに誤りがあれば、ビルドは失敗します。スキーマは願望ではなく、確実に適用されます。

ステップ 10 — 切り替え（一斉ではなく、コンポーネントごとに）

最後にまとめて切り替えるのではなく、同等性が確保できたコンポーネントから順に切り替えます。

• API 同等性トラッカー — 古いライブラリのエクスポートと新しい同等機能を対応付けた Markdown のチェックリスト。
• トークンブリッジ — 古いトークンを新しいコンポーネントスコープのトークンにマッピングします。
• Codemod — ページごとにインポートを書き換えます。

---

原則

• 自動生成より簡潔さを優先します。 最初の約10個のコンポーネントのメタデータは手作業で記述します。パターンが明確になってから自動化します。
• 直接インポートし、バレルファイルは使いません。 コンポーネントごとに正規のパスを1つにします。方法が2つあると、エージェントが誤った方を選びます。
• すべてを同じ場所に置きます。 コンポーネント、メタデータ、トークン、ストーリー、テストを1つのフォルダーにまとめます。
• アンチパターンを設計の指針にします。 まずアンチパターンを記述します。これにより契約が明らかになります。
• コンポーネントスコープのトークンを使います。 コンポーネントの CSS からグローバルトークンを直接参照してはいけません。
• 状態はトークンで表現します。 states ブロックも、behavior.states 配列も使いません。
• アクセシビリティは関係性に基づきます。 独立した柱ではなく、Relationships に含めます。
• スキーマが契約です。 バリデーターは CI で実行し、メタデータに不備があればビルドを失敗させます。

---

成功の状態

ユーザーが Figma のスクリーンショット、または「破壊的な操作を含む確認モーダルを作成して」という文章のリクエストをエージェントに渡すと、エージェントは次のように動作します。

1. metadata/index.json をスキャンし、Modal、Button、Heading を候補として絞り込みます。
2. 候補となった各コンポーネントの .meta.ts を読み込みます。
3. Button.relationships.mustBeChildOf に ModalFooter が含まれていることを確認し、aiHints.selectionCriteria から appearance: "danger" を選びます。
4. antiPatterns で注意されているため、appearance: "primary" の兄弟要素を2つ使うのを避けます。
5. コンポーネントスコープのトークンを参照し、色を勝手に作りません。
6. 最初から契約に従ったコードを生成します。

目指すのはこの状態です。メタデータによってエージェントをこの結果に導けない場合は、メタデータを修正してください。