Communityコーディング&開発github.com

レスポンシブWeb: モバイルファースト、任意のスタック、検証済み

レスポンシブWebスキル。320pxのスマホから2560pxのモニタまで、あらゆる画面幅で崩れないUIをモバイルファーストで構築・検証します。プレーンCSS、Tailwind、Bootstrap、SCSS、CSSモジュール、CSS-in-JS、React/Vue/Svelte/Angular、サーバーサイドレンダリングテンプレートなど、あらゆるスタックに対応。150以上の幅と横向きスマホを網羅し、横スクロール、テキストの切れ・重なり、タップターゲットの隠れ・小ささ、画像の伸び、viewportメタの欠落などを実測するPlaywrightチェッカーを同梱。

レスポンシブWeb: モバイルファースト、任意のスタック、検証済み とは?

このスキルは、あらゆる画面幅で崩れないレスポンシブなWeb UIを構築し、自動検証するためのものです。「モバイルファースト」で書き、`scripts/check_responsive.py` というPlaywrightベースのチェッカーで150以上の幅と横向きスマホを実測します。チェッカーはDOMのボックスと算出スタイルのみを見るため、CSSの書き方(Tailwind、Bootstrap、CSS Modules、CSS-in-JS、React/Vue/Svelte/Angular、サーバーテンプレートなど)に依存せず、あらゆるスタックで使えます。横スクロール、テキストの切れ・重なり、小さすぎるタップターゲット、伸びた画像、viewportメタの欠落など、実際のレイアウト破損をエラーとして報告し、修正ループをガイドします。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/isikenes35/responsive-web/tree/HEAD

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

レスポンシブWeb: モバイルファースト、任意のスタック、検証済み は何をしますか?

目標は、誰かが選んだ5つのデバイス幅だけでなく、あらゆる幅で動作するレイアウトです。 バグはその間、例えば412px、905px、max-width: 767px と min-width: 769px の両方が適用されなくなる1ピクセルに潜んでいます。そのため、このスキルは常にセットで使用する2つの部分から成ります。

  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-viewportviewport 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. 修正ループ

  1. 最初に最も小さい幅で失敗している箇所を修正します。モバイルが基盤であり、それを修正することで残りも修正されることがよくあります。
  2. 手がかりが示す根本原因を、プロジェクトが使用するソース(Tailwindクラス、SCSSパーシャル、styled component)で修正し、一回限りのオーバーライドでは修正しないでください。references/checks.md に各チェックの原因と修正方法がリストされています。
  3. 再実行(--quick)、繰り返し、その後完全な実行を行います。エラーが0になり、すべての警告が修正されるか理由が説明されるまで続けます。
  4. 意図的にルールを破るもの(画面からはみ出す装飾的なシェイプ、ヒーローコラージュでの意図的な重なり)がある場合は、その要素に 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のフィクスチャ)。チェッカーを編集した後に実行してください。

関連スキル