design-system

design-system

指定されたデザインシステムを、名前付きトークン、対象スタックの流儀に沿った UI ライブラリ、検証可能なプレビューページ、3 つの登録先（ドキュメント、AGENTS.md の参照、プロジェクト UI スキル）に変換します。これにより、その後の UI 変更では個別のマークアップを直接記述せず、ライブラリを再利用できます。UI プロジェクトごとに /agents-md → /setup-matt-pocock-skills → プレースホルダーの入力の後に一度実行し、トリガーが発生したら extend を再実行します。

このスキルの対象外です。 1 ページをデザインとピクセル単位で一致させる作業は /pixel-audit、外観の QA の仕上げは /polish-batch、参照スタックからの UI の移植は /port-feature、既存 UI の追跡は /feature-discovery を使用します。

入力

リクエストと、手軽に確認できるリポジトリの情報から推測し、不足がある場合にのみ質問します。

• TARGET PROJECT-CODE — Project Matrix の完全なコードです。出力の流儀を決定します。Project Matrix がない場合は停止し、まず /agents-md に案内します。スタックはマトリックスまたは AGENTS.md から読み取り、決して推測しないでください。
• DESIGN-SYSTEM SOURCE（必須） — 指定されたソースを優先します。指定がない場合は references/source-selection.md を読み込み、記載された順序で探します。トークンを含むソースがある場合、それを唯一の信頼できる情報源とします。ソースがない場合、またはガイド付き定義が明示的に承認されていない場合は停止して確認し、決してシステムを捏造しないでください。

ルール

• 帰属表記は一切含めません。コミット、PR、課題コメント、リリースノート、生成ドキュメント、設定、コードコメントに、共同作成者、AI、ツールに関する帰属表記を追加したり残したりしないでください。このルールを、生成または更新する各指示ファイルに含めます。
• Project Matrix の完全な PROJECT-CODE をすべての箇所で使用し、別のプロジェクトの規約、トークン、コンポーネントを混在させないでください。
• 判断は成果物です。すべての出力をチャットではなくディスク上に保存します。
• 場所をハードコードしないでください。対象のスタック規約とセットアップ時の決定に基づいてパスを解決し、実際のパスをドキュメント、参照、スキルに記録します。
• サブエージェント：独立した作業はローカルのレーンに自動で割り当てます。クラウドエージェントは使用しません。割り当て時にレーン数を知らせ、各レーンの完了時に報告します。レーンは抽出と調査のみを行い、統合はメインエージェントが担当します。
• 各フェーズの切り替わり時に Stage / Found / Next / Needs user を出力します。各項目はそれぞれ 1 行にします。
• 提案のみとし、自動で次の処理に進みません。 次のステップを推奨したら停止します。ここでは機能の作業を開始しないでください。

スタックに適応した出力

ハードコードされたフレームワークに固定せず、対象の流儀に沿って出力します。フレームワークを使う Web アプリ（Laravel/Livewire、Rails、Django など）では、フレームワークのコンポーネントと、サーバーでレンダリングされるプレビュー用ルート（例：/ui/preview/all）を作成します。React Native ではライブラリとプレビュー画面を作成します。静的 HTML/PHP では HTML/CSS コンポーネントと静的プレビューファイルを作成します。それ以外の場合は、UI のレンダリング方法に最も近い形で作成します。

モード

bootstrap（デフォルト）

初回実行時の全工程です。既存のデザインシステムのドキュメントまたはライブラリがある場合は、extend に切り替えます。次の順に進めます。

1. 抽出 — ソースからトークンと、状態を含む基本コンポーネントの一覧を抽出します。
2. トークン — 色、タイポグラフィ、余白、角丸、影を、プロジェクトで既に採用されている仕組みを使って名前付きトークンとして定義し、インストール済みのフレームワークのバージョンに照らして確認します。使用箇所ごとにハードコードしてはいけません。ソースにライトモードとダークモードの定義がある場合は、トークンに両方を含め、プレビューで両方を表示します。
   • コントラスト： すべてのテキストと背景のトークンの組み合わせについて、WCAG AA に照らして確認します。本文は 4.5:1、大きなテキストは 3:1 とし、フォーカスインジケーターとコントロールの境界も確認します。ソースの組み合わせが基準を満たさない場合は、逸脱事項とユーザーへの確認事項に記録します。ソースの色を黙って変更してはいけません。
   • フォント： フォントトークンには、プロジェクトで読み込まれる書体を指定します。読み込めない書体は逸脱事項として扱い、黙ってフォールバックしてはいけません。
3. UI ライブラリ — トークンを使い、ソースに忠実な基本コンポーネント（ボタン、入力欄、セレクト、トグル、カード、アラート、バッジなど）を構築します。
4. プレビューページ — すべてのコンポーネントを各状態（デフォルト／ホバー／フォーカス／無効／アクティブ。該当する場合は空／読み込み中／エラー。レスポンシブ対応）で表示する 1 つのページ／ルート／画面を用意します。これは 2 つの段階からなる検証ゲートです。
   • エージェント側 — まず証拠を提示します。 対象をビルドして配信し、プレビューを読み込んで、抽出したすべてのコンポーネントがエラー出力なしで表示されることを確認します。レンダリングされたスクリーンショットを最低限の証拠とします。サーバーレンダリングのウェブ出力に限り、配信された HTML で代用できます。クライアントのみで動作するウェブスタックとネイティブスタックでは、ローカルのブラウザーまたはシミュレーターから取得したスクリーンショット、あるいはレンダリングされた DOM／ツリースナップショットが必要です。証拠を明記します。URL／ファイル、ステータス、スクリーンショットのパスまたは明記した代替手段、抽出した一覧と照合して確認済みのコンポーネント一覧を記載します。単なる合計数では証拠になりません。
   • 人間側 — ゲートです。 ワークスペースのポリシーで先に /agentic-qa が必要とされているにもかかわらず、その証明がない場合は、人による確認を保留として記録し、その QA の手順を提案します。自動で実行してはいけません。後から preview をリクエストされた場合、または次の extend の際に、その証明が揃っていればこの段階から再開します。該当する QA ゲートを通過したら、プレビューの場所を提示し、ユーザーに目視確認を依頼します。ユーザーが不在の場合は、プレビューの場所とエージェント側の証拠を伝え、フェーズの更新に目視確認が保留中であることを記録してから、提案に進みます。ユーザーが確認するまでは、デザインシステムの検証が完了したと主張してはいけません。 スナップショット用のハーネスがある場合は、基本コンポーネントごとに最小限のレンダリング／スナップショットテストを追加します。
5. 登録 — ドキュメント、AGENTS.md の参照、およびプロジェクトの UI スキル（以下）を作成します。

extend（再実行）

実行のきっかけ：デザインシステムが拡張された場合（新しい Figma コンポーネントの追加）、UI の変更で不足しているコンポーネントが必要になった場合、またはフィードバックループ（公開済みページの UI フローをライブラリに反映する場合）。

• 不足しているコンポーネント： まずライブラリを確認します。存在する場合は、構築するものはありません。その旨を伝えて終了します。不足している場合は、デザインシステムのソースに基づいて構築します。参照元がない場合は、構築前にユーザーに提示を依頼します。作り上げてはいけません。
• フィードバックループ： 公開済みページの差分を確認し、再利用可能な要素をそれぞれライブラリに追加します。公開済みの UI とソースに基づいて構築し、ページ固有の使い捨て要素は、理由を記録した場合に限り残します。
• 目視確認の保留： bootstrap で人間側の確認が保留になっていた場合は、同期の前にプレビューの場所を提示し、目視確認を依頼します。
• 同期： ライブラリ、プレビュー、ドキュメント、AGENTS.md の参照、およびプロジェクトの UI スキルをまとめて更新します。
• 境界 — デザインシステムのみ。 extend が更新するのはデザインシステムのみです。それ以外は更新しません。コミット、プッシュ、ADR の作成、引き継ぎの作成は行いません。これらは /grill-with-field と /commit-push-* の担当であり、「提案のみ・自動連鎖しない」のルールに従って個別に実行します。

登録

specs/design-system/ のドキュメント

ドキュメント全体を <docs-root>/design-system/<TARGET-PROJECT-CODE>-design-system.md に記述します。<docs-root> はセットアップドキュメントの保存場所です。セットアップに関する決定がない場合は、<artifacts-root>/specs/ を使います。<artifacts-root> は、存在する場合は *.code-workspace のディレクトリ、なければコンテキストごとのルート（リポジトリのルートにある GLOSSARY-MAP.md、または旧形式の CONTEXT-MAP.md）、それもなければリポジトリのルートとします。references/registration-templates.md の §1 にあるドキュメントのひな形を埋めます。

AGENTS.md の参照

/agents-md の構成に従い、PROJECT-CODE をキーにした簡潔な参照のみを追加します。extend の場合は既存の参照を更新し、重複させないでください。デザインシステム全体を AGENTS.md に記載してはいけません。AGENTS.md からドキュメントを参照する形にします。references/registration-templates.md の §2 を埋めます。

プロジェクトの UI スキル

実際の UI 作業に関する詳細なリファレンスです。プロジェクト固有の UI ルールはすべてこのスキルとドキュメントに記載し、/design-system には記載しません。

• まず既存の UI スキルを検出します： <project>/.agents/skills/ とランタイムディレクトリ（.claude/skills/、.cursor/skills/ など）を調べ、このプロジェクトの UI 作業をすでに担当しているスキルがないか確認します。
• 見つかった場合 → そのスキルを採用し、既存の場所で拡張します。隣に別のスキルを作成してはいけません。 2 つの UI スキルがあると、振り分け先が競合します。実際のパス、コンポーネント一覧と状態、既存のものを新規作成より優先する方針、コンポーネントがない場合の手順、ライブラリを利用するルールを盛り込みます。UI 作業が引き続きそのスキルに振り分けられるよう、説明を明確にします。
• 既存のスキルで培われた規約や文体を保ちます。差分を示し、既存のルールがデザインシステムと矛盾する場合は、どちらも黙って書き換えず、ユーザーにその矛盾を伝えます。
• 採用したスキルの実際の名前を、ドキュメントの Project skill: 行と AGENTS.md の参照に記録します。
• UI スキルがどこにも存在しない場合に限り、プロジェクト内に <project-slug>-ui-coding（ターゲットの命名規則に従った kebab-case）を作成します。配置場所、ランタイムごとのコピー、内容については references/fresh-ui-skill.md を読みます。

出力

フェーズの更新を出力して終了します。

Stage: design-system (<bootstrap|extend>) — tokens+library+preview for <TARGET-PROJECT-CODE>; doc <docs-root>/design-system/<TARGET-PROJECT-CODE>-design-system.md; AGENTS.md reference added; <ui-skill name> seeded/extended.
Found: <N> tokens, <M> components (<states covered>); source = <DESIGN.md|project UI skill/library|Figma|spec|reference|guided(approved)>; contrast <all AA | N failing pairs>; stack = <from matrix>.
Next: <required agent QA pending: run /agentic-qa; otherwise open preview and inspect every component/state>. Then /feature-prompt for the first feature.
Needs user: <agent QA pending: start the required QA; otherwise verify the preview>; confirm guided choices, failing contrast pairs, or DS/stack deviations.

Suggested next skills (optional):
- /feature-prompt: begin the first feature — it consumes this library.
- /pixel-audit: per-page conformance during that feature work (not here).

提案以降の作業には進まないでください。

完了条件

• トークン、ライブラリ、プレビューが存在し、ドキュメントに記録されたパスに配置されている
• エージェント側の手順に従ってプレビューの証拠が引用されている。ハーネスが存在する場合はレンダリングテスト／スナップショットテストが合格している
• <docs-root>/design-system/<TARGET-PROJECT-CODE>-design-system.md が存在し、ディスク上にあるスキルの名前を記載した Project skill: 行がある
• AGENTS.md に TARGET PROJECT-CODE のデザインシステム参照が 1 つだけ記載されている
• フェーズの更新に、目視確認が完了または保留であることが記録され、その後は何も実行されていない
• extend を実行した場合：git log にこの実行で作成された新しいコミットがない