テーマ対応のUIコンポーネントライブラリで、コンポーネントを作る・直す

## コンポーネントの変更が及ぶファイルを洗い出す 再利用可能で、テーマを適用でき、アクセシブルなコンポーネントライブラリへ慎重に貢献する担当者として行動します。編集前に、要求された動作、影響を受けるコンポーネントまたはユーティリティ、直接関係するすべての領域を特定します。 実際のリポジトリ構造に従いますが、コンポーネントの変更は次の領域の一部にまたがる可能性があります。 - 実行時コンポーネントとコンポーザブル。 - 公開される型とエクスポート。 - テーマレシピ、バリアント、既定値。 - 単体テスト、レンダリングテスト、スナップショットテスト、アクセシビリティテスト。 - ユーザー向けドキュメントと例。 - ローカルのプレイグラウンドまたはデモページ。 すべての領域を変更する必要があると決めつけないでください。既存のコンポーネントと最も近い類似実装をたどり、依頼に必要な領域だけを列挙します。ソースとテストの規約は該当ディレクトリに限定して適用し、ドキュメント、例、ツールへ無差別に適用しないでください。 タスクで明示的に変更されていない既存の公開動作は維持します。属性の転送、既定値の解決、アクセシビリティ上の意味、右から左へ記述する場合の動作、文書化されたAPIは、実装の詳細ではなく契約として扱います。 ## 必要なガイドだけを読み、ジェネレーターで作り始める 最初にリポジトリ全体の貢献ガイドを読み、その後はタスクに関係する参照資料だけを読み込みます。たとえば、props、slots、events、テンプレートのパターンにはコンポーネント構造のガイド、スロットとバリアントにはテーマのガイド、レンダリング、スナップショット、アクセシビリティにはテストのガイド、例とマークアップにはドキュメントのガイドを使います。 存在するという理由だけですべての参照資料を読み込まないでください。影響を受けるファイルから始め、最近の比較可能な実装を調べ、変更が該当領域に及ぶ場合だけ追加のガイドを開きます。 プロジェクトで宣言されたパッケージスクリプトとサポート対象のパッケージマネージャーを使います。依存関係のインストール後、プレイグラウンド、ドキュメントサイト、各種チェックを開始する前に、必須の準備処理または型生成処理を実行します。変更に適したローカル環境として、メインアプリケーションのプレイグラウンド、別フレームワーク用のプレイグラウンド、問題再現に絞った環境、ドキュメントサイトのいずれかを使います。 コンポーネントを作成する時は、リポジトリで承認されたジェネレーターを優先します。生成されたファイルを編集前に確認し、タスクに必要なテンプレートだけを要求します。適用できるジェネレーターがなければ、確立済みのファイル配置と命名規則を手作業で再現します。 ## テーマの既定値の優先順位と、右から左の表示を守る ライブラリで確立されたコード規約を一貫して守ります。 - ツールチェーンまたはスタイルガイドで必要とされる場合、型だけのインポートを分離します。 - 実行時のpropsの既定値は標準ヘルパーで定義し、公開される既定値は型側のAPIに記載します。 - レンダリングされる要素に安定したスロットマーカーを追加します。ルート要素では呼び出し側が指定したマーカーがコンポーネントのフォールバックより優先され、内側の要素ではそれぞれ固有のマーカーが維持されなければなりません。 - 属性の自動フォールスルーを無効にしている場合は、呼び出し側の属性が暗黙に上書きされないよう、ルートのバインディング順序または解決方法を整えます。 - テーマの状態を一度だけ評価するのではなく、標準の算出機構を通じてリアクティブなテーマ出力を構築します。 - プロジェクトで定義された完全な優先順位に従って既定値を解決します。明示的なコンポーネント入力、最も近いグループまたはフィールドのコンテキスト、ライブラリレベルのテーマ上書き、コンポーネントの既定値、アプリケーション構成の順です。 - プロキシ化によって注入の優先順位が変わる場合は、コンテキストヘルパーへ未加工の入力を渡します。より近いコンテキストがない時は、テーマレベルの既定値を失わせず、解決済みのコンポーネント値へフォールバックします。 - 解決済みの既定値を維持できるよう、プリミティブライブラリのpropsとeventsをプロジェクトのプロキシ対応アダプター経由で転送します。 未加工のパレット値ではなく、意味に基づくデザイントークンを使います。左から右、右から左のどちらのコンテキストでもレイアウトが機能するよう、論理的な余白、位置、境界線、角丸、テキスト配置のプロパティを使います。論理プロパティで表現できない変形、カーソル、グラデーション、トランジションには、記述方向を明示した代替を追加します。 実装を既存のパターンに合わせます。コンポーネント一つのために、競合する既定値システム、props転送経路、テーマ解決レイヤーを導入しないでください。 ## チェックリストで、テーマからテストとドキュメントまで作る 新しいコンポーネントまたは大規模なコンポーネント機能を、次のチェックリストで追跡します。 1. 標準の実行時配置にコンポーネントのひな型を生成するか、新規作成します。 2. 動作、公開props、slots、events、アクセシビリティ上の意味を実装します。 3. slots、variants、複合variants、意味に基づくトークンを含むテーマレシピを追加または更新します。 4. 公開する型をエクスポートし、テーマシステムに必要なコンポーネント既定値インターフェースを登録します。 5. 必要に応じて、動作、props、slots、属性転送、記述方向、アクセシビリティに焦点を当てたテストを追加します。 6. 使用方法、例、APIの詳細を含むユーザー向けドキュメントを更新します。 7. 変更された動作を示すプレイグラウンドの例を追加または更新します。 8. リンティング、静的型チェック、関連するテスト一式を実行します。 プロジェクトがスナップショットを有用な契約として扱っている場合にだけ使用し、生成された変更を自動的に受け入れず確認します。テストは、外部から意味のある動作と既知の優先順位規則に集中させます。 パッケージのリリースより先にドキュメントがデプロイされる場合は、影響を受ける見出しや例にプロジェクトで承認されたプレリリースマーカーを維持します。このマーカーは、マージ済みドキュメントに次のリリースで提供される機能が記載される可能性を意図的に伝えるものです。リリース方針を確認せずにマーカーを外したり、不整合として報告したりしないでください。 ## リントとテストを実際に回し、結果を添えてプルリクエストを出す 最終diffを、最も近い確立済みのパターンおよび元の依頼と照合してレビューします。次を確認します。 - コンポーネントの構造、公開する型、エクスポートに一貫性がある。 - テーマコードが意味に基づくトークンを使い、既定値の完全な優先順位を維持している。 - ルート属性とスロットマーカーが呼び出し側の上書きを尊重している。 - 論理プロパティまたは記述方向を明示したバリアントが、右から左に記述する場合の動作を網羅している。 - テストが変更されたprops、slots、動作、アクセシビリティ要件を網羅している。 - ドキュメントに必要な使用方法、例、API変更が含まれている。 - 意図的なプレリリース用ドキュメントマーカーが維持されている。 リポジトリのリンティング、型チェック、関連テストの各コマンドを実行し、実際の結果を報告します。目視確認だけでチェックが通ったと主張しないでください。公開動作が変わった場合はドキュメントを更新します。 リポジトリで必須のコミットメッセージ規約とプルリクエストテンプレートを使います。関連する作業項目をリンクし、変更の種類を示し、動作と検証内容を説明し、証拠で裏づけられるチェックリスト項目だけを完了済みにします。 見た目を整えることだけを理由に、貢献者のコミット履歴を書き換えたり、リベースしたり、強制プッシュしたり、まとめたりしないでください。リポジトリがスカッシュマージを行う場合は、複数の開発コミットが許容されることがあります。実際のマージ方針とユーザーの許可に従ってください。