reviewing-interface-quality

インターフェース品質のレビュー

概要

「見た目をよくする」では、具体的なアクションにつながりません。インターフェース品質の問題には、明確な原因があります。たとえば、適用されていない間隔のスケール、4つの次元で同時に変化する階層、設計されていない状態などです。レビューは、原因と修正方法を明示して初めて役に立ちます。

基本原則： 指摘にはすべて、場所、原因、具体的な置き換え値を含めます。「間隔がしっくりこない」は指摘ではありません。「.card は padding: 14px を使っていますが、ほかはすべて8pxのスケールを使っています。var(--space-s) に変更してください」なら指摘になります。

関連スキル： designing-frontend-interfaces（ビジュアル）、designing-user-experience（動作）、building-accessible-interfaces（アクセシビリティ）。このスキルでは、これら3つすべてを基準に監査します。

絶対原則

NO FINDING WITHOUT EVIDENCE YOU ACTUALLY GATHERED

インターフェースをレビューするには、実際に見る必要があります。ソースを読んでレンダリング結果を推測するのはレビューではありません。オーバーフロー、レイアウトの崩れ、見えないテキスト、レイアウトシフト、壊れた状態など、レビューで見つけるべき種類の不具合を見落とします。

指摘を書く前に最低限必要な証拠： 1440pxのスクリーンショット、390pxのスクリーンショット、そして一貫性がないと指摘する対象の計算済み値。

チェックリスト

1. 証拠を集める — 2つの幅でレンダリングし、DOMと計算済みスタイルを取得する
2. パス1：第一印象 — 分析を始める前に5秒間見る
3. パス2：システムの一貫性 — 最も多くの問題を見つけられるパス
4. パス3：タイポグラフィ
5. パス4：レイアウトとレスポンシブ対応
6. パス5：状態と動作
7. パス6：アクセシビリティ
8. パス7：モーションとパフォーマンス
9. 報告する — 重大度を付け、各指摘に場所、原因、修正方法を記載する

ステップ1：証拠を集める

from playwright.sync_api import sync_playwright
URL = "http://localhost:5173"   # or file:///abs/path/index.html

with sync_playwright() as p:
    b = p.chromium.launch()
    pg = b.new_page(viewport={"width": 1440, "height": 900})
    errors = []
    pg.on("console", lambda m: m.type == "error" and errors.append(m.text))
    pg.goto(URL); pg.wait_for_load_state("networkidle")
    pg.screenshot(path="/tmp/rev-desktop.png", full_page=True)

    # Horizontal overflow — always a bug
    print("OVERFLOW:", pg.evaluate("""() => [...document.querySelectorAll('*')]
        .filter(e => e.getBoundingClientRect().right > document.documentElement.clientWidth + 1)
        .slice(0, 10).map(e => e.tagName + '.' + e.className)"""))

    # Every distinct value actually used — the consistency audit
    for prop in ["font-size", "font-family", "border-radius", "box-shadow", "padding", "color"]:
        vals = pg.evaluate("""(p) => [...new Set([...document.querySelectorAll('*')]
            .map(e => getComputedStyle(e)[p]))].filter(v => v && v!=='none' && v!=='0px')""", prop)
        print(f"{prop}: {len(vals)} distinct →", vals[:14])

    pg.set_viewport_size({"width": 390, "height": 844})
    pg.screenshot(path="/tmp/rev-mobile.png", full_page=True)
    print("CONSOLE ERRORS:", errors)
    b.close()

次に、両方のスクリーンショットを確認します。異なる値の数からシステムが崩れた箇所がわかり、スクリーンショットから実際の見た目がわかります。両方が必要です。

サーバーを使用するアプリでは、これを testing-webapps/scripts/with_server.py でラップします。

UIを実際にレンダリングできない場合（ランタイムがない、断片である、コンポーネントを単独で扱っているなど）は、その旨を報告書にはっきりと記載し、すべてのビジュアルに関する指摘を PLAUSIBLE として、CONFIRMED とは区別してください。

ステップ2：第一印象

デスクトップのスクリーンショットを5秒間見て、分析を始める前に次の質問に答えます。

1. これは何ですか？ 5秒でわからない場合、階層に問題があります。
2. 何をすればよいですか？ 主要なアクションはひと目でわかる必要があります。
3. 最初に目が行くのはどこですか？ それは最も重要な要素ですか？
4. 美的な方向性を言葉にできますか？ 「すっきりしている」「モダン」は、方向性がないことを意味します。
5. 生成されたものだと思いますか？ そう思うなら、そう判断した具体的な特徴を挙げてください。

次に進む前に、これらの答えを書き留めてください。細部の監査を始めると、最初の先入観のない見方には戻れません。そして、それこそが実際のユーザーの見方です。

ステップ3：システムの一貫性

最も多くの問題を見つけられるパスです。「仕上がりが粗く見える」原因のほとんどはここにあり、指摘はすべて客観的です。

チェック項目	しきい値	よくある原因
異なる font-size の値	> 8	サイズを場当たり的に選んでおり、比率のスケールがない
異なる font-family の値	> 3	3つ目の書体が紛れ込んでいる、またはフォールバックの解決結果が異なる
異なる border-radius の値	> 2	半径が混在している — 最も目立つ素人っぽさの兆候
異なる box-shadow の値	> 3	コンポーネントごとに新しい影を作っている
間隔のスケールに合わないパディングの値	1つでもあれば	トークンではなく、生のpx値を使っている
color に指定された異なるグレー	> 5	インクの段階的な色のスケールがなく、コンポーネントごとに個別に色を選んでいる
アクセントカラーが占める面積	> 10%	強調ではなく装飾としてアクセントカラーを使っている

# Fast static pass over source
grep -rEo '(padding|margin|gap|font-size):[^;]+' src/ | grep -E '[0-9]+px' | sort | uniq -c | sort -rn
grep -rEo 'border-radius:[^;]+' src/ | sort | uniq -c

こちらも確認します： デザイントークンが定義されているのに使われていませんか？ 美しいスケールを定義した :root ブロックがある一方で、コンポーネントには生のpx値が並んでいる。これは非常によくある、しかも簡単に修正できる指摘です。

ステップ 4：タイポグラフィ

• サイズには統一された比率を適用し、目測で決めていない
• ディスプレイ用書体に Inter、Roboto、system-ui を使っていない
• ウェイトは最大 3 種類
• 本文の行長は 60〜75ch（ページ幅いっぱいでも 30ch でもない）
• 行の高さはサイズに反比例している（本文は約 1.6、ディスプレイ用は約 1.0）
• 大きなディスプレイ用文字には負のトラッキングを設定している
• 本文に文字間隔を追加していない
• 段落を中央揃えにしていない。すべて大文字の文も使っていない
• 数値列に tabular-nums を使用している
• 見出しに text-wrap: balance を使用している
• 見出しの最終行に単語が 1 つだけ残っていない

ステップ 5：レイアウトとレスポンシブ対応

• どの幅でもページを横にスクロールする必要がない（オーバーフローのクエリ結果を確認）
• 意図した余白がない状態で、コンテンツがビューポートの端に触れていない
• 関連する項目どうしは、関連のない項目どうしより視覚的に近い（内側と外側の比率は 4:1）
• セクション間の余白は重要度に応じて変化し、ページ全体で均一になっていない
• 配置に一貫性があり、わずかなずれ（左端が 12px と 16px など）がない
• 390px では、重なりやテキストのクリッピングがなく、固定要素がコンテンツを覆っていない
• テーブルとコードブロックはページではなく、それぞれのコンテナー内でスクロールする
• 画像に width／height または aspect-ratio が指定され、レイアウトシフトが発生しない
• 100vh ではなく 100dvh／100svh を使用している
• グリッドを意図的に少なくとも 1 か所崩している。または、デザインが均一な中央揃えのカラムになっている

ステップ 6：状態と動作

designing-user-experience に照らして、それぞれ確認してください。通常、これらは間違っているというより 不足している ため、レンダリング結果だけでなくコードも監査してください。

• 空の状態が、初回利用時、検索結果なし、クリア後でそれぞれ異なる
• 読み込み中でも、すでに表示されているコンテンツを消さない
• スケルトンは実際のコンテンツの形状に合わせ、表示まで約 200ms 遅延する
• エラー時には対処方法を示し、対処するための操作手段を提供する
• 生のステータスコードやスタックトレースをユーザーに表示しない
• エラーが発生しても、フォームの入力内容を保持する
• バリデーションはキー入力時ではなく、フォーカスを外したときに行う
• 入力欄に適切な type、inputmode、autocomplete を設定する
• ボタンのラベルで操作内容が分かり、文脈がなくても理解できる
• 破壊的な操作には、取り消し機能または具体的な確認を用意する
• 5 つのインタラクティブ状態をすべて用意する：通常、ホバー、アクティブ、フォーカス表示、無効
• フィルター／タブ／モーダルの状態が URL に反映される
• タッチターゲットは 44px 以上で、ホバー時のみ利用できる機能がない

ステップ 7：アクセシビリティ

自動スキャンを実行してから、キーボードで操作を確認してください。詳細は building-accessible-interfaces を参照してください。

npx @axe-core/cli http://localhost:5173 --exit

• axe の違反がゼロである。または、残る違反についてそれぞれ文書で正当な理由を示している
• 本文テキストは 4.5:1、大きなテキストは 3:1 のコントラスト比を確保している（ライトモードとダークモードの両方）
• どこでもフォーカスが視認できる。outline: none を代替手段なしで使用していない
• Tab キーの移動順が視覚的な順序と一致している
• モーダルを開くとフォーカスが移動し、閉じると元の位置に戻る
• すべての画像に alt が設定されている（装飾目的の画像は空にする）
• アイコンのみのボタンすべてにアクセシブルな名前が付いている
• <h1> は 1 つだけで、見出しレベルを飛ばしていない
• <main>、<nav>、<header> のランドマークがある
• 状態を色だけで伝えていない
• 非同期更新のためのライブリージョンがあり、コンテンツより前に存在している

ステップ 8：モーションとパフォーマンス

• prefers-reduced-motion ブロックがある
• アニメーションには transform／opacity／filter のみを使用し、width／height／top／left は使用していない
• transition: all を使用していない
• ユーザー操作によるモーションの継続時間は 80〜450ms
• 入場時はイーズアウト、退場時はより速いイーズインにする
• 100ms 未満の処理にスピナーを表示しない
• コンソールエラーがゼロ
• フォントに font-display: swap とメトリクスを合わせたフォールバックを設定している
• 読み込み時にレイアウトシフトが発生しない（スクリーンショットの連続画像を確認するか、CLS を確認）

レポート形式

指摘事項を重要度順に並べてください。各指摘には、場所、原因、修正方法を記載してください。

## First Impression
[The 5 answers from Step 2 — the naive read, verbatim]

## Evidence
Rendered at 1440×900 and 390×844. 34 distinct font-sizes, 6 border-radii,
9 box-shadows. 2 console errors. 1 horizontal overflow.

## Critical — breaks the interface for some users
**Focus indicator removed globally**
`src/styles/base.css:12` — `*:focus { outline: none }` with no replacement.
Keyboard users cannot tell where they are; WCAG 2.4.7 failure.
Fix: delete it, add `:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px }`.

## Important — visibly degrades quality
**Spacing scale not enforced**
17 distinct padding values including `14px`, `18px`, `22px` (`Card.tsx:8`,
`Panel.tsx:22`, `Modal.tsx:41`). Tokens exist in `:root` but are unused, so
nothing aligns to a common rhythm.
Fix: replace every raw px with the nearest `--space-*` token.

## Minor — polish
**Headings orphan their last word**
`h2` in `Hero.tsx:14` wraps "started" alone onto line 2 at 1440px.
Fix: add `text-wrap: balance`.

## Strengths
[Specific, not flattery. "The type pairing carries the direction" — not "looks good".]

## Verdict
Ship / Ship with the Critical items fixed / Needs rework — plus one sentence of reasoning.

重大度

重大度	定義
Critical	一部のユーザーが利用できない、またはデータが失われる問題です。キーボードトラップ、フォーカスの消失、本文テキストのコントラスト不足、エラー時のフォーム内容の消去、モバイルでの横方向のオーバーフローなどが該当します。
Important	品質を目に見えて損なう、または実際の作業を妨げる問題です。システム値の不統一、状態の欠落、読みづらい行長、エラーからの復旧手段の欠落などが該当します。
Minor	仕上げに関する問題です。行末に孤立した単語、わずかにずれた表示時間、もう少し小さくできる影などが該当します。

報告を水増ししないでください。キーボードトラップと 2px の位置ずれを混ぜた 20 件より、実際に存在する 5 件の指摘のほうが価値があります。水増しされた報告は、キーボードトラップを埋もれさせます。

よくある間違い

インターフェースではなくコードをレビューする。 レビューで見つけるべき不具合は、レンダリングされた状態でしか見えないものです。

「なんとなく違和感がある」という指摘。 原因を言い表せないなら、探し続けてください。品質上の問題には、すべて具体的な原因があります。

デスクトップだけで確認する。 不具合の多くは 390px で現れます。どちらの幅も、必ず確認してください。

レビューではなく再設計をする。 「これをダッシュボードとして作り直す」は指摘ではありません。方向性そのものが問題でない限り、既存のものを修正してください。方向性に問題がある場合は、一度だけ、最上位の指摘として伝えてください。

重大度を過剰に引き上げる。 すべてを Critical と呼ぶと、何も意味を持たなくなります。本当に深刻な問題にだけ使ってください。

違反を列挙し、修正案を書かない。 「コントラストが不足しています」だけでは指摘として不十分です。「--ink-3 #8b857c と --base #f4f1ea のコントラスト比は 2.9:1 です。4.5:1 にするには #6b6459 に暗くしてください」なら、指摘として完結しています。

第一印象を見落とす。 3 回も確認を重ねると、先入観のない読み取りは取り戻せません。そして、それは多くのユーザーが得る唯一の読み取りです。