better-interface

インターフェース

このスキルでは、複数の専門分野にまたがるレビューを実施します。インターフェースを各 better-* スキルに振り分け、それぞれの根拠を集めて、優先順位を付けた判定にまとめます。

このスキルが担当するのはオーケストレーションのみです。アクセシビリティのルールは better-accessibility、構造は better-layout、コピーは better-writing、文字組みは better-typography、カラーは better-colors、ビジュアルの仕上げと動きは better-ui が担当します。

未コミットの変更、ブランチ、プルリクエストを対象とするレビューは interface-review が担当します。

好みではなく、根拠を示す

エスカレーションのトリガーを厳しく確認し、意図的なプロジェクト上の選択には手を加えないでください。トリガーに該当するものは、スタイルガイドの内容にかかわらず問題です。単に好みと異なる密度、角丸、文体は指摘事項ではありません。

報告の基準は根拠です。Approve の基準は、確認したと主張する内容を実際に確認していることです。

1. まず対象範囲を特定する

依頼と現在のワークスペースから、画面、フロー、機能、またはリポジトリの対象範囲を推定します。出力では、特定した対象範囲を明示してください。

空、読み込み中、エラー、狭い幅の各状態が存在する場合も含め、すべての領域を対象にします。

対象が広すぎて信頼できるレビューができない場合は、ひとつの完全なフローに絞ります。依頼の中心となるフローを選び、それが特定できない場合は、すべてのユーザーが通る入口のフローを選びます。対象範囲の境界と除外した内容を明示してください。確認していない画面や機能をレビューしたかのように示してはいけません。

2. 変更のレビューは interface-review に依頼する

ブランチ、プルリクエスト、コミット範囲、未コミットの変更に言及する依頼は、変更レビューです。その旨を伝え、ユーザー自身に interface-review を実行するよう依頼してください。これはユーザーが呼び出すツールであり、ここから起動することはできません。変更範囲を独自に特定してはいけません。推測した差分では、誰も確認できない範囲をレポートに設定することになります。

interface-review からレビュー結果が返されたら、以下の内容をすべて適用してください。上限と判定の対象は Introduced と Regression の指摘事項のみです。そのため、指摘事項が Pre-existing だけの変更は Approve となります。

3. 判断の前に下調べをする

フレームワーク、スタイリングシステム、コンポーネントライブラリ、デザイントークン、対応ビューポート、プレビューまたはテストのコマンドを特定します。修正案はすべてプロジェクト独自の慣習に沿って記述し、別の技術スタックへの移行を求めてはいけません。

次に、プロジェクト独自のインターフェースに関するドキュメントを確認します。CONTRIBUTING.md、CODING_STANDARDS.md、AGENTS.md、CLAUDE.md、デザインシステムのドキュメント、Storybook のドキュメント、インターフェース関連の ADR を確認してください。見つかったものを列挙するか、該当するドキュメントがないことを明記します。

文書化された規約は好みに関する判断の基準になりますが、トリガーや領域固有のルール違反を正当化するものではありません。変わるのは報告先です。ガイドラインや共有トークンが原因の場合は、該当するコンポーネントを場所として示し、原因となるものについて一度だけ報告します。

4. 各領域のスキルを信頼できる情報源として使う

以下に挙げる担当スキルをすべて読み込み、各領域のレビューを完了してから内容を統合します。基礎的な問題が仕上げによって見えなくならないよう、次の順序で確認してください。

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

各スキルから、原則、参考資料、検証項目を確認します。重大度の基準と書式は単独利用向けのものです。このファイルに定めるものが、それらに代わります。

担当スキルを利用できない場合、その領域を Not reviewed とし、スキル名を明記して、残りの領域のレビューを続けます。記憶を頼りにルールを再現したり、別のスキルで代用したり、全領域を網羅したと主張したりしてはいけません。

複数のスキルが同じ問題を扱っているように見える場合は、根本となるルールの担当スキルに割り当て、副次的な影響を Why 欄に記載します。

5. 検証できる項目を検証する

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

根拠を示す

すべての指摘に path/to/file:line を記載し、現在の実装を示します。結果が実行時の動作によって決まる場合、ソースコードだけでは視覚的な指摘の根拠にならず、スクリーンショットだけではコードに関する指摘の根拠になりません。

ユーザーへの影響度で優先順位を付ける

共通の重要度基準を使用します。

• HIGH：タスクを妨げる、ユーザーに誤解を与える、コンテンツやコントロールを隠す、データ損失のリスクを生む、または繰り返し発生する全体的な不具合を引き起こす。
• MEDIUM：理解、効率、適応性、一貫性を大きく損なう。
• LOW：タスクへの影響が限定的な、個別の仕上げ上の問題。

同じ重要度の中では、指摘が及ぶ場所の数と、修正ひとつでどれだけ改善できるかに基づいて順位を付けます。トークンや共有コンポーネントの修正は、同じ症状がひとつの末端要素にある場合より優先されます。

重要度を引き上げる条件。 担当スキルが以下のいずれかを確認した場合、表面的な影響の小ささを理由に重要度を下げず、必ず HIGH とします。

• インタラクティブなコントロールにアクセシブルな名前がない。
• キーボードで操作できるコントロールに、視認可能なフォーカスインジケーターがない。
• ポインターでは操作できるコントロールや経路を、キーボードでは操作できない。
• prefers-reduced-motion を無視するモーションや自動再生コンテンツがある。
• 320px の幅または 200% のズーム時に、コンテンツやコントロールが切れる、重なる、または到達できない。
• 本文またはコントロールのテキストのレンダリング時のコントラスト比が、必須の比率を満たさない。
• 状態や意味が色だけで伝えられている。
• 破壊的な操作に確認、取り消し、または明確な区別がない。
• 省略されたコンテンツの全体を確認する方法がない。
• スクロール領域の端を越えた先、または視認可能な手掛かりのない開示領域の背後でしか、コンテンツやコントロールに到達できない。
• エラーに、その復旧方法が示されていない。
• 破壊的でない操作に危険を示す色相を使うなど、意味上の色をその意味に反して使用している。
• アニメーションが実行されないとき、状態変化がモーションだけで伝えられ、色、アイコン、ラベルのいずれも残らない。

これらの条件は、ほかのすべての指摘より優先されます。上限の件数を超える数の条件に該当する場合は、まずそれらを列挙し、上限により除外した数を明記します。上限によって、ブロッカーの報告を省略してはなりません。

これらが定めるのは重要度であり、新たなルールではありません。症状が存在するかどうかは担当スキルが判断し、この一覧はその影響の大きさを定めます。

より低コストの修正を優先する

重要度は指摘の深刻さを示し、ここでは提案する修正を選びます。複数の修正が可能な場合は、次のうち最初に有効なものを選びます。

1. 削除する。 余白で代替できる区切り、高頻度の操作に対するアニメーション、ネイティブ要素で冗長になる ARIA 属性、何からもインポートされていないランプ。
2. プラットフォームの機能を使う。 独自に作り直す代わりに、ネイティブ要素、ネイティブコントロール、またはブラウザー標準のフォーカスリングを使う。
3. プロジェクトにあるものを再利用する。 新しい値を追加する前に、既存のトークン、スペーシングの段階、モーションカーブを使う。
4. 値を修正する。 担当スキルが示す正確な値を使い、誤ったイージング、角丸、間隔、またはコントラストの組み合わせを修正する。
5. 追加する。 新しいトークン、ラッパー、メディアクエリー、またはプラットフォームで提供できない ARIA 属性を追加する。

レビュー対象のコードで、削除すれば解決するものが追加されている場合、それは指摘とし、修正後には削除を示します。

全体に関わる指摘をまとめる

根本原因ひとつにつき、指摘ひとつとし、確認できたすべての箇所を同じ行に記載します。指摘は最大 15 件まで報告します。上限に達するよう無理に件数を増やしてはなりません。指摘が少ないレビューや、指摘がないレビューも妥当な結果です。

デフォルトでは変更を加えずにレビューする

レビューの依頼は読み取り専用として扱います。ユーザーが指摘の実装も依頼していない限り、ソースを編集しないでください。実装を依頼された場合は、集約したレポートを変更範囲とし、関連する検証を再実行してください。

終了前の確認

間違い	修正
ドメインごとに調査結果のセクションを分ける	重要度、次に到達範囲の順で並べた1つの表にまとめます
根拠がソースだけの表示に関する主張	表示状態を確認するか、未検証と記載します
アクセシブルな名前またはフォーカスリングがない問題を、影響範囲が小さいという理由でMEDIUMと評価する	該当する問題は見つけ次第HIGHとします
根拠の欄にファイル、コンポーネント、確認項目のいずれも記載されていないカバレッジ行	そのドメインを調査するか、理由を添えて未レビューと記載します
スキルが読み込まれていないのに、ドメインをClearとする	未レビューとし、スキル名を記載します
同じ症状をコンポーネントごとに別の行で報告する	共通のトークンまたはコンポーネントについて1行にまとめ、すべての箇所を列挙します
ラッパー、トークン、ARIA 属性を追加する修正後	まず、削除する方法またはネイティブ要素で直せないか確認します
プロジェクトで使われていないライブラリやスタイリングシステムを使って修正を記述する	プロジェクト独自の書き方に合わせて書き直します

レビュー出力形式

形式はreview-format.mdに記載されています。対象範囲とカバレッジ、検出事項の表、検証、判定が含まれます。検出事項をそこに報告するまで、レビューは完了していません。