improve-ui

UI を改善する

実際に適用されているシステムに照らして、一貫性のある製品サーフェスを1つ監査します。製品の個性を保ち、既存の担当者を活用し、根拠のない指摘はせず、指摘がなければその旨を記録します。計画を作成するのは、ユーザーが選択した変更に限ります。別のエージェントが実行します。

範囲

• 製品のソースは変更しないでください。ファイルの作成・編集は design-plans/ 内に限ります。
• 依存関係のインストール、フォーマッターの実行、コミット、プッシュ、その他の作業ツリーの変更は行わないでください。
• デザインドキュメントは更新しないでください。ドキュメントの変更が承認された場合は、実行担当者向けの計画に記録します。
• ユーザーが提示した場合、または目視による確認を明示的に依頼した場合に限り、レンダリング結果を証拠として使用してください。
• 各計画は、それだけで完結するものにしてください。実行担当者は、監査や会話のコンテキストを持っていません。

1. サーフェスを選択する

ユーザーの指定範囲に従ってください。依頼の範囲が広い場合は、主要な製品タスクを代表する、一貫したサーフェスファミリーを1つ選び、デプロイ可能なアプリケーションを1つ対象にします。選択した対象を明記してください。リポジトリ全体を1つの製品としてまとめないでください。

サーフェスのルートとレイアウトから調査を始めてください。構成要素、共有コンポーネント、バリアント、解決済みトークン、スタイルをたどり、レンダリングに至る経路を確認します。リポジトリ全体を検索して不整合を探すことから始めてはいけません。

接続があると判断できるのは、レンダリング、インポート、プロップ、解決済みの設定、CSS の継承、またはサーフェスによって読み込まれる生成済みアーティファクトによって立証される場合に限ります。名前の共有、トークンの類似、リポジトリ内での近接、概念上の関連だけでは接続の根拠になりません。たどった経路に関与しない他のアプリケーション、プレビュー、コンフィギュレーター、生成済みレジストリ、レガシーシステム、エンタープライズ版は除外してください。

2. ローカルシステムを再構築する

DESIGN.md、リポジトリのガイダンス、サーフェス固有のデザインドキュメントを確認してください。情報源を利用するのは、それが最新であり、選択したサーフェスに適用されると確認できた場合に限ります。明示的に承認され、最新である場合を除き、ドラフト、提案、移行資料、タスクリストは将来の意図を示すものとして扱ってください。デザインドキュメントが存在しないことは指摘事項ではありません。

たどった経路に関連するトークン、変数、テーマ、プリミティブ、バリアント、構成のみを調べてください。エイリアスとバリアントは、それぞれの定義まで解決してください。リポジトリに記載されている場合に限り、実装をローカルまたはレガシーに分類してください。

以下を記録してください。

## Design language
- Audited surface:
- Design sources:
- Documented decisions:
- Governing owners and consumers:
- Explicit exceptions:

引用した情報源が例外を明示していない限り、Explicit exceptions の下には None documented と記載してください。

3. 調査結果を立証する

立証ゲートを適用する前に、トレースした各サーフェスのユーザー向けラベル、アクティブ状態の表示、レスポンシブ時の分岐、兄弟バリエーションを調べ、内部に矛盾がないか確認します。その結果は候補としてのみ扱います。

修正によって主に変わるのが、視覚的な表示、インターフェースのコピー、レイアウト、コンポーネントのスタイル、または文書化されたデザインルールへの準拠である場合に限り、その指摘は対象範囲内です。修正によって主にプロダクトの動作の可否が変わる場合は、却下します。

検索結果、繰り返し、実装の違いから得られるのは候補であり、指摘ではありません。次の3つすべての立証が揃った場合にのみ、候補を残します。

1. 契約 — このプロパティと対象範囲を拘束するデザイン上の決定、または同一タスク内のユーザー向け表示やコンテンツにおける直接的な矛盾を引用します。「推奨」、「一般に」、名称、省略、繰り返し、例外がないことは、契約の根拠になりません。
2. 実行時 — 引用した所有者、値、または動作が、トレースした実行時経路を通じて対象サーフェスに届くことを立証します。別々の所有権レイヤーやライフサイクル状態を比較してはいけません。
3. 修正 — 根拠から必要となる変更を1つ提示します。既存のトークン、バリエーション、プリミティブ、または手本に依存する場合は、その名称を正確に記載します。根拠から正しい選択を判断できない場合、意図された条件が曖昧な場合、提案に複数の選択肢が含まれる場合、または修正にプロダクトの意図を創作する必要がある場合は、候補を却下します。

ソースから立証できるのは、トークン、タイポグラフィ、色、間隔、レイアウト、コピー、コンポーネントのバリエーション、レスポンシブ表示、および明示的なデザイン契約に関する違反です。機能的な動作、状態管理、インタラクションの正しさをデザイン上の指摘に変えることはできません。階層、目立ちやすさ、密度、明瞭さ、見つけやすさ、使いやすさ、知覚される一貫性の判断には、レンダリング結果またはユーザーの根拠が必要です。

ユーザーが明示的に求めていない限り、アクセシビリティおよび HTML/ARIA のセマンティクスに関する指摘は破棄します。ユーザーが求めている場合、またはプロダクト固有のデザイン契約が適用される場合を除き、壊れたルート、リダイレクト、データ接続、アクションの失敗、メタデータ、パッケージ API、パフォーマンス、アーキテクチャ、コード品質に関する指摘は破棄します。

すべての立証に合格してから、信頼度を割り当てます。根拠が裏付けている場合は既存の所有者を再利用し、繰り返しだけを理由に共有プリミティブを作成してはいけません。

4. 指摘を精査する

報告する前に、引用したソースをすべて開き直し、各候補が誤りである可能性を検討します。次のいずれかに該当する場合は削除します。

• 問題が引用した実装と正確に一致しない。
• ルールがそのプロパティとサーフェスに適用されない。
• 反証により、その違いが正当または意図的であると示される。
• 根拠から複数の修正案が導かれる。
• 修正がプロダクトの意図を創作する。
• 別の指摘が同じ根本問題を説明している。

この精査を通過した指摘のみを表に記載できます。

5. 報告する

残った指摘を、信頼度、ユーザーへの影響、適用範囲、修正コストの順に並べます。最大3件までとします。

次の構成を使用します。

## Design language
- Audited surface:
- Design sources:
- Documented decisions:
- Governing owners and consumers:
- Explicit exceptions:

## Findings
| # | Problem | Evidence | Proposed change | Scope | Confidence |
| --- | --- | --- | --- | --- | --- |

## Improve first
<Highest-leverage finding and why, or no supported recommendation.>

根拠によって、契約、実行時の関係、確定的なインターフェース上の結果を立証する必要があります。提案する変更には、修正を1つだけ記載します。未裏付け、または重複する行は、返答前に削除します。

Confidence を含む必須列がすべて揃っていない指摘は削除します。

Improve first では、根拠が最も強く、効果が最も大きい、残った指摘を1つ選びます。複数の指摘を組み合わせてはいけません。

候補が1つも残らなかった場合は、## Findings の下に No supported findings were found.、## Improve first の下に No supported recommendation. と記載します。

指摘が残った場合は、どれを計画にするかを尋ねて終了します。ユーザーがすでに指摘を選択している場合、または説明された改善について計画を明示的に求めている場合は、その対象範囲で続行します。直接修正または改善を求められた場合は、計画を提示します。実装は決して行いません。

6. 選択した変更を明確にする

references/plan-template.mdを読みます。選択した変更ごとに計画を1つ作成し、症状ごとに計画を作成しないでください。

作成する前に、引用したすべてのソースを再度開き、可能な場合は現在のコミットを記録し、再利用可能なプリミティブと参考例を特定して、影響を受ける領域を追跡します。既存の計画がある場合は、重複させずに整合させます。

リポジトリにトークンやコンポーネントの仕様がある場合は、値をでっち上げないでください。既存のシステムではその判断を表現できない理由と、どの利用者がそのプリミティブを共有すべきかを証明してから、プリミティブを導入します。

整合を求められた場合は、既存の計画を現在のソースおよび文書化された決定と照らし合わせて再確認し、古くなった根拠、影響を受ける領域、ステータスを更新します。