Layout Witness (レイアウトウィットネス)
ページのスキャン性と操作性を高めます。関連する要素に明確なグループ化を施し、繰り返しコンポーネントの一貫性を保ち、コンテンツやビューポートサイズが変化してもそれらの関係性を維持します。ガイドを利用して、編集時に修正すべき点を判断します。
既存の開発タブでChrome拡張機能を使用します。ローカルエージェント接続と連携させてガイドを制御し、ターミナル上でページと要素の測定値をJSONとして読み取ります。オプションのPlaywright CLIを使用すれば、新しいブラウザコンテキストで無人キャプチャを実行できます。
既存のタブに接続する
chrome://extensions から、完全な layout-witness スキルディレクトリを展開済み拡張機能として読み込みます。Chrome 116以降が必要です。
WITNESS_DIRにインストール済みのスキルディレクトリを設定します。一度(cd "$WITNESS_DIR" && npm ci --omit=dev)を実行し、その後node "$WITNESS_DIR/scripts/agent.mjs" serveを永続的なターミナルで起動します。- 開発タブのツールバーから Layout Witness を開きます。Agent access (エージェントアクセス) の下に、ターミナルに表示されたペアリングURLを貼り付け、Connect agent (エージェントに接続) を選択します。これにより1つのタブが認証されます。アクセスがない場合は、ユーザーにそのタブを一度ペアリングするよう依頼してください。
- 同じマシンの任意のターミナルからCLIを使用します。編集中はローカルサーバーを起動したままにします。
node "$WITNESS_DIR/scripts/agent.mjs" start
node "$WITNESS_DIR/scripts/agent.mjs" select 'header [aria-label="Search"]'
node "$WITNESS_DIR/scripts/agent.mjs" measure
# プロジェクトのCSSを編集し、devサーバーが適用するのを待ちます。
node "$WITNESS_DIR/scripts/agent.mjs" measure
measure はページ領域、チェック結果、および現在選択されている要素（利用可能な場合）を表示します。その要素には、レンダリングされたボックス、マージン、ボーダー、パディング、グリッドとギャップの値、タイポグラフィ（測定可能な場合はビューポートベースラインYを含む）、SVGジオメトリを含めることができます。表示されている要素を1つだけ選択するセレクターを使用します。編集時は選択を維持し、ブラウザが変更を適用した後にもう一度JSONを読み取ります。
status で接続を確認、clear で要素ガイドのみを削除、pick で手動クリック選択、import <rules.json> でプロジェクトルールを読み込み、defaults でデフォルトルールを復元します。stop で両方のガイドを削除し選択をクリアしてクリーンなレビューを行います。start と select で再開します。タブがコマンドの受け付けを停止すべき場合は、終了時に disconnect を使用します。同一オリジンのリロードでは、同じルート上でガイドと選択を復元できます。異なるオリジンまたはタブを閉じるとペアリングは終了します。
手動レビューの場合は、ツールバーポップアップで Start guides (ガイド開始)、Inspect element (要素を検査)、Stop guides (ガイド停止) を使用します。コピーを保存したい場合は Download report (レポートをダウンロード) が利用できます。
ガイドを有効にして作業する
- 期待されるレイアウトを設定します。 プロジェクトのレイアウトとコンポーネントルールを読み、既存のトークンと許容される兄弟コンポーネントを確認します。タスクに関係する関係性（共有の読み取りエッジ、ナビゲーショングループ間のギャップ、ボタンのインラインパディングなど）を書き留めます。新しいページでは、これらの関係性をブリーフから選択し、自分の前提を記録します。拡張機能のデフォルトグリッドは探索的なガイドとして扱います。
- ページから要素まで検査します。 編集前にガイドを起動します。レンダリングされた開始点をキャプチャし、問題のある要素を選択します。ラベルが密集している場合は、レポートで正確な測定値を確認します。新しいページでは、シェルがレンダリングされたらガイドを起動し、セクションやコントロールを追加する間もガイドをオンにしたままにします。
- 選択をアクティブにしたままソースを編集します。 測定値を期待値と比較します。その関係性を管理しているCSSまたは共有コンポーネントを修正します。devサーバーが編集を適用したら、別の要素を選択する前に同じ要素のガイドと測定値を確認します。リロードによって要素が置き換えられた場合は、復元された選択が意図したコントロールをまだ指していることを確認します。実際の値、期待値、測定結果を記録します。
- クリーンなレンダリングをレビューします。 まず修正後のガイドをキャプチャし、その後ガイドをオフにして実際のページを検査します。グループ化、階層、配置、折り返し、レイアウトが変化する幅での可視フォーカスを確認します。長いラベルや翻訳されたコンテンツ、関連する開いている状態、折りたたまれている状態、密集している状態を含めます。残っている問題と、確認した幅と状態を報告します。
| スコープ | 検査内容 |
|---|---|
| ページシェル | ページガイドを使用して、共有の読み取りエッジ、外側のガター、ヘッダー、サイドバー、メインエリア、フッターがブレークポイントでどのように適応するかを確認します。クリーンレンダリングでは、繰り返し表示されるアクションが見つけやすく、主要なタスクが最も視覚的に強調されていることを確認します。 |
| グループと繰り返しコンポーネント | ローカルグリッドトラックを使用して、領域内の配置とスパンを確認します。グループ間の間隔を、各コンポーネント内のパディングおよびギャップとは別に比較します。関連するアイテムが視覚的にグループ化されている状態を保ち、グループが積み重なったときの読み取り順序を確認します。 |
| 個々の要素 | コントロールを選択して、そのボックス、パディング、アイコンとラベルの間隔を検査します。整列させる予定のラベル間の行の高さとベースラインを比較します。同じファミリー内のアイコンサイズとストロークをレビューし、レンダリングサイズで光学バランスを判断します。インタラクティブターゲットはグリフとは別に測定します。 |
混雑したサイドバーの場合は、まず関連リンクがグループとして読め、隣接するセクションに明確なギャップがあるかを確認します。次に行を選択し、そのインセットとアイコン-ラベル間隔を同等の行と比較します。共有コンポーネントが各辺16pxを要求していてガイドが片側8pxと読んだ場合は、トークンを復元し、同じ選択を再測定します。ガイドをオフにして、展開時と折りたたみ時のサイドバーをコンテキスト内で確認します。
トークン値、名前付きエッジ間の配置、オーバーフローなどの明示的な期待値には厳密なチェックを使用します。階層と光学バランスはレンダリングされたページで判断します。プロジェクトのタイプスケールを使用して、ベースラインを揃えるべきかどうかを決定します。
デザインリファレンス
- Adobe Spectrum 2 は、近接がどのように関係性を示すか、間隔がスコープによってどのように異なるか、アイコンの間隔とストロークをファミリー内でレビューする方法を説明しています。間隔 · アイコンの基礎
- Figma は、ページ、ネストされた領域、コンポーネントパディング、テキストベースラインのガイドの選び方を示しています。レイアウトグリッド
- Linear のデザインリフレッシュは、密集したワークスペースにおける予測可能なヘッダーアクションと視覚的階層のケーススタディです。デザインリフレッシュ
アクセシビリティが範囲に含まれる場合は、WCAGを使用してリフロー、ユーザーのテキスト間隔オーバーライド、および実際のポインターターゲット（該当する例外を含む）を確認します。リフロー · テキスト間隔 · ターゲットサイズ
オプションの無人キャプチャ
自動化で、ビューポート幅やテーマをまたいだ新しいブラウザコンテキストが必要な場合はCLIを使用します。Node.js 22+ と Playwright Chromium が必要です。WITNESS_DIR にインストール済みのスキルディレクトリを設定し、そこに依存関係をインストールします:
(cd "$WITNESS_DIR" && npm ci && npx --no-install playwright install chromium)
プロジェクトからCLIを実行して、その設定と出力パスがそこで解決されるようにします:
node "$WITNESS_DIR/scripts/witness.mjs" capture http://localhost:3000 \
--config ./layout-witness.json --width 1440 --width 390 --strict \
--out .layout-witness/review
生成されたオーバーレイとJSONレポートを読み取ります。キャプチャモードは、各幅とテーマごとに新しいページを開きます。領域とチェックの定義については、ルールリファレンスを参照してください。対話型CLIワークフローには watch を使用します。