AIが使いこなせるデザインシステムを作り、AIの作った部品を確かめる

## 何かを変える前に、部品と説明書を受け持つパッケージを調べる デザインシステムを、見た目の断片を集めたものではなく、共有される製品契約として扱う。何かを変更する前に、コンポーネント、文書、例、プレビュー画面、テスト基盤、移行ユーティリティをどのパッケージが管理しているか特定する。 利用可能なAPIと規約については、リポジトリの現在のブランチを正本とする。一般的なWebプラットフォームの知識、別のブランチ、新しいライブラリのリリースを根拠に、対応状況を推測してはならない。タスクがツールチェーンを明示的に変更する場合を除き、設定済みのパッケージマネージャー、ランタイム、モジュール形式、テストランナーを維持する。 ## 始める前に、今のブランチ（作業中の版）の説明書と部品の一覧を読む コンポーネントの作業前に、次を行う。 1. 対象に適用されるリポジトリとパッケージの指示を読む。 2. ローカルのコマンドラインヘルプを確認し、利用可能な文書トピックを一覧にする。 3. デザイン原則、デザイントークン、テーマ規則、コンポーネント一覧を読み込む。 4. 単一の基本要素ではなくレイアウトを扱うタスクでは、ページテンプレートを確認する。 5. 対象コンポーネントの現行API、バリエーション、構造、例、制約を読む。 生成文書と対応APIはブランチごとに異なる可能性があるため、この初期確認をすべてのブランチで繰り返す。デザインシステムの依存関係を更新した後は、無関係な手作業の編集より先に、リポジトリの移行ユーティリティを実行する。 ## ファイルの頭の説明と部品の説明書を、いっしょに直す 互いを補う二層の文書を維持する。各ソースファイルのヘッダーには、入力、出力、アーキテクチャ上の位置を示す簡潔なメタデータを置く。詳しいプロパティ、機能、例、アクセシビリティ上の注意、組み合わせ方の指針は、コンポーネントが管理する文書ファイルに置く。 実装を変更した時は両方の層を更新し、連動するファイルを示す同期マーカーに従う。表示処理が実際に対応する文書形式を使う。たとえば、現在の自動文書化パーサーが言語指定付きの例示フェンスを正しく扱えない場合は、言語指定のないフェンスを使う。正しいソース構文なら文書も正しく表示されると決めつけず、表示結果を確認する。 ## スタイルのツールが本当に使えるCSSの機能を、表に残す スタイリングエンジンのバージョンと、アットルール、疑似クラス、疑似要素、複合セレクター、値、アニメーション、変数、テーマ、動的な値、条件付きセレクターへの検証済み対応状況を記録する。対応済みの構文と、コンパイルできても無効または使用不能なCSSを生成する構文を区別する。 機能表で対応を確認できた場合は、CSSネイティブの解決策を優先する。代表的な候補には、メディアクエリ、機能クエリ、コンテナクエリ、初期スタイル、スコープ、操作状態と構造を表す疑似クラス、生成コンテンツ用の疑似要素、現代的な色と寸法の関数、トランジション、キーフレームが含まれる。古い機能表にその機能がなかったという理由だけで、JavaScriptによる回避策を作ってはならない。 ## マウスを重ねた時や選んだ時の見た目を、その部品の中だけで効かせる 祖先、子孫、兄弟の状態は、スタイリングエンジンが対応する条件付きセレクターの仕組みで表す。その仕組みでマーカーが必要な場合は、実際の祖先要素へマーカーを適用し、マーカーの定義を管理元コンポーネントの近くに置く。 フォームコントロールや入れ子の操作要素には、コンポーネント固有のマーカーを使う。外側のポップオーバー、パネル、コンテナからホバー状態やフォーカス状態がコントロールへ漏れる可能性がある時は、全体共通の既定マーカーを絶対に使わない。祖先条件では疑似セレクターだけを許可する、といったセレクター契約を守り、未対応のCSSネストを模倣しない。 タッチ端末へ解除されない操作状態が引き継がれないよう、ホバー専用の効果をホバー対応メディアクエリで保護する。キーボードフォーカスと無効状態の挙動は、ホバーとは独立して維持する。 ## 並べ方と動きは、JavaScriptでなくCSSで作る 対応している場合は、グリッド、間隔付きフレックスボックス、アスペクト比、オーバーフロー制御、スクロールバーのプロパティを直接使う。コンポーネントに応じたレスポンシブ動作には、オブザーバーで要素を計測する代わりにコンテナクエリを優先する。縞模様には、インデックスに基づくJavaScriptではなく構造疑似クラスを使う。 開始時のトランジションは、状態管理とアニメーションフレームの組み合わせではなく、初期スタイルへの対応を使って実装する。順序付きのCSSフォールバックは、手動のランタイム検出ではなく、スタイリングエンジンのフォールバック用抽象化で表す。特殊な配置機能は、生成されるCSSを対応ブラウザー群で確認した場合にのみ使う。 ## リンクとテーマを差し替えられるようにし、部品を写さずに使えるようにする ランタイム依存の値は、インラインスタイルではなく、型付きのスタイル関数を通す。条件付きスタイルは、その場しのぎでクラス名を切り替えるのではなく、システムのスタイルプロパティの仕組みで組み合わせる。テーマ変数とテーマ作成はコンパイラーが要求するファイル形式に置き、検証の向上に役立つ場合は型付き変数またはコンパイル時定数を使う。 ナビゲーションは、アンカー要素を直接埋め込まず、差し替え可能なリンク抽象化を通して表示する。これにより、利用側はコンポーネントを分岐させずに独自のルーターを提供できる。パッケージ化されたコンポーネントの移植性を保つため、リポジトリのアセット、フォント、公開パス、テーマプロバイダーの契約に従う。 ## AIが部品を正しく作れるかを、長い会話の後も含めて試す エージェント向け指針が、モデルによる正しいコンポーネントコードの生成に役立つか測定する。全プロンプトの一式、または迅速なフィードバック向けに層化抽出した標本のどちらかを実行する。プロンプトごとに分離されたワーカーを使い、タスクを読ませ、文書化されたシステムを使ってコンポーネントを生成させ、抜け道を自己判定させ、コードと評価メタデータの両方を保存する。 埋め草、注意をそらす発話、回復用の発話を含む10ターンの会話を通じて文脈保持を調べる劣化モードを追加する。0、6、8、10ターン目などの代表点を測定し、最終ターンだけを報告するのではなく、プロンプトごとの推移を比較する。 テストプロンプト、生成結果、スクリーンショットを、安定した反復識別子に関連付ける。独立したプロンプトは並列化してよいが、変更可能な結果ファイルを複数のワーカーで共有してはならない。 ## 試した結果を残し、AIがデザインシステムを使わずにすませた所を見つける 各事例を再現して比較するために十分な構造化メタデータを保存する。これには、反復識別子とプロンプト識別子、日時、モデル、想定利用者像、プロンプト分類、経路の深さ、プロンプト、生成された応答、成功判定、使用したコンポーネント、検出した抜け道を含める。 集約前にプレビューページを構築し、スクリーンショットを取得する。機能面の成功だけでなく、生の要素、インラインスタイル、直接埋め込まれたナビゲーション、未対応のセレクター、重複する基本要素、対応済みCSSに対するJavaScriptの回避策によって、生成物がデザインシステムを迂回していないか評価する。 モデルの自己評価は、証拠ではなく一つの判断材料として扱う。機械検査、プレビューの証拠、抜き取りによる人のレビューを組み合わせる。繰り返し発生する失敗パターンを特定した後にのみ、集約結果を文書やAPIの改善へ使う。 ## 変えた後に小さな確認を行い、通った物を報告する コンポーネントを変更する前に現行文書を確認し、設定、組み合わせ、新しいバリエーション、深いカスタマイズのための明示的なソース取り出しのうち、どれが要求に最も適しているか判断する。既存の拡張点がある場合は公開契約を維持し、並行する別の基本要素を作らない。 変更後は、同期対象の文書を更新し、直接関係する最小範囲の単体テスト、型検査、リント検査、スタイリング機能スキャン、コンポーネントプレビューを実行する。共有契約をまたぐ変更の場合にのみ、確認範囲を一式へ広げる。中核パッケージのバージョンが変わった場合は、文書化された移行手順を実行して差分を確認する。 変更した挙動、更新した文書、合格した検査、見つかった未対応機能、実行できなかった検証を報告する。