レイアウト監査
layout-audit.mjs（このファイルと同じディレクトリに配置）は、複数の画面幅でページを表示し、DOM を測定します。人間が「レイアウト欠陥」と判断するものだけを報告します。アクセシビリティは別の観点であり、このツールでは扱いません。
node ~/.claude/skills/layout-audit/layout-audit.mjs --base=http://localhost:3000 --routes=/,/pricing
フラグ: --routes（カンマ区切り、デフォルトは /）、--widths（デフォルトは 1440x900,390x844）、--auth=user:pass（Basic 認証用）、--shots=<dir>（ルートと幅ごとにスクリーンショットも保存）、--json（実行結果の差分を取るため）。Playwright はグローバルにインストールされた @playwright/cli を使用するため、プロジェクトに依存関係は追加されません。
チェック項目
| チェック | 意味 |
|---|---|
viewport-overflow | 要素がビューポートの端を超えて表示される — ページが横スクロールする |
clipped-text | ボックスが自身のテキストを切り取り、省略記号も title 属性もなく、テキストにアクセスできない |
collapsed-text | 要素にテキストがあるが高さがゼロ — 空白の隙間として認識される |
overlapping-text | 二つのテキストボックスが同じピクセル上に描画される |
tiny-text | スマートフォンで読めない小さなフォントサイズ |
結果の扱い方
- 開発中ではなく、ビルドに対して実行してください。 ホットリロード中はスタイルが中途半端に適用されます。
- 修正に入る前に、要素ごとに結果をグループ化してください。 10 ルートで共通して使われるヘッダーは、1 つの欠陥であって 10 個の欠陥ではありません。レポートの件数は作業量を示すものではありません。
- 省略記号と title 属性によるテキスト省略はパターンであり、欠陥ではありません。 このツールはそのようなケースをすでに除外しています。もしボックスがテキストをクリップしていると報告された場合、テキストは本当にアクセス不能です。
- 同じ種類の要素で繰り返し検出される問題は、デザイン上の判断です。 画面全体のフォントサイズや色は、デザインを担当する人の権限に属します。数値を報告し、その人に判断を任せてください。軽率にカラーパレットを変更しないでください。
- どのルールにも該当しない問題でも、スクリーンショットは捉えます。
--shotsを有効にして、ルールが「問題なし」と判断したページを、特にスマートフォン幅で確認してください。 - 問題なしの結果は、実際のスマートフォンでの動作を保証しません。 Playwright の WebKit を iPhone プロファイルで実行しても、実際の iPhone 上の Safari とは異なります。報告されたスマートフォンの欠陥が再現しない場合は、「動作する」と報告するのではなく、その旨を伝え、デバイスを確認するか、疑わしい機構を完全に取り除いてください。
- ルールが正しく動作することを確認してから、ゼロ件の結果を信用してください。 スクラッチページに意図的に欠陥を仕込み、チェックを実行し、ルールがそれを報告することを確認してください。特にページレベルのクリッピングは、単純な幅の比較ではすべてのページで合格になってしまいます。