build-design-system

デザインシステムを構築する

1. 実行の枠組みを定めます：モードと基盤、基準となるリファレンス、パイロット、デフォルトを適用した Frame の質問、実行ブランチ、.design-system/run.md（references/modes.md、references/run-record.md、references/coordinator-path.md の Start）。
2. 規模を決めます：小規模アプリ向けの手順、またはメモリ圧から読み取ったマシンの予算内で並列展開します（references/coordinator-path.md の Small app と Machine budget）。
3. スクリプトを使ってインベントリを作成し、編集前にすべての画面を記録します（references/inventory.md、references/browser.md）。
4. 用途に基づいてトークンに名前を付けます：同一値の置換、判断として許容範囲内の値を統合し、それを超えた場合は統合をデフォルトとするゲートを設けます（references/token-architecture.md）。
5. コンポーネント：最もよく使われるファミリーを最初から最後まで扱い、その後、残りを並列展開します（references/component-contract.md、references/rule-method.md、references/worker-brief.md）。
6. 事前に仕込んだ違反で失敗するチェック、ラチェット、2段階の CI を用意します（references/checks.md）。
7. パイロットのフローをシステム上で実行し、ベースラインと比較してレビューします（references/browser.md）。
8. パイロット外で安全に実施できる変更を行い、許可が下りた場合のみ移行します（references/coordinator-path.md、Clearance）。
9. ドキュメント、生成された対になるファイル、AGENTS.md のインデックスを整えます（references/system-structure.md）。
10. 引き継ぎ：数値を確定し、未回答のデフォルト項目を最初に示し、発見した未修正事項を一覧にします（references/run-record.md、Handoff report）。

決してリリースしないもの：

• アプリに存在しない色、フォント、影、グラデーション、モーションの値。ただし、デザインソースを選び、サンプルを確認した場合を除きます（references/modes.md）。
• 開始時のブランチ上でのコミット、プッシュ、公開、デプロイ。
• ベースライン、フィクスチャ、チェックの編集。代わりにコードを修正してください。
• 安全な変更でも許可済みの画面でもない、パイロット外の変更。
• レンダリング結果ではなくソースから読み取ったアクセシビリティやコントラストの結果。
• スクリプトで算出していない件数、または失敗するところを一度も確認していないチェック。
• 人が禁止した事項を Don't: 行以外に記載すること。

token-mapping、component-docs、ui-review を呼び出し、同じ内容を繰り返しません。基盤のベースリファレンス（references/base-*.md）は、一般的なリファレンスより優先されます。

コーディネーターから呼び出された場合

コーディネーターは、対象、パイロット、予算、実行ブランチ、実行記録のパスを引き継ぐ場合があります。それ以外は Inputs のデフォルトに従います。質問する代わりにゲートを実行記録へ記載し、引き継ぎレポートまたは停止時の形式を返します。返信はステータス行から始め、その後に Commit: <run branch head> を記載します。design-system-boss の配下では、boss のルールと上限が適用されます。サブエージェントとして、ワーカーはフォアグラウンド呼び出しで実行し、実行中のワーカーがある間は決して返答しません。

完了

実行はチェックを優先して終了します（references/modes.md）。フェーズ 1 の判定条件を満たし、すべての数値をフェーズ 8 で測定します：「N 個の正規コンポーネントが、インベントリにある M 個のファミリーをカバーし、すべてのトークンに役割があり、チェックは事前に仕込んだ違反で失敗し、クリーンなクローンで終了コード 0 となり、パイロットは一覧にある意図的な変更を除いてベースラインと一致している。」失敗している項目は失敗として報告します。判定条件を決して緩和しません。

• すべてのトークンに役割が明記され、すべての安全な変更が実施され、その根拠が確認されています（references/run-record.md、Terms）。
• パイロットで使用する正規コンポーネントにはすべてレジストリエントリがあり、node scripts/check-spec.mjs docs/system を通過する仕様があります。また、レジストリに登録されたコンポーネントのうち、プレーンエントリのまま未対応のものは 0 件です。
• クリーンなクローンでフルチェックが終了コード 0 となり、今回のセッション中にすべてのルールについて、対応する不正なフィクスチャで失敗することが確認され、すべてのルートが本番ビルドで 200 を返します。
• パイロットのキャプチャに含まれるすべての差分と、パイロット外のすべてのコミットは、判断またはゲートに結び付けられています。
• 引き継ぎレポートは references/run-record.md に従い、すべての件数は .design-system/close.md に基づいています。

モードと対象範囲に応じたその他の完了条件は、references/coordinator-path.md（Close）に記載されています。停止する場合は、停止条件、完了した成果物、実行記録のパス、作業再開に必要な最小限の返信内容を返します。

入力

各行にリポジトリの情報またはデフォルト値を入力します。パスを尋ねることはありません。

入力	欠けている場合
書き込みアクセス権のあるリポジトリ	停止します。スクリーンショットから構築したシステムには、強制できるコードがありません
アプリを実行する方法	dev または start スクリプトを試します。何も起動しない場合は、コードからフェーズ 3、4、5、7 を実行し、パイロットを省略して「コード完了、ランタイム検証なし」と報告します
モノレポ内の対象アプリ	The Frame の対象を特定する質問（references/run-record.md、Questions）を使います。その間、候補ごとにフェーズ 2 の読み取り専用スクリプトを実行します
パイロットフロー	苦情に記載された画面を使います。記載がなければ、最も多くのファミリーを使用し、エラー状態のあるフォームを含むフローを使います。同数の場合は high ティアのフローを優先します。それもなければパターンページ（references/modes.md）を使います
予算	The Frame の「Go, 」という返信を使います。なければホストのセッションを使い、それもなければ references/coordinator-path.md（フェーズの上限）を使います
テーマ	アプリに含まれるものを使い、新しいテーマは追加しません
モードと基盤	ルーターのトリアージ結果を使います。なければ references/modes.md を使います
既存のトークン、ライブラリ、デザイン仕様またはブランド	基本リファレンスと references/modes.md（質問の判断基準）に従って、これを起点にします
ユーザーの言葉と保存されたメモリ、AGENTS.md、CLAUDE.md	ブランチとプッシュのポリシーも含め、これらを本ファイルより優先します

シェル、git、Node が必要です。

手順

他のファイルでは、冒頭のリストではなく、これらのフェーズ番号を参照しています。各フェーズは成果物のパスと判断行を記録して終了し、上限に達した時点で停止します（references/coordinator-path.md、フェーズの上限）。共有 UI またはトークンを編集した後は、capture.mjs --status で、すべてのルートが読み込まれていることを確認する必要があります（references/browser.md）。

1. フレーム。 エージェントへの指示、マニフェスト、スタイルのエントリーポイント、テーマプロバイダー、ルートツリーを読みます。苦情を本人の言葉で書き、応える最初の目に見える変更、件数を空欄にした述語、常設の指示を記します。ビューポートには、アプリがサポートする最も狭い幅と最も広い幅を指定します。デフォルトは 390 px と 1280 px です。フットプリントを設定して node scripts/check-system.mjs --init を実行し、ファンアウトの前に Lock を確定します。待たずにフェーズ 2 を開始してください。
2. インベントリ。 スクリプトを実行し、各サーフェスとその状態およびティアを列挙して、capture.mjs --kind before コマンド 1 回でキャプチャーします。アニメーションの一覧を記録し、パイロットのトラップを測定します。ファミリーをグループ化し、重複を示して、references/traps.md のレンダリング済みスタイルの確認を実行します。使われていないものを削除し、専用のコミットにまとめます（references/inventory.md、Delete plan）。コーディネーターがまだ対応していない場合は、トークンのコミット直後に migrate-design-system を監査モード、読み取り専用で開始します。
3. 基盤。 生の値をカテゴリと役割ごとにまとめ、サーフェスと前景色のペアを持つセマンティックトークンにします。token-mapping の許容範囲内での統合は確定事項です。許容範囲を超える場合は、各クラスターにつきゲートを 1 つ設けます。デフォルトは統合とし、最大の変化と影響を受ける画面を明記して、すべてのデフォルトを今すぐトークンファイルに適用します。セットアップにジェネレーターがある場合は、それを作成します。完全なインベントリに対して token-mapping を実行し、すべての生の値が役割、統合、または一覧に記載された例外のいずれかに対応するまで続けます。すべてのルートで、値が同一のものをすべて置き換えます。変更されたルートを移行マップに記載します。AGENTS.md ブロックを記述し、モーションプリセットとアイコンサイズを指定します。また、本人がブラウザーでレビューする際にライブショーケースを開始します（references/system-structure.md）。
4. コンポーネント。 コントラクトに基づいて、各コンポーネントの標準実装を選びます。依頼で状態が指定されている場合、各コンポーネントに不足している状態を追加します。最もよく使われるファミリーから、コンポーネント、テスト、ショーケースページ、ルールを含む仕様を 1 つのコミットで最初から最後まで実装します。ファンアウトの前に、そのページを見せます。旧実装から新実装へのマップと、手動で移行したパイロット画面に一致する codemod を作成するか、存在しない理由を記録します。パイロットと残りの項目が使用するファミリーをファンアウトし、ブリーフの範囲外の差分は却下します。置き換えられたラッパーは非推奨にしますが、標準の基盤コンポーネントは非推奨にしません。references/coordinator-path.md に従って完了します（Components close）。
5. チェック。 references/checks.md に従います。フェーズ 6 の前にチェックが 0 で終了することを確認します。node scripts/check-system.mjs --self-test --fixtures <skills>/build-design-system/fixtures/check-system を実行し、リリース済みのルールを検証します。
6. パイロット、その後に安全な移行。 codemod を使ってパイロットを移行し、すべての差分を確認します。ベースラインと同じビューポート、テーマ、データを使って移行後をキャプチャーします。追跡できない差分は欠陥です。レンダリングの変更をキャプチャーレポートなしで行った場合は checks-only として報告します。キーボードで操作してフローを確認し、エラー状態と読み込み状態を発生させ、すべてのトラップを前後で測定します。移行後のキャプチャーに対して ui-review を実行します。既存のトークンやコンポーネントで対処できる変更と、動作の不具合は修正します。それ以外はゲートにします。その後、安全な移行を 1 サーフェスにつき 1 コミットで取り込みます（references/coordinator-path.md、実行ブランチの Surfaces）。
7. ドキュメント。 仕様がない標準コンポーネントがあれば、component-docs を実行します。基盤のページ、共通の状態パターン（references/system-structure.md）、ライティングのページ（references/writing-method.md）を記述します。node scripts/gen-docs.mjs を実行します。初回の実行では --name を指定し、docs/system/writing.md が作成されたら copy-check.mjs をチェックに追加します。その後、レビューして判断し、修正します（references/coordinator-path.md）。最後に再生成します。
8. 引き継ぎ。 インベントリのスクリプトを再実行し、各コンポーネントを評価して述語を埋めます。フルフットプリントの場合は、プロジェクトのスキルを記述します。新しいエージェントでの試行を実施し、references/coordinator-path.md に従って完了します（Close）。

境界

次の場合に限り、作業を止めて確認してください。

• リポジトリにアクセスできない場合。
• 別のパッケージまたはパブリック API がエクスポートしているものに影響する削除。
• パッケージの公開や共有リモートの変更など、git で元に戻せない手順。

次の場合はデフォルトを設定して、誰からも回答がなくても作業を続けてください。

• コード内で値が2通りに記述されているブランドカラー、書体、ロゴ。
• 「Plan」や「Workspace」など、製品に関わる語を含む名前。
• 許容範囲を超えるマージ、または公開済み画面を変更するバリアントの削除。
• プロジェクトのルールでは解決できない、コードと仕様書または古いドキュメントとの不一致。
• リンクの色または下線の変更。影響するすべての箇所を列挙してください。メインコンテンツ内のリンクには、通常時も視認できる手がかりを残してください。
• 変更範囲。リポジトリが他者のものに見える場合、または依頼に PR や上流リポジトリへの言及がある場合。デフォルトは最小限（references/coordinator-path.md）です。