responsive-craft

レスポンシブデザインの実践

すべての画面幅で機能するレスポンシブデザインを実装します。視覚的なキャンバスがないことを補うため、事前に意図的な判断を行います。

クイックスタート

既存のサイトを変換する： /responsive-craft audit または「レスポンシブにして」「モバイルレイアウトを修正して」 レスポンシブデザインをゼロから構築する： /responsive-craft build または「モバイルファーストで構築して」「レスポンシブレイアウトを作成して」 すべてのブレークポイントをプレビューする： /responsive-craft preview または「レスポンシブプレビューを表示して」「ブレークポイントのプレビューを開いて」

---

基本原則

1. 段階的な適用モデル — まず固有の CSS（auto-fit、flex-wrap、clamp()）を使い、次にコンテナークエリ（コンポーネントレベル）、最後にメディアクエリ（ページレベルのみ）を使います。よりシンプルな手法で解決できるなら、そこで止めます。

2. コードを書く前に説明する — キャンバスがないため、CSSを書く前にレスポンシブ時の動作を明示的に説明します。Adaptive モードでは、インラインの動作メモ（CSS コメント）を使います。Guided モードでは、正式な動作仕様（コンポーネントごとの表）を記述します。どちらも、キャンバスなら受動的に気づける設計上の判断を事前に把握できます。

3. 基本は流動的に、ブレークポイントは例外的に — タイポグラフィ、間隔、サイズには clamp() を使います。固定ブレークポイントは、ナビゲーションの変化、列数の切り替え、サイドバーの表示・非表示など、構造が変わる場合に限ります。

4. コンポーネントはコンテナーに適応させる — コンポーネントはビューポートではなく、コンテナーに応じて変化します。コンテナークエリを使います。サイドバー内のカードと全幅セクション内のカードには、同じ CSS を使うべきです。

5. 飛び飛びに確認せず、ドラッグしてテストする — DevTools で 280px から 2560px までゆっくりサイズを変更します。名前付きブレークポイントだけを確認するのではありません。これにより、途中のサイズで発生する問題を見つけられます。

6. スティッキー表示とスクロールには明示的なパターンが必要 — スティッキー要素の連携、z-index のスタッキングコンテキスト、オーバーフローの祖先要素、セーフエリア、仮想キーボードには注意が必要です。これらは気づかないうちに壊れることがあります。独自に対応せず、references/sticky-scroll-patterns.md のパターンを使います。

7. 設計上の分岐点を認識し、黙って既定の選択肢にしない — レスポンシブ対応に複数の妥当な方法がある場合は、トレードオフとともに 2～3 個の選択肢を提示し、ユーザーに選んでもらいます。references/responsive-design-forks.md を参照してください。

---

3 層のレスポンシブシステム

層	ツール	対応内容
連続的	clamp()、流動的なトークン、cqi 単位	フォントサイズ、パディング、間隔の滑らかな拡大・縮小
コンポーネント	コンテナークエリ（@container）	カードのレイアウト、ナビゲーション項目など、コンテキストへの適応
構造	メディアクエリ（@media）	グリッドの列数、ナビゲーションの変化、サイドバーなど、ページレベルでの変更

段階的適用の判断ツリー

Does this need to change layout?
  No  → clamp() for sizing. Done.
  Yes → Does it depend on CONTAINER size?
    Yes → Container query
    No  → Does it depend on VIEWPORT?
      Yes → Media query (page-level only)
      No  → :has() or intrinsic sizing (auto-fit, flex-wrap)

---

モードの選択

このスキルは 3 つのモードで動作します。$ARGUMENTS からモードを判定するか、ユーザーに確認します。

判定

• $ARGUMENTS に「preview」、「show breakpoints」、「live preview」が含まれる → プレビュー
• $ARGUMENTS に「audit」、「transform」、「fix」、「improve」、「retrofit」が含まれる → 既存サイトの変換
• $ARGUMENTS に「build」、「create」、「new」、「from scratch」が含まれる → レスポンシブデザインの構築
• 既存のコードベースでレスポンシブの問題に取り組んでいる → 既存サイトの変換
• 新しいページやコンポーネントを作成しようとしている → レスポンシブデザインの構築
• 判断できない → 質問する

AskUserQuestion が利用できる場合：

• 既存サイトを変換する — 現在のコードのレスポンシブ動作を確認して改善します
• ゼロから構築する — 最初からレスポンシブレイアウトを設計します
• プレビューする — ブラウザーで複数のブレークポイントのライブプレビューを起動します

それ以外の場合：「既存サイトのレスポンシブデザインを変換しますか、新しいものを構築しますか、それともプレビューのみを行いますか？」

インタラクティビティのレベル

プレビューモードではスキップ — すぐにルーティングに進みます。

モードを選択した後、インタラクティビティを決定します。

AskUserQuestion を利用できる場合：

• アダプティブ — すばやく進めます。探索のための質問を1～2個した後、作業を開始します。設計上の分岐が生じたら、その場で提示します。正式な仕様書は作成せず、判断はその都度行います。
• ガイド付き — 成果物を作成します。十分な探索を行い、コーディング前に各コンポーネントの動作仕様を書き、各段階の前に明示的な承認を得ます。複雑なレイアウトや、後から参照する仕様をユーザーが求めている場合に最適です。

利用できない場合は、次のように尋ねます。「（1）アダプティブ — すばやく進め、作業中に質問します、または（2）ガイド付き — コンポーネントごとに動作仕様を書き、コーディング前に承認を得ます。どちらにしますか？」

ユーザーが希望を示さない場合は、アダプティブを既定とします。

ガイド付きの推奨場面： レイアウトに5つ以上の異なるレスポンシブコンポーネントがある場合、複数のスティッキー要素がある場合、またはダッシュボード形式のレイアウトの場合は、ガイド付きの利用を提案します。動作仕様を用意することで、後から発生する大規模な手戻りを防げます。

---

ルーティング

モードとインタラクティビティを選択した後：

モード	ワークフローを読む	すぐに読み込む
プレビュー	workflows/preview.md	なし
既存のものを変換	workflows/transform-existing.md	references/ai-failure-patterns.md
レスポンシブに構築	workflows/build-responsive.md	references/modern-css-patterns.md、references/ai-failure-patterns.md

その他のリファレンスは必要に応じて読み込みます：

• references/sticky-scroll-patterns.md — スティッキー、スクロールスナップ、または独立したスクロール領域が関係する場合
• references/responsive-design-forks.md — 曖昧なレスポンシブ対応の分岐が見つかった場合
• references/testing-checklist.md — 検証手順の実行時
• references/modern-css-patterns.md — 変換モードで修正を実装する場合

---

注意点 — Claude がレスポンシブデザインで失敗するケース

よくある間違いを以下に示します。レスポンシブ対応の出力をすべて、このリストに照らして確認してください。

1. モバイルでの 100vh — vh のフォールバックを指定したうえで、svh／dvh を使用します。100vh はモバイルブラウザーの表示領域の背後にはみ出します。

2. デスクトップファーストのメディアクエリ — 常に max-width ではなく min-width（モバイルファースト）を使用します。モバイルでは上書きの読み込みが少なくなります。

3. Flex の子要素に min-width: 0 がない — Flex の min-width の既定値は auto（コンテンツのサイズ）です。長いテキストや画像がはみ出します。コンテンツが動的な場合は min-width: 0 を追加します。

4. overflow: hidden はスティッキーを無効にする — 祖先要素に overflow: hidden/scroll/auto があると、position: sticky が機能しなくなります。見た目だけを切り取る場合は overflow: clip を使用します。

5. transform は position: fixed を壊す — 祖先要素に transform があると、固定配置された子要素はビューポートではなく、その祖先要素を基準に配置されます。

6. iOS で16px未満の入力欄を使用するとズームする — 入力欄の font-size が16px未満だと、Safari でビューポートがズームされます。font-size: max(16px, 1rem) を使用します。

7. セーフエリアのインセットがない — ノッチのあるデバイスでは env(safe-area-inset-*) が必要です。メタタグに viewport-fit=cover を指定する必要があります。横向きの画面も忘れずに対応します。

8. z-index の値をむやみに大きくする — 9999 のような値は、スタッキングコンテキストの理解が不十分であることを示します。isolation: isolate と段階的な z-index のスケールを使用します。

9. Flex／Grid 内のスティッキー要素に align-self: start がない — これがないと、要素が高さ全体に引き伸ばされ、スティッキーとして固定される余地がなくなります。気づきにくいスティッキーの不具合のうち、最もよくある原因です。

10. 1つのビューポートだけに最適化する — 1440px で完璧に見えるコードでも、320px、768px の縦向き、ウルトラワイドでは崩れます。必ず全範囲でテストしてください。

コード例を含む完全なリストは、references/ai-failure-patterns.md を参照してください。

---

ツール

このスキルには、視覚的なレスポンシブ検証用の CLI ツールが scripts/ に2つ含まれています。

複数ビューポートのライブプレビュー

ブラウザーでホットリロードを使い、すべてのブレークポイントを同時に確認できます：

node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000
node ${CLAUDE_SKILL_DIR}/scripts/preview.js ./index.html
node ${CLAUDE_SKILL_DIR}/scripts/preview.js http://localhost:3000 --breakpoints 375,768,1024,1440,1920

レスポンシブスナップショット

各ブレークポイントでスクリーンショットを撮影します。変更前後の比較にも対応しています：

# Capture current state
node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000

# Capture baseline, make changes, then capture again for comparison
node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000 --before
# ... make responsive changes ...
node ${CLAUDE_SKILL_DIR}/scripts/snapshot.js http://localhost:3000
# → generates comparison.html with before/after at each breakpoint

どちらのツールも依存関係は不要で、Node.js だけで動作します。スナップショットの撮影には、ヘッドレススクリーンショット用の dev-browser が必要です。

---

リファレンス一覧

ファイル	内容	読み込むタイミング
modern-css-patterns.md	コンテナクエリ、clamp()、subgrid、:has()、ビューポート単位、スクロール駆動アニメーション、ネスト、@layer、論理プロパティ	レスポンシブ CSS を記述またはレビューするとき
sticky-scroll-patterns.md	スティッキー要素の連携、scroll-snap、独立したスクロール領域、レスポンシブなデータテーブル、モーダル／シート、IntersectionObserver	スティッキー、スクロール、または複雑なレイアウトパターンに取り組むとき
responsive-design-forks.md	選択肢とトレードオフを含む、デスクトップからモバイルへの曖昧な変換例 8 件	レスポンシブな変換に唯一の正解がないとき
ai-failure-patterns.md	AI によるレスポンシブ対応の失敗パターン 13 種類。良い例・悪い例のコード、出力前スキャンのチェックリスト	レスポンシブコードを出力する前のスキャン
testing-checklist.md	優先ビューポート、10 項目のチェック、エッジケース、3 段階のテスト戦略、Playwright のパターン	実装後の検証

ワークフロー一覧

ワークフロー	目的
transform-existing.md	監査 → 分岐点の特定 → 優先順位に沿ってレスポンシブの問題を修正
build-responsive.md	動作の説明 → 基盤の確立 → モバイルファーストで構築 → 検証
preview.md	ブラウザーで複数のブレークポイントのライブプレビューを起動