build-design-system

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

用語集は references/glossary.md、禁止事項と幅のデフォルトは references/taste.md にあります。アプリ独自の見た目を基準にしてください。本人がデザインの参考元を選び、サンプルを確認した場合を除き、アプリにない色、フォント、影、グラデーション、モーションの値を創作してはいけません。

スクリプトはこのスキルの scripts/ にあります。リポジトリのルートから node で実行し、先に --help を読んでください。scripts/capture.mjs は scripts/capture-guard.mjs の背後でスクリーンショットを撮影します。このガードはすべての書き込みをブロックし、scripts/pixdiff.mjs はスクリーンショットを比較します。capture と pixdiff には Playwright と Chromium が必要です。scripts/find-chromium.mjs が Chromium を探すか、インストール方法を説明します。

手順

1. 枠組みを定める。 AGENTS.md または CLAUDE.md、マニフェスト、ルートツリーを読みます。本人の言葉で不満点、それに応える最初に見える変更、パイロットのフロー（不満点で言及されたフロー、そうでなければコンポーネントファミリーが最も多く、エラー状態のあるフォームを含むフロー）を書きます。.design-system/ を .git/info/exclude に追加し、メモ、キャプチャ、スクラッチファイルが決してコミットされないようにします。本人が指定したブランチを作業ブランチとして使います。指定がなければブランチを切り、開始時のブランチを .design-system/start-branch に書きます。land.mjs はこのファイルがあると処理を拒否します。references/taste.md を禁止項目が未選択の状態で一度提示し、承認されたコピーを .design-system/taste.md に保存します。それ以外は何も質問しません。回答がなければデフォルトを採用し、default (unanswered) と記録して続行します。 不満点、パイロット、ブランチ、承認済みの taste ファイルが記録されていれば完了です。

2. 一覧作成とベースライン。 すべての画面、各画面の状態、データを書き込むかどうかを一覧にします。scripts/check-system.mjs --no-allowlist --no-self-test --json で、出現回数に基づき生の値（#fff、text-gray-500、p-[13px]）を数え、コンポーネントをファミリーごとにまとめます。編集前に、最も狭い幅と最も広い対応幅（デフォルトでは 390 と 1280）で、各画面のすべての状態をキャプチャします。各幅で新規にナビゲーションを1回行ってください。アプリを起動した状態（ここではポート 3000）で、.design-system/surfaces.tsv に各画面を surface<TAB>route<TAB>states の行として記録し、アプリが送信するすべての書き込みをネットワークログからコピーして .design-system/writes.txt に METHOD URL の形式で記録します。その後、node <this skill>/scripts/capture.mjs --base http://localhost:3000 --kind before --out .design-system/captures --surfaces .design-system/surfaces.tsv --writes .design-system/writes.txt を実行します。--writes（書き込みを送信しないアプリでは --no-backend）なしでは開始を拒否し、ブラウザーを開く前にすべての書き込みがブロックされたことを検証し、各キャプチャのアクセシビリティツリーを保存します。キャプチャし損ねたものがあれば終了コード 1 で終了します。何にも使われていないものは、それぞれ個別のコミットで削除します。 各画面にベースラインがあるか、キャプチャされていない理由が記録されていれば完了です。

3. トークン。 生の値を役割ごとにクラスタリングし、用途に応じた名前を付け、各画面をその前景色と組み合わせます（references/tokens.md）。すべての生の値が役割、統合、または列挙された例外に対応するまで、token-mapping を実行します。許容範囲内の統合は判断として扱います。許容範囲を超える場合は、デフォルトが統合となるゲートをクラスタごとに1つ開きます。すべてのルートで、同一の値をすべて置き換えます。 token-mapping が例外リスト以外の不足をゼロと報告し、置き換えがあったすべての画面で pixdiff.mjs が許容値 0 において 0％を報告すれば完了です。

4. コンポーネント。 最もよく使われているファミリーから、最初から最後まで構築します（references/components.md）。テキストプリミティブと小さいテキスト用プリミティブは、Button とともに第1波でリリースします。それぞれを component-docs で文書化します。ファミリーを展開する前に本人に見せます。システムを使った画面ができた後に中核の不具合が見つかると、全体の修正が必要になるためです（無効なフィールドが赤く表示されたまま、Combobox が Input より 2 px 高い、パネルのアクションが折り返されない、ファイルのドロップが無反応のまま失敗する、など）。 すべての標準コンポーネントにレジストリの行とドキュメントがあり、無効、必須、エラー、長文の各状態がショーケースでキャプチャされ、本人に提示されていれば完了です。

5. チェック。 scripts/check-system.mjs と scripts/oklch.mjs をリポジトリの scripts/ にコピーし、--init を実行してから、--init-allowlist を一度実行します。ルールは、違反が検出されて初めて有効と見なされます。スキャン対象のフォルダーに違反を1つ仕込み、--files <plant> --no-allowlist を実行し、終了コード1となってルール名が表示されることを確認してから、仕込んだ違反を削除します。許可リストとラチェットは縮小するだけです。禁止事項を導入する変更には、同じ変更内で必ずそのチェックルールも含めます。コピーのルールには、要素単位で適用する例外も含めます。引用、用語、バージョン文字列など、原文のままにする必要があるテキストと、プロンプト、API の例、クリップボードの値など、機械や人が別の場所に貼り付けるペイロード文字列が対象です。これらを書き換えると、相手が受け取る内容が変わるためです。 クリーンクローンでチェックが終了コード0となり、--self-test が「all as expected」で終わり、この実行で追加されたすべてのルールについて、今回その仕込みで失敗することを確認できたら完了です。

6. パイロット。 パイロットのフローを、差分を1つずつ確認したコードモッドで移行します。ベースラインのコマンド、幅、テーマ、データを使って移行後のキャプチャを取得し、変更するのは --kind after のみとします。その後、2つのフォルダーを pixdiff.mjs で比較します。説明のつかない差分は不具合です。キーボードでフローを操作し、エラー状態と読み込み状態を強制的に発生させてから、移行後のキャプチャに対して ui-review を実行します。 キャプチャ内のすべての差分が、判断またはゲートに結び付けられたら完了です。キャプチャがないレンダリングの変更は checks-only として報告します。

7. 準備状況。 移行を展開する前に、以下の5つの監査をすべて満たすか、記録済みの例外を設定します。

8. 引き継ぎ。 件数を再計測します。システムがカバーする範囲を数値で報告し、まず未回答のデフォルト値を示してから、見つかったものの修正していないものを優先度順に報告します。そのうえで、規模を添えて移行を提案します。移行は開始しないでください。 報告内のすべての数値について、それを算出したコマンドが明記されていれば完了です。

準備状況の監査

画面がシステムを使い始めた後に見つかった不足は、一括修正が必要になります。事前に見つかれば、一覧の1行で済みます。ステップ5の終了時と、最初の展開前に、これらの監査を実施します。各結果を .design-system/readiness.md に判定語とともに記録してください。

1. スロットとプロパティの同等性。 呼び出し箇所がある各レガシープリミティブのすべてのプロパティについて、新しいプリミティブに対応するプロパティがあるか、不足項目として記録されていること。
2. 動作契約。 インタラクティブプリミティブごとに「何がいつ発火するか」の表を作成し、各行をテストにすること（references/components.md）。
3. トーンの同等性。 押下可能なプリミティブと行プリミティブのそれぞれを、ミュートを含むすべてのステータストーンと組み合わせて確認すること。空欄は不足項目として記録するか、非対応であることを明記すること。
4. 固定文字列。 ロール名またはテキストによる、すべてのレガシーテストクエリについて、新しいプリミティブにデフォルト名とラベルの上書き方法があること。
5. 最も難しい画面。 各ファミリーで最も難しい呼び出し箇所を1つずつ選び、ショーケースでレンダリングしてスクリーンショットを取得すること。

準備が整っていないファミリーは移行しません。そのファミリーの画面はレガシーのままにします。

禁止事項

• このセッション中に依頼された場合を除き、プッシュ、公開、デプロイをしないでください。
• 実行開始時のブランチにはコミットしないでください。まず実行用ブランチを作成してください。
• 作業ツリーが汚れた状態で、スタッシュしたりブランチを切り替えたりしないでください。作業ツリーが汚れている場合は、専用のワークツリーに実行用ブランチを作成します（git worktree add）。
• 別のパッケージまたは公開 API がエクスポートしているものを削除しないでください。処理を止め、インポート元とともにゲートとして列挙してください。
• 手順を黙って省略しないでください。アプリをビルドまたは実行できない場合、レポートに code-complete, not runtime-verified と記載し、未実施の内容を明記してください。
• 自分の作業を verified と呼ばないでください。他のエージェントを起動できないホストでは、手順を順番に実行し、差分とキャプチャを新たに確認して各項目を検証し、その判定を self-verified としてください。

ルール

• 生の値の臭いは、#fff、rgb(、text-gray-500、p-[13px]、style={{ padding: 12 }}です。それぞれ、セマンティックトークンまたは列挙された例外に対応します。
• プリミティブが欠けている場合はギャップ行とし、サーフェス内の回避策で補ってはいけません。
• delta E OK 2以内の色の統合と、2 px以内のスペーシングの統合は判断事項です。ボーダーの幅、ウェイト、イージングには許容差がありません。
• セマンティクスを追加するだけの変更（名前、ロール、aria-current）は判断事項です。セマンティクスを削除または再構成する変更はゲートです。
• 誤り：{saving ? "Saving..." : "Save"}。正しい対応：アイドル時のラベルはそのままにし、同じボックス内にスピナーを配置して、aria-busyを設定します。
• 修正が2回再発したら、別の文を追加するのではなく、チェックルールまたはスクリプトにします。
• 差分チェックを通すためにベースラインを編集してはいけません。正しいコードを誤って検出するチェックは、修正を証明するケースを仕込んだうえでチェック側を修正します。コードを曲げてはいけません。
• スクリプトで生成されていない数値や、失敗するところを一度も確認していないチェックについては報告しません。

完了条件

クリーンなクローンでチェックが終了コード0を返し、すべてのルールについて失敗することを確認済みであり、本番ビルドで全ルートが200を返し（capture.mjs --status）、パイロットが一覧にある意図的な変更を除いてベースラインと一致し、すべての引き継ぎ件数がスクリプトから取得されていれば完了です。

references/traps.mdには、ID別の動作上の落とし穴が記載されています。references/tokens.mdには、レイヤー、名前、許容差、モーションプリセットが記載されています。