saltjsx/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 がそれらを見つけるか、インストール方法を説明します。

手順

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) として記録し、先に進みます。 完了条件：不満、パイロット、ブランチ、承認されたテイストファイルが書き留められていること。

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で終了します。何も使用していないものを削除し、独自のコミットで行います。 完了条件：各サーフェスにベースライン、または not captured の理由が記載されていること。

3. トークン. 生の値を役割ごとにクラスタリングし、目的に応じて名前を付け、各サーフェスを前景色とペアにします（references/tokens.md）。すべての生の値が役割、マージ、またはリストされた例外にマッピングされるまで token-mapping を実行します。許容範囲内のマージは決定です。許容範囲を超える場合は、デフォルトがマージであるクラスターごとに1つのゲートを開きます。すべてのルートで、同一の値の交換を行います。 完了条件：token-mapping が例外リスト外のギャップをゼロと報告し、pixdiff.mjs が許容範囲0で、交換が影響を与えたすべてのサーフェスに対して0%を報告すること。

4. コンポーネント. 最初に最も使用されているファミリーをエンドツーエンドで構築します（references/components.md）。テキストプリミティブとスモールテキストプリミティブは、Button と一緒にウェーブ1で出荷します。それぞれを component-docs で文書化します。ファンアウトの前にファミリーをユーザーに表示します。なぜなら、スクリーンがシステムを消費した後に見つかったコアバグはスイープのコストがかかるからです（無効フィールドがまだ赤で描画される、Combobox が Input より2px 高い、パネルアクションが折り返されない、ファイルドロップが静かに失敗する）。 完了条件：すべての正規コンポーネントにレジストリ行とドキュメントがあり、無効、必須、エラー、および長いテキストの状態がショーケースでキャプチャされ、ユーザーに表示されていること。

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

6. パイロット. コドモッドを使用してパイロットフローを移行し、ハンクごとに読みます。編集後は、ベースラインと同じコマンド、幅、テーマ、データを使用して --kind after のみを変更してキャプチャし、次に pixdiff.mjs で2つのフォルダを比較します。説明できない違いは欠陥です。フローをキーボードで操作し、エラー状態とローディング状態を強制し、その後 ui-review を after キャプチャに対して実行します。 完了条件：キャプチャのすべての違いが決定またはゲートに遡れること。キャプチャのないレンダリング変更は checks-only として報告されること。

7. 準備完了. 移行がファンアウトする前に、以下の5つの監査が保持されているか、記録された例外が存在すること。

8. ハンドオフ. カウントを再実行します。システムがカバーする内容を数値で報告し、最初に未回答のデフォルト、次に見つかったが修正されなかったもの（順位付け）を報告します。移行をそのサイズとともに提案します。開始してはいけません。 完了条件：レポート内のすべての数値が、それを生成したコマンドを指定していること。

準備完了監査

スクリーンがシステムを消費した後に見つかったギャップはスイープのコストがかかります。前に見つかったギャップは行のコストです。これらをステップ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 }} です。それぞれはセマンティックトークンまたはリストされた例外にマッピングされます。
• プリミティブの欠落はギャップ行であり、サーフェス内の回避策ではありません。
• デルタE OK 2以内の色のマージと2px以内のスペーシングのマージは決定です。境界線の幅、ウェイト、イージングには許容範囲がありません。
• セマンティクス（名前、役割、aria-current）のみを追加する変更は決定です。セマンティクスを削除または再構築するものはゲートです。
• 間違い：{saving ? "Saving..." : "Save"}。正しい：アイドルラベルはそのまま、スピナーは同じボックス内に配置され、aria-busy が設定されます。
• 2回繰り返される修正は、別の文ではなく、チェックルールまたはスクリプトになります。
• ベースラインは、差分をパスさせるために編集されることは決してありません。正しいコードにフラグを立てるチェックは、チェック内で修正され、修正を証明する仕込まれたケースとともに行われます。コードを曲げることは決してありません。
• スクリプトによって生成されなかったカウント、または失敗しているのを見たことのないチェックは報告されません。

完了

クリーンなクローンでチェックが終了コード0で終了し、すべてのルールが失敗しているのを確認し、すべてのルートがプロダクションビルドで200を返し（capture.mjs --status）、パイロットがリストされた意図された変更を除いてベースラインと一致し、すべてのハンドオフカウントがスクリプトから取得されていること。

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