画面の部品集（UIコンポーネントライブラリ）を、デザインの決まりどおりに作って直す

## 作業の種類ごとに先に読む資料を決め、食い違いはコードに合わせる 編集前にタスクを分類し、その作業を規定する正本を読む。 - コンポーネントの挙動やAPIについては、公開APIガイド、実装、近接する承認済みコンポーネントを読む。 - スタイルについては、詳細なスタイル仕様、コンパイル時トークンファイル、実行時テーマファイル、隣接するスコープ付きスタイルを読む。 - ビルド変更については、パイプラインを変える前にビルド設定とすべてのカスタムプラグイン契約を読む。 - テストについては専用テスト設定と近接するテストを読み、文書については同期マトリクスを読む。 - 矛盾は、ソースと有効な設定、リポジトリ規則、専門文書、一般的な経験の順に解消する。 - ソースと文書が異なる場合はソースに従い、同じ承認済み範囲内で古くなった文書も修正する。 - クイックリファレンス表は、規則を独立して複製したものではなく、正本となる節への案内として扱う。 - APIを創作したり、バージョンに左右される挙動を記憶だけに頼ったりしてはならない。インストール済みバージョンと同梱文書を確認する。 実装前に、影響を受けるエクスポート、スタイル、テスト、デモレジストリ、文書、ビルド不変条件を列挙する。 ## 部品ごとに、コード・見た目・テストを1つのフォルダにまとめる 各コンポーネントには専用フォルダを1つ設け、実装、スコープ付きスタイルファイル、エクスポート用エントリ、同じ場所に置く単体テストを格納する。公開する値と型は分けてエクスポートし、必要なデモ画面も登録する。 - 型付き関数コンポーネントを使い、引数の分割代入でデフォルト値を定義し、安定した表示名を設定する。 - 適切なネイティブ要素の属性を拡張し、競合するフィールドだけを除外する。 - コンポーネント名と型名はリポジトリ標準の大文字・小文字表記に、スタイルファイルは設定済みのファイル名形式に、スコープ付きクラス名は設定済みのクラス規則に従わせる。 - 厳格なnull検査と分離モジュール規則を維持する。型を無視する逃げ道を避け、型専用エクスポートを明示する。 - importはファイル冒頭にまとめ、設定済みのプロジェクトエイリアスを使い、コンポーネントのスコープ付きスタイル内にグローバルセレクタを置かない。 - 生成されたクラス名を直書きせず、スコープ付きスタイルマップまたは承認済みクラス補助関数を通じてクラスを合成する。 - 再利用可能な補助関数は目的を絞り、リポジトリ規則が定める場所に置く。 コンポーネントの公開インターフェースを変える場合は、エクスポート、テスト、例、API文書もまとめて更新しなければならない。 ## 色や角の丸みは、生の数字でなく共通の決まった値で書く 役割ごとにトークン層を分けて維持する。コンパイル時変数は計算とミックスインを支え、実行時CSSカスタムプロパティは利用側によるテーマ上書きを可能にする。この2層を同じものとして扱ってはならない。 - CSS Modulesの命名とトークン注入を、ビルド設定とテスト設定の間で一致させる。 - コンポーネントスタイルでは実行時のセマンティックトークンを優先し、前処理が必要な場合だけコンパイル時変数を使う。 - 色、フォーカス、角丸、立体感、タイポグラフィ、ウェイト、モーションは、孤立した生の値ではなく、システムの意味的な役割で表現する。 - デザイン言語で色味のある面、温かみのある文字色、ブランド固有のフォーカス状態が定義されている場合は、純粋な極値や一般的で冷たい初期値を避ける。 - 意図的なコンポーネントの輪郭、状態表現、影の規則を、単一の汎用パターンへ平板化せず維持する。 - グローバルフォント、テーマ変数、リセットは、1つのグローバルスタイルエントリの内側にまとめる。 - モーション低減設定を尊重し、視認できるフォーカス、キーボード操作、読み取れるコントラスト、文書化されたアクセシビリティロールを維持する。 正確な値とコンポーネント固有の例外は、記憶ではなく、正本となるデザイン仕様と現在のソースから取得する。 ## 部品ごとに、キーボード操作と使いやすさ（アクセシビリティ）をテストする 宣言済みのDOM環境、セットアップファイル、マッチャー、エイリアス、CSS Modules処理を備えた、リポジトリ専用のテスト設定を使う。有効なテストランナーが無視するビルド設定へテスト設定を移してはならない。 - コンポーネントテストは実装と同じ場所に置き、承認済みのレンダリング、クエリ、ユーザー操作ユーティリティを使う。 - レンダリング、propsに応じたクラス、コールバック、無効状態の挙動、状態変化、関係するアクセシビリティロールを網羅する。 - フォーカス移動、起動、終了、方向操作を含め、そのコンポーネントパターンで必要なキーを使ってキーボード挙動を確認する。 - 生成された文字列リテラルではなく、importしたスタイルマップを通じてスコープ付きクラスを検証する。 - 命令型APIはテストフレームワークの状態境界内で呼び出し、マウント結果を待ってテストする。コンポーネントではないAPIをJSXとしてレンダリングしてはならない。 - 共有テストユーティリティは一元化し、低水準のイベント用ショートカットではなく、現実的なユーザー操作を使う。 - 設定済みのカバレッジ基準を満たし、価値の低いテストで数値を水増しせず、意図的な除外は文書化する。 不具合には、まず対象を絞った失敗するテストを実行し、次に影響範囲のテスト一式を、最後に完了前に必要な全テスト一式を実行する。 ## 使う部品だけが読み込まれるように、部品ごとに分けて組み立てる カスタムビルドプラグイン、パッケージエクスポート、アセット規則は、利用側との契約として扱う。 - 未使用コンポーネントをtree shakingできるようモジュール境界を保ち、ES-moduleとCommonJSの成果物を分けて維持する。 - フレームワークと承認済み補助パッケージがpeer dependencyである場合はexternalに保つ。明示的な要件なしにruntime dependencyを追加してはならない。 - CSSコード分割と、各コンポーネントのスタイルをそのJavaScriptエントリへ関連付ける仕組みを維持する。 - グローバルスタイルシートのエントリを完全に保つ一方で、未使用コンポーネントのアセットが利用側のbundleへ入らないようにする。 - フォント形式とpublic pathの要件を含め、リポジトリのアセットコピーおよびインライン化方針に従う。 - パッケージのexport map、配布対象ファイル、side effect宣言を、生成される構造と一致させる。 - カスタムプラグイン契約を読んでからビルド処理を変更し、その後でコンポーネント単位のimportとグローバルスタイルエントリの両方を確認する。 生成された配布用、デモビルド用、カバレッジ用のディレクトリは編集対象ではない。リポジトリ方針が明示的に求めない限り、コミットしてはならない。 ## 部品を変えたら、説明書と見本ページも一緒に直す コンポーネント変更の影響を受ける正本をすべて更新する。 - APIやpropの変更時はソースに基づいてAPIマニュアルを更新し、スタイル変更時は詳細なスタイル仕様を更新する。 - 視覚言語の変更時はデザイン概要を更新し、新しいコンポーネントの追加時はユーザー向けプロンプトまたはカタログ仕様を更新する。 - コンポーネント数やカバレッジの変更時は、承認済みジェネレーターを通じて、同じ情報を掲載するすべてのreadmeを更新する。 - デモ登録がルートメタデータ、レンダラーマップ、ホームページカタログに分かれている場合は、独立した各レジストリをすべて更新する。 - 機械可読な件数は手作業で重複記載せず、正本のメタデータから導出する。 - 文書同期チェッカーを実行し、そのチェッカーが検査しないデモ画面や生成面も把握する。 - 追跡対象の生成物は直接編集せず、承認済みコマンドで再生成する。 登録変更後は、デモルートを選ぶと意図したページが表示されることを確認する。メニューが選択状態なのにメイン領域が空なら、通常はレジストリ登録が欠けている。 ## 一括の置き換えや、真っ白な見本ページなどのよくある失敗を防ぐ 多数のファイルを気付かないまま破損させる可能性がある変更には、範囲を絞った検証可能な操作を使う。 - スクリプトによる置換では、すべての対象を直後に確認し、文字列操作が不変であることを考慮し、引用符付きマークアップをまたぐと失敗するパターンを避ける。 - テストツールが構造化結果を書き出す場合は、既定ファイルがあると決めつけず、必要な保存先を指定する。 - DOMから画像を生成する処理では、レンダリングエンジンが文書のフォントレジストリを参照できない場合、必要なフォント宣言をキャプチャルートへ埋め込む。 - 表面的なtree shaking指標を改善するだけの目的で、意図されたコンポーネント内部依存をリファクタリングしてはならない。 - オンデマンドimportを保ち、未使用の大容量アセット、フォント、コンポーネントが利用側のbundleへ入るのを防いで、パッケージサイズを最適化する。 - デモページが空白になる場合は、コンポーネント実装を変える前に、独立したすべてのページレジストリを確認する。 安定した配置先がリポジトリにある場合、繰り返し発生すると確認された各失敗を、対象を絞った自動チェックへ変換する。 ## 変更を渡す前に、決まった検査（CI）を全部通す 文書化されたフォーマッターチェック、lint、単体テスト、ライブラリビルドを、リポジトリが要求する順序で実行する。コントリビューションを提案する前に、CIコマンド一式を実行する。 次を確認する。 - 変更したすべてのコンポーネント、エクスポート、テスト、文書、デモレジストリが同期されている。 - カバレッジまたはコンポーネント数のバッジは、その入力が変わった場合に再生成されている。 - 承認されていないruntime dependencyや生成物が変更へ入り込んでいない。 - モジュール形式の成果物、CSS分割、アセット読み込みの契約が維持されている。 - 視覚的な変更が、現在のトークン仕様とコンポーネント仕様に一致する。 - 最終差分に、意図したソースと文書の変更だけが含まれている。 必要なチェックが1つでも失敗した場合は、差分を提示する前に失敗を修正し、関係するゲートを再実行する。リポジトリのコントリビューション形式に従い、リリースまたは公開のワークフローはタスクに明示的に含まれる場合だけ実行する。実行したチェックを正確に報告し、範囲外として意図的に省いた広範なチェックも明示する。