レスポンシブWeb: モバイルファースト、任意のスタック、検証済み は何をしますか?
目標は、誰かが選んだ5つのデバイス幅だけでなく、あらゆる幅で動作するレイアウトです。
バグはその間、例えば412px、905px、max-width: 767px と min-width: 769px の両方が適用されなくなる1ピクセルに潜んでいます。そのため、このスキルは常にセットで使用する2つの部分から成ります。
- モバイルファーストで構築する: レイアウトが自動的に適応し、ブレークポイントを最小限にするように書きます。
- 証明する:
scripts/check_responsive.pyを実行し、ページをレンダリングしてあらゆる幅でレイアウトを測定します。スクリーンショット1、2枚で「問題なさそうに見える」は証明になりません。「完了」とは、チェッカーが0エラーを報告することを意味します。
チェッカーはレンダリングされたページ(DOMボックスと算出スタイル)だけを見るため、CSSがどのように書かれたかは気にしません。それが、このスキルがあらゆるテクノロジーで機能する理由です。
0. まずプロジェクトを読む
CSSを書く前に、少し時間をかけて以下を確認してください。
- ここでのスタイルの書き方: Tailwind(
tailwind.config.*または CSS内の@theme)、Bootstrap/SCSS変数、CSS Modules、styled-components/emotion、Vue/Svelteのスコープ付きスタイル、プレーンCSSファイル。同じシステム、同じトークンで新しいコードを書いてください。2つ目のスタイリングシステムは保守上のバグになります。 - 既存のブレークポイントを再利用すること。コンテンツが必要としない限り、新しいものを発明しないでください。
- ページの見方: 静的
.htmlファイル、または開発サーバー(npm run dev、php artisan serve、python manage.py runserver、rails s、dotnet watch...)。チェッカー用のURLまたはファイルパスが必要です。
references/stacks.md に、一般的なスタックにおけるモバイルファーストの構文とブレークポイントの場所を示しています。
1. モバイルファーストで構築する
メディアクエリなしで、最小の画面用のベーススタイルを書きます。スペースが増えるにつれてレイアウトを追加し、min-width クエリを使用します。 スマートフォンには最もシンプルなCSSを適用し、コンテンツは自然に積み重なり、各ブレークポイントは単に追加するだけです。デスクトップファーストの方法(デスクトップを書いてから max-width で下方修正する)では、修正の間に隙間が生じ、そこがほとんどのレスポンシブバグの発生源となります。
コードベースがすでにデスクトップファーストであれば、書き直さないでください。新しい部分や変更した部分は、その規則内でモバイルファーストで書き、チェッカーが見つけたものを修正してください。
ブレークポイントなしで適応するレイアウトを優先する
- グリッド:
grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr))。スペースが許す限り列が自動的に現れ、ブレークポイントが不要で、320pxでもオーバーフローしません(min(100%, …)の部分がそれを防ぎます)。 - 折り返すべき行:
display: flex; flex-wrap: wrap; gap: …と適切なflex-basis。 - サイズ:
width: 640pxの代わりにwidth: 100%; max-width: 40rem。clamp(min, preferred, max)を使った流動的なタイポグラフィとスペーシング。 - 異なる幅のスロット(サイドバー vs メインカラム)に配置されるコンポーネント: コンテナクエリ(
container-type: inline-size+@container)を使用し、ウィンドウではなくスロットに応答するようにします。 - コンテンツが崩れる箇所(何かおかしくなるまでウィンドウを狭くする)にブレークポイントを追加し、デバイス幅に基づいて追加しないでください。
既知のレイアウト破壊パターン。書くときにそれぞれ確認すること。
| 破壊パターン | なぜ壊れるか | 代わりに使うもの |
|---|---|---|
コンテナに固定の width/min-width (px) | 320pxのスマホより広い | max-width + width:100%、%、fr、minmax() |
| 長いコンテンツを持つflex/grid子要素 | 子要素はデフォルトで min-width: auto になり、縮小を拒否する | 子要素に min-width: 0(または minmax(0,1fr)) |
| 長い単語、URL、メールアドレス、コード | 改行機会がない | テキストコンテナに overflow-wrap: anywhere |
ボタン/ラベル/ナビの white-space: nowrap | テキストが折り返せず、幅を押し広げる | 折り返しを許可するか、min-width:0 + title で省略記号を使う |
| 画像、動画、iframe、埋め込み | 固有の幅が画面より大きい | max-width:100%; height:auto; 埋め込みには aspect-ratio |
| テーブル | 列がコンテンツより小さく縮小できない | overflow-x:auto のコンテナで囲むか、小さな画面では行を積み重ねる |
pre/code ブロック | 空白が保持される | ブロックに overflow-x:auto |
100vw | スクロールバーを含むため、デスクトップでは約15px広くなる | 100%(または注意して本当に全幅にしたい場合のみ 100dvw) |
テキストのあるボックスに固定 height | スマホでテキストが折り返されて行数が増え、溢れたりクリップされる | min-height、または高さを指定しない |
| コンテンツの絶対配置 | スペースを取らず、他の幅で衝突する | 通常フロー/グリッド; 絶対配置は装飾のみに使う |
height: 100vh のヒーローセクション | モバイルブラウザのバーや短い横向き画面で切り取られる | min-height: 100svh(その前に 100vh のフォールバックを付ける) |
症状を隠してはいけない
html/bodyにoverflow-x: hiddenを設定して横スクロールを止めないでください。コンテンツがまだ切り取られているのにバグを隠し(さらにposition: stickyを壊します)。幅が広すぎる要素を見つけてください。チェッカーはこのマスキングをclipped-offscreenとして報告します。user-scalable=noやmaximum-scale=1は使用しないでください。ズームをブロックすることはアクセシビリティ違反です(WCAG 1.4.4)。- レイアウトのためにJavaScriptの幅チェックやユーザーエージェントスニッフィングを使用しないでください。CSSのメディアクエリ/コンテナクエリがちらつきなく行います。JSは動作(
matchMedia)には問題ありませんが、レイアウトには使わないでください。 - テストをパスさせるためにテスト自体を変更しないでください(
--minを上げる、無視リストに追加してエラーを消すなど)。
タッチ、入力、ビューポート
- すべてのページのheadに
<meta name="viewport" content="width=device-width, initial-scale=1">を設定します。 - タップターゲットは最低 24x24px(WCAG 2.2 AA)。タッチスクリーン上のボタンやアイコン操作は 44x44px を目指し、隣接要素との間隔を保ちます。
- ホバー専用のUI(コンテンツを表示するメニュー、ツールチップ)には
@media (hover: hover)とタップ用の代替手段が必要です。 - フォームフィールドの
font-sizeはスマホでは16px以上にします。そうしないとiOS Safariがフォーカス時にズームインします。適切なtype、inputmode、autocompleteを使用します。 - 短い横向きスマホ(高さ320~430px)は実際に存在します。固定ヘッダーとクッキーバナーが画面の約3分の1以上を覆わないようにします。短い高さでは折りたたむか縮小します(
@media (max-height: 500px))。 - ノッチのあるデバイス:
viewport-fit=coverと一緒にenv(safe-area-inset-*)パディングのみを使用します。
タイポグラフィ、メディア、ナビゲーション、コンテンツ
- タイプには
rem、見出しにはclamp()、行長は上限を設定(max-width: 65chなど)、行間は単位なし。 - 画像: 写真には
srcset/sizes、レイアウトシフトを避けるためにwidth/height属性またはaspect-ratio、ボックスの比率が画像と異なる場合はobject-fit: cover(そうしないと伸びます)。 - ナビゲーション: 小さな画面では、実際の
<button>でaria-expanded/aria-controlsを使いメニューを開きます。リンクが実際に収まる幅からインラインリンクを表示します。 - コンテンツのパリティを維持する: 収まりにくいからといってモバイルでコンテンツを落とさないでください。並べ替え、圧縮、または折りたたんでください。
references/patterns.md には、これらの各項目(グリッド、ナビ、テーブル、フォーム、ヒーロー、カード、メディア)に対するコピー可能なCSSがあります。
2. 検証: チェッカーを実行する
初期設定(Python 3.9以上):
pip install playwright
python -m playwright install chromium
レンダリングされたページに対して実行します。開発サーバーがある場合は最初に起動してください。
python <skill-dir>/scripts/check_responsive.py http://localhost:5173/ --out responsive-report
python <skill-dir>/scripts/check_responsive.py site/index.html --out responsive-report # 静的ファイル
- 複数ページ: 複数のURLを渡します。変更したページまたはルートすべてと、共有レイアウト(ヘッダー/フッター)を使用するページを少なくとも1つチェックします。
- レンダリングが遅いSPA:
--wait-for "#app main"。ログインが必要なページ:--storage-state state.json。 - 修正中の内部ループ:
--quick(約5~10秒)。完了を宣言する前に完全な実行を行ってください(ページあたり約20~40秒)。 - 終了コード: 0 = エラーなし、1 = エラー検出(
--strictの場合は警告も)、2 = 実行不可。
チェッカーの動作: 320~1920pxを10px刻みでスイープし、一般的なデバイス幅に加えてページ自身のCSSで見つかったすべてのブレークポイントの両側をチェックします。主要な幅を実際のモバイルエミュレーション(タッチ、meta viewport)で再読み込みし、4つの短い横向きスマホをチェックします。各幅で以下を測定します。
| エラー(修正必須) | 意味 |
|---|---|
horizontal-overflow | ページが横にスクロールする; はみ出している要素と、それを広くしている原因を特定 |
clipped-offscreen | コンテンツが画面端で切り取られている(多くの場合、bodyの overflow-x:hidden で隠されている) |
occluded-target | リンク/ボタンが別の要素(またはすべてのスクロール位置で固定バー)に覆われている |
small-target | タップターゲットが24px未満で、隣接要素と密集している |
text-spill / text-clipped | テキストがボックスからはみ出している / 固定サイズ + overflow:hidden で切り取られている |
text-overlap | 無関係な2つのブロックのテキストが互いに重なって描画されている |
distorted-media | 画像/動画が伸びている(ボックス比率 ≠ 自然比率、object-fit なし) |
viewport-meta, layout-viewport | viewport metaの欠落/ズームブロック; スマホがデスクトップ幅でレンダリングされる |
警告(修正するか、理由を説明すること): touch-target(タッチ幅で44px未満の操作要素)、small-text(スマホで12px未満)、input-zoom(16px未満の入力)、fixed-coverage(固定/スティッキーバーが短い画面の35%超を覆う)。
レポート(report.md、report.json)は発見事項を次のようにグループ化します:
1. **horizontal-overflow** at 320-610px; 568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
- worst: 296 px past right edge at 320px
- clues: stays exactly 600px wide at every failing width: a fixed width - use max-width/%/fr/minmax instead
- close-up: responsive-report/closeups/01-horizontal-overflow-320.png
clues 行が診断結果です。CSSを開く前に読んでください。
3. 修正ループ
- 最初に最も小さい幅で失敗している箇所を修正します。モバイルが基盤であり、それを修正することで残りも修正されることがよくあります。
- 手がかりが示す根本原因を、プロジェクトが使用するソース(Tailwindクラス、SCSSパーシャル、styled component)で修正し、一回限りのオーバーライドでは修正しないでください。
references/checks.mdに各チェックの原因と修正方法がリストされています。 - 再実行(
--quick)、繰り返し、その後完全な実行を行います。エラーが0になり、すべての警告が修正されるか理由が説明されるまで続けます。 - 意図的にルールを破るもの(画面からはみ出す装飾的なシェイプ、ヒーローコラージュでの意図的な重なり)がある場合は、その要素に
data-responsive-ignore="text-overlap"(チェック名をスペース区切りで)をマークし、コード内に理由をコメントとして追加します。本当のコンテンツを無視してグリーンランを取得することは、テストしないことと同じです。
4. 目視確認
チェッカーは測定可能な壊れ方を見つけます。測定できない問題もあります: 不格好な折り返し(ボタンに一語だけ残る)、グリッドの最後の項目が一つだけぽつんとある、1920px以上で巨大な空のガター、被写体が切れる画像のトリミング、技術的には問題ないが使いにくいメニューなど。実行で保存されたスクリーンショット(screens/320.png、375、768、1024、1440 と closeups/)を開いて見てください。画像を表示できない場合は、視覚的なレビューを行ったと主張するのではなく、その旨をレポートに記載してください。
ユーザーに視覚的な問題を報告するときは、要素をクラス名ではなく、何でどこにあるかで説明してください(「商品写真の価格バッジ」「メニューグリッドの2つめのカード」)。ユーザーはDOMセレクタを読みません。セレクタはコードを見つけるための自分のメモに残しておいてください。
5. 監査のみのリクエスト
ユーザーがサイトのチェックまたは監査(修正はしない)を依頼した場合は、まず完全なチェッカーを実行し、結果を重大度と幅範囲ごとにグループ化し、スクリーンショットを添えて報告してからコードに触れてください。範囲が大きい場合は、修正する前に確認を取ってください。
6. 検証内容をユーザーに伝える
最後に、簡潔で事実に基づくサマリーを記載します:
- 変更内容(ファイル、コンポーネント);
- テストしたもの: ページ、
N幅 320~1920px、横向きスマホ; チェッカー結果(0 エラー, 1 警告); - 残っている各警告とその理由;
- スクリーンショットの場所;
- 検証していないもの。チェッカーはChromiumのみを使用するため、Safari/Firefoxの癖、実機のキーボード、テキストのみの200%ズーム、RTL、ストレージステートなしのログインが必要なページは、別途テストしない限り対象外です。
参考ファイル
references/patterns.md: 一般的な構成要素に対する、コピーしてすぐ使えるモバイルファーストCSS。新しいレイアウトやコンポーネントを構築する際に読んでください。references/stacks.md: Tailwind、Bootstrap、SCSS、CSS Modules、CSS-in-JS、MUI/Chakra、Vue/Svelte/Angular、サーバーテンプレートでのモバイルファーストとブレークポイントの見え方、さらにそれぞれをチェッカー用に提供する方法。references/checks.md: 各チェッカー発見事項と、典型的な原因、修正方法、既知の誤検出。発見事項の原因が明らかでないときに読んでください。scripts/selftest/run_selftest.py: チェッカーが各バグタイプをまだ捕捉できることを証明します(14のフィクスチャ)。チェッカーを編集した後に実行してください。