better-interface

インターフェースを一つのシステムとしてレビューする

優れたインターフェースは、独立した監査を積み重ねただけのものではありません。体験全体をレビューし、各 better-* スキルにそれぞれの領域のルールを適用させたうえで、根拠を一つの優先順位付きの評価にまとめます。

このスキルが担うのは、オーケストレーションのみです。アクセシビリティのルールは better-accessibility、構造は better-layout、コピーは better-writing、文字組みは better-typography、色は better-colors、ビジュアルの仕上げとモーションは better-ui が担当します。ここでそれらのルールを重複させたり、上書きしたりしてはいけません。未コミットの変更、ブランチ、プルリクエストを対象とした変更範囲のレビューは interface-review が担当し、範囲の特定と指摘事項の分類を行ってから、レビューをこちらに引き継ぎます。

基本原則

1. 最初に範囲とモードを特定する

呼び出しを [quick|full] [scope] として解析します。先頭のトークンが正確に quick または full の場合にのみモードとして扱い、それ以外はすべて範囲の一部とします。モードの既定値は full です。

依頼と現在のワークスペースから、対象となる画面、フロー、機能、またはリポジトリの範囲を推定します。出力には、特定した範囲を明記します。

モード	対象範囲	指摘事項の上限
quick	対象範囲の主要な経路と、実際に到達する状態。HIGH および MEDIUM の問題のみを報告	5
full	原則3に記載されたすべての領域スキルを通じた、依頼された範囲全体。存在する場合は、空、読み込み中、エラー、および狭い画面幅の状態も含む	15

依頼された範囲が広すぎて信頼できるレビューができない場合は、一つの完全なフローに範囲を絞ります。依頼の中心となるフローを選び、それがなければ対象範囲のすべてのユーザーが通るエントリーパスを選びます。境界と対象外の内容を明記してください。レビューしていない領域をレビューしたかのように示してはいけません。

依頼にブランチ、プルリクエスト、コミット範囲、または未コミットの変更が指定されている場合、それは画面レビューではなく変更レビューです。その旨を伝え、ユーザーに interface-review の実行を依頼してください。これはユーザーが呼び出すものであり、このスキルから開始することはできません。ここで変更範囲を特定してはいけません。差分の確認、指摘事項の分類、変更されたファイルから影響を受ける領域への範囲拡大は、すべて interface-review の担当です。これらを推測すると、範囲を検証できないレポートになってしまいます。

interface-review は反対方向にレビューを引き継ぎます。その際、特定した変更範囲、影響を受ける領域、各指摘事項のステータスが渡されます。重要度、統合、上限、出力形式、および評価は、以下の 変更範囲レビュー に従い、引き続きこちらが担当します。

2. 判断の前に調査する

フレームワーク、スタイリングシステム、コンポーネントライブラリ、デザイントークン、サポート対象のビューポート、利用可能なプレビューまたはテスト用コマンドを特定します。別のスタックの採用を求める指摘にならないよう、修正案はすべてプロジェクト独自の流儀に合わせて記述します。これは修正の形式を定めるものであり、現在のコードが十分かどうかを左右するものではありません。

次に、プロジェクトがインターフェースについて記述した内容を確認します。CONTRIBUTING.md、CODING_STANDARDS.md、AGENTS.md、CLAUDE.md、デザインシステムのドキュメント、Storybook のドキュメント、インターフェースに関する ADR などです。見つかったもの、または該当するものがなかったことを出力に記載します。

これらは判断材料として読み、許可を求めるものとして読んではいけません。規約が文書化されていても、それが優れた規約である証拠にはなりません。また、「スタイルガイドに書いてある」ことを理由に、指摘事項を取り下げてはいけません。変わるのは報告する場所です。ガイドラインや共有トークンが原因の場合は、その箇所に対して一度だけ報告し、関連コンポーネントをその報告の発生箇所として挙げます。

3. ドメインスキルを信頼できる情報源として使用する

レビューの前に、以下の担当スキルがすべて利用可能であることを確認してください。利用可能な担当スキルをすべて読み込み、適用してください。quick モードではすべてのドメインを確認し、主要フローに根拠があるドメインのみを深くレビューします。full モードでは、統合する前に利用可能な各ドメインのレビューを完了してください。

基礎的な問題が仕上げによって隠れないよう、次の順序でレビューします。

1. better-accessibility
2. better-layout
3. better-writing
4. better-typography
5. better-colors
6. better-ui

このスキルが最終回答を担当します。better-interface 経由でドメインスキルを読み込んだ場合は、その原則と参照資料を適用しますが、Reporting セクションと、そこで指定されている review-output.md は無視してください。代わりに、このファイルの統合形式、共通の重大度、指摘数の上限を使用してください。

担当スキルが利用できない場合、そのドメインを Not reviewed とし、欠けているスキル名を記載して、残りのドメインのレビューを続けてください。記憶を頼りにそのルールを再現したり、隣接するスキルで代用したり、全体を網羅したと主張したりしてはいけません。

複数のスキルが同じ問題を扱っているように見える場合は、根本にあるルールを担当するスキルに割り当て、二次的な影響は Why 欄に記載してください。同じ問題を複数回報告してはいけません。

4. 根拠を必須とする

すべての指摘に path/to/file:line を記載し、現在の実装を示してください。レビュー対象にソースファイルがない場合は、該当する画面とコンポーネントを正確に記載してください。見た目だけを根拠にコードレベルの指摘をしたり、実行時の挙動が結果を左右する場合にソースコードだけを根拠に見た目の指摘をしたりしてはいけません。

5. ユーザーへの影響度で順位付けする

共通の重大度スケールを使用してください。

• HIGH：タスクを妨げる、ユーザーを誤解させる、コンテンツやコントロールを隠す、データ損失のリスクを生じさせる、または繰り返し発生するシステム上の不具合を引き起こす。
• MEDIUM：理解しやすさ、効率、適応性、一貫性を大きく損なう。
• LOW：タスクへの影響が限定的な、単独の仕上げ上の問題。full モードでのみ含めてください。

同じ重大度内では、影響範囲と改善効果で順位付けしてください。トークンや共有コンポーネントの修正は、単一の末端コンポーネントにおける同じ症状より優先されます。

重大度を引き上げる条件。 担当スキルが以下のいずれかを確認した場合、表面上の問題が小さいからといって重大度を下げたり、quick モードだから報告を見送ったりせず、即座に HIGH としてください。

• アクセシブルな名前のないインタラクティブなコントロール。
• キーボードでフォーカスできるのに、フォーカスインジケーターが見えないコントロール。
• ポインターでは操作できるが、キーボードでは操作できないコントロールまたは操作経路。
• prefers-reduced-motion を無視するモーションまたは自動再生コンテンツ。
• 幅 320px またはズーム 200% で、切り取られる、重なる、またはアクセスできないコンテンツやコントロール。
• 必要な比率を満たさないコントラストの組み合わせで表示される本文またはコントロールのテキスト。
• 色だけで伝えられる状態や意味。
• 確認、取り消し、または明確な差別化のない破壊的操作。

これらの条件に該当する指摘は、他のすべての指摘より上位に配置してください。指摘数の上限を超える数の条件が該当する場合は、該当する指摘を先に列挙し、上限によって除外された指摘の数を記載してください。上限によって報告されない阻害要因が生じてはなりません。

これらは重大度を定めるものであり、新たなルールを追加するものではありません。症状の有無は引き続き担当スキルが判断し、このリストはその影響度を定めます。変更レビューでは、重大度引き上げ条件に該当すると確認された Regression は、既存の問題なら MEDIUM に相当する場合でも HIGH としてください。

6. システム全体に関わる指摘を統合する

根本原因が同じなら、指摘は 1 件にまとめてください。発生箇所ごとに行を分けず、確認された箇所をすべて同じ行に列挙してください。指摘数の上限まで報告を増やしてはいけません。レビュー結果が短くても、指摘がなくても問題ありません。

7. 慎重な判断を明示する

検討したものの、意図的に見送った候補を記録してください。担当スキルが現在の実装を許容している場合、根拠が不十分な場合、プロジェクトの慣例が単に定着しているだけでなく妥当な選択である場合、または提案する変更がユーザーの利益なしに複雑さを増やす場合、その候補は見送りとします。

8. 検証可能な項目を検証する

プロジェクトで利用できる、安全かつ関連性のあるチェックを実行します。実行時の動作や視覚的な判断が重要な場合は、レンダリングされたインターフェースを確認します。正確なコマンドまたは操作と、確認できた結果を報告します。チェックを実行できない場合は 未検証 と明記し、何が未確認なのかを示します。検証できていないことを指摘事項に置き換えてはいけません。

9. 原則として変更を加えずにレビューする

レビューの依頼は読み取り専用として扱います。ユーザーが指摘事項の実装も依頼していない限り、ソースコードを編集してはいけません。実装を依頼された場合は、集約した報告内容を変更範囲として維持し、実装後に関連する検証を再実行します。

よくある誤り

誤り	修正方法
ドメインごとに分かれた6つの報告	ランク付けした指摘事項テーブル1つに集約する
同じ問題を複数のスキルが報告する	根本のルールを担当するスキルに割り当てる
正確な場所が記載されていない指摘事項	path/to/file:line と現在の実装を示す
ソースだけを根拠にした視覚的な指摘	レンダリングされた状態を確認するか、未検証と明記する
影響の小さい改善を際限なく挙げる	モードごとの上限を守る。quick では LOW の指摘事項を省く
確認範囲に抜けがあっても明示しない	実際に確認したドメインと状態を示す
担当スキルの欠如を、確認済みとして扱う	ドメインを 未レビュー とし、利用できないスキルを明記する
却下した候補がない	必須の検討したが却下した項目のテーブルを含める
レビュー中に黙ってコードを編集する	実装を依頼されていない限り、読み取り専用を維持する
対応可能な指摘事項が残っているのに「承認」する	要修正 または ブロック とする
変更したファイルにある既存の問題をすべて報告する	既存の指摘事項は専用セクションに最大3件まで記載する
変更前から存在する問題を、変更レビューの妨げにする	既存の指摘事項は上限にも判定にも含めない
変更範囲で触れていないドメインを 問題なし とする	未レビュー：変更範囲に証拠なし と記載する

レビュー出力形式

以下のセクションを必ず使用します。

範囲とカバレッジ

モード、正確な対象範囲、スタックとスタイリング規約、調査で見つかったプロジェクト規約のドキュメント、レビューの境界を明記します。その後、カバレッジを示します。

ドメイン	確認した証拠	結果
アクセシビリティ	ファイル、コンポーネント、状態、またはチェック	指摘事項の数、または 問題なし

原則3に記載されているすべてのドメインを含めます。問題なし は対応可能な指摘事項がなく、確認済みであることを意味します。未レビュー とする場合は、その理由を説明します。

指摘事項

重要度、影響範囲、改善効果の順に並べたテーブルを1つ使用します。

#	重要度	ドメイン	場所	変更前	変更後	理由
1	HIGH	アクセシビリティ	src/Dialog.tsx:42	<button><XIcon /></button>	aria-label="Close" を追加し、アイコンをアクセシビリティツリーから除外する	アイコンのみのコントロールに、アクセシブルネームがありません

各行は根本原因を1つ示します。ドメインには、better- の接頭辞を除いた担当スキル名を指定します。モードごとの指摘事項の上限を守ります。指摘事項がない場合はテーブルを省略し、「対応可能なインターフェース上の指摘事項はありません。」と記載します。

検討したが却下した候補

quick モードでは1～3件、full モードでは2～5件を含めます。

場所	候補	却下した理由
src/Card.tsx:28	影を強くする	既存の奥行きは共有サーフェストークンに合致しており、1つのカードだけを変更すると一貫性が損なわれるため

これらはレビュー中に確認した実際の候補とし、数合わせのために作り出してはいけません。対象範囲に境界的な候補が実際に少ない場合は、存在するものを記載し、その旨を説明します。

検証

各チェックまたは操作について、正確なコマンドまたは手順と、確認できた結果を記載します。合格したチェックと 未検証 としたチェックは分けて示します。

判定

次のいずれか1つで締めくくります。

• ブロック：HIGH の指摘事項が1件以上残っています。
• 要修正：残っている指摘事項は MEDIUM または LOW のみです。
• 承認：対応可能な指摘事項がなく、記載したカバレッジが検証済みです。

変更範囲に絞ったレビュー

interface-review がバージョン管理から範囲を特定した場合は、上記の形式に次の4項目を追加します。このファイルが形式、上限、判定を定め、interface-review が範囲とステータスを提供するため、これらはここに記載されています。

1. 範囲ブロック。 範囲とカバレッジは、interface-review が作成した変更範囲の表から始め、その後に上記のカバレッジ表を変更せずに続けます。変更範囲に根拠がないドメインは Not reviewed: no evidence in the change scope とします。これはカバレッジに関する記述であり、問題点ではありません。

2. ステータス列。 指摘事項の表には、Domain の後に Status 列を追加し、Introduced または Regression を記載します。

   #	Severity	Domain	Status	Location	Before	After	Why
   1	HIGH	Accessibility	Regression	src/Dialog.tsx:42	この変更で aria-label="Close" が削除された	アイコンのみのコントロールに aria-label="Close" を復元する	この変更前は閉じるコントロールにアクセシブルな名前がありましたが、現在はありません

   Introduced または Regression の指摘事項がない場合は、表を省略し、「この変更には対応が必要なインターフェース上の指摘事項はありません。」と記載します。

3. 既存の問題のセクション。 検討したものの却下した項目の後に配置し、最大3件を深刻度の高い順に、今回の変更で対処する責任はないことを明確にして記載します。該当するものがなければ省略します。

   Severity	Domain	Location	Issue
   MEDIUM	Typography	src/Toolbar.tsx:7	数値バッジにプロポーショナル数字を使用しています。この変更より前から存在します

4. 上限と判定。 どちらも Introduced と Regression のみを対象とします。Pre-existing の指摘事項は上限の対象外です。そのため、既存ファイルに変更を加えてもファイル全体の監査に発展することはありません。また、判定の対象外でもあるため、指摘事項が既存の問題だけの変更は Approve となります。