thumb-first-platform

Thumb-First · Platform

thumb-first スイートの技術検証レイヤーです。thumb-first-design がモバイルデザインのあるべき姿（プラットフォームに依存しない判断）を決めるのに対し、このスキルでは実際のデバイスで実装が適切に機能するかを検証します。ファイル名と行番号を示して客観的な問題を特定し、修正案を重大度別に評価します。

デザインとプラットフォームをまとめてレビューするには /thumb-first を実行してください。技術的なチェックだけを行う場合は、このスキルを直接使用してください。

---

ステップ 0 · 対象を特定する（最初に実施）

Web/PWA とネイティブアプリでは、該当する問題がまったく異なります。ほかの作業を始める前に対象を特定してください。

リポジトリを確認する：

• Web / PWA → next.config.*、vite.config.*、index.html、Web アプリの manifest.json/manifest.webmanifest、サービスワーカー、Tailwind/CSS。このスキルの担当範囲です。以下の原則と振り分けに進んでください。
• ネイティブ → package.json にある react-native/expo、app.json/app.config.*（Expo）、ios/+android/ の組み合わせ、*.xcodeproj/Package.swift/*.swift（SwiftUI/UIKit）、または pubspec.yaml（Flutter）。
• 判別できない、または両方（例：Web ターゲットもある Expo アプリ）→ どのターゲットを監査するか確認してください。

ターゲットがネイティブの場合、Web 監査を装ってはいけません。 このスキルのチェック項目（Safari の挙動、ビューポート単位、サービスワーカー、Web マニフェスト）は適用されません。代わりに：

1. 導入済みのネイティブスキルがあるか確認して、引き継げるものを探してください。 利用可能なスキルや ~/.claude/skills/ を調べ、React Native、Expo、SwiftUI、ネイティブ iOS/Android、Flutter に関するものを探します（例：react-native-design、building-native-ui、vercel-react-native-skills）。
2. 見つかった場合は引き継いでください。 スキル名を明示します。「ネイティブの技術チェックには、<skill> を使用してください。ネイティブのパフォーマンス、リスト、プラットフォーム API を対象としています。」と伝えてください。thumb-first-design はプラットフォームに依存しないため、ネイティブアプリのデザイン判断も引き続き対象となることを明記します。
3. 見つからない場合は、その旨を率直に伝えてください。対応範囲を超えてはいけません。

   thumb-first-platform が対象とするのは、thumb-first-design によるモバイルのデザイン判断と、Web/PWA の技術的な問題です。ネイティブプラットフォーム（React Native / SwiftUI / Flutter）のパフォーマンス監査や技術監査には対応していません。これらを行うには、ネイティブ専用のスキルをインストールするか、Xcode Instruments、Android Studio Profiler、Flipper、React Native パフォーマンスモニターなどのプラットフォーム標準ツールを使用してください。

デザインレイヤーはすべてのターゲットに適用されます。この技術レイヤーは Web/PWA に詳しく、ネイティブについては把握したうえで適切なスキルに引き継ぎます。この境界を明確にしてください。

---

モバイル Web と PWA — 基本原則

1. iOS Safari は特に問題が多い

ほとんどの特異な挙動や制限はここにあります。実際の iOS デバイスで必ずテストしてください。シミュレーターでは重要な挙動を見落とします。特に注意する点：

• PWA のインストールには Safari が必要です（ホーム画面に追加）。
• プッシュ通知が機能するのは、ホーム画面にインストールした場合のみです（iOS 16.4 以降）。
• インストールされていない Web アプリではストレージが 7 日で制限されます。キャッシュの上限は 50MB で、バックグラウンド同期はできません。
• 描画エンジンは WebKit のみです（iOS 上の Chrome も WebKit を使用します）。

2. ビューポート単位は重要

モバイルの全高レイアウトには 100vh を使用しないでください。ブラウザーの UI により、コンテンツがはみ出します。

.hero  { height: 100vh; height: 100svh; }  /* svh for static elements (90% of cases) */
.menu  { height: 100dvh; }                 /* dvh only for elements that should resize */

dvh はレイアウトシフトを引き起こすため、使用は控えめにしてください。

3. セーフエリアのインセットは必須

ノッチ、Dynamic Island、ホームインジケーターはあらゆる場所にあります。

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">

.header     { padding-top: max(1rem, env(safe-area-inset-top)); }
.bottom-nav { padding-bottom: max(1rem, env(safe-area-inset-bottom)); }

4. タッチターゲットは 44px 以上

Apple HIG では 44×44pt 以上、Google では 48×48dp 以上を推奨しています。タップ対象をこれより小さくしてはいけません。

5. 実機でテストする

Chrome DevTools のエミュレーションでは、アドレスバーの挙動、セーフエリアのインセット、タッチ遅延の細かな違い、iOS Safari の CSS の不具合、実際のモバイル端末のパフォーマンスが再現されません。実機、または BrowserStack/Sauce Labs を使用してください。

インテイクと振り分け

何をしたいですか？

1. 既存のモバイルアプリ／PWA の問題を監査する
2. iOS Safari 固有の問題を修正する
3. PWA をセットアップする（マニフェスト、サービスワーカー、アイコン）
4. モバイルのパフォーマンスを最適化する（Core Web Vitals）
5. タッチ／ジェスチャーの問題をデバッグする
6. プッシュ通知をセットアップする
7. モバイルの互換性をテストする

回答を待ってから、該当するワークフローを読み、その手順に従ってください。

回答	ワークフロー／リファレンス
1 · 「監査」「確認」「レビュー」「問題」	workflows/audit-mobile-pwa.md
2 · 「ios」「safari」「iphone」「apple」	workflows/fix-ios-issues.md
3 · 「pwa」「manifest」「service worker」「install」	workflows/setup-pwa.md
4 · 「パフォーマンス」「遅い」「vitals」「lcp」「cls」	workflows/optimize-performance.md
5 · 「タッチ」「ジェスチャー」「タップ」「スワイプ」「スクロール」	references/touch-interactions.md を読み、その後修正します
6 · 「プッシュ」「通知」「vapid」	references/push-notifications.md を読み、その後実装します
7 · 「テスト」「デバッグ」「エミュレート」	workflows/test-mobile.md

意図に基づく振り分け（具体的な問題が記述されている場合）：

• 「100vh が機能しない」「viewport」「高さの問題」「ノッチ」「セーフエリア」「ダイナミックアイランド」→ references/viewport-layout.md
• 「画像が大きすぎる」「画像の読み込みが遅い」→ references/image-optimization.md
• 「ラバーバンド」「バウンススクロール」→ references/ios-safari-quirks.md

/thumb-first 経由で実行する場合： 包括的なワークフローから呼び出されるのは audit のパスのみです（workflows/audit-mobile-pwa.md）。その不具合を統合レポートに反映します。セットアップ／プッシュ／パフォーマンスのワークフローは構築タスクです。個別に呼び出せば利用できますが、ワンストップレビューの対象外です。

---

検証ループ — 変更のたびに実施

1. ビルドは成功しますか？ pnpm build
2. Lighthouse 監査を実施しますか？ Chrome DevTools → Lighthouse → Mobile + PWA
3. 実機の iOS デバイスを使いますか？ Safari Web Inspector、または ngrok／localtunnel
4. セーフエリアに対応していますか？ ノッチの有無それぞれで、縦向きと横向きを確認します

調査結果は次の形式で報告します：ビルド：✓ · Lighthouse PWA：X/100 · iOS Safari：[具体的な問題]。

---

リファレンス一覧

すべて references/ 内にあります：

ファイル	内容
ios-safari-quirks.md	iOS Safari の不具合、CSS の回避策、制限事項
android-pwa.md	Android Chrome の PWA 動作、WebAPK
viewport-layout.md	100vh の問題、dvh/svh/lvh、セーフエリアのインセット
pwa-manifest.md	manifest.json、アイコン、スプラッシュ画面
service-workers.md	キャッシュ戦略、オフライン対応、Next.js との統合
push-notifications.md	Web プッシュ、VAPID、iOS と Android の違い
touch-interactions.md	300ms の遅延、touch-action、ジェスチャー
performance.md	Core Web Vitals（LCP/INP/CLS）、モバイルの最適化
image-optimization.md	Next.js Image、レスポンシブ画像、WebP/AVIF
responsive-patterns.md	よくある間違い、アンチパターン
testing-debugging.md	Lighthouse、テストツール、iOS のデバッグ

ワークフロー一覧

ファイル	目的
audit-mobile-pwa.md	モバイルアプリ／PWA の包括的な監査（/thumb-first が呼び出すパス）
fix-ios-issues.md	iOS Safari 固有の問題を修正する
setup-pwa.md	PWA をゼロから設定する
optimize-performance.md	Core Web Vitals を改善する
test-mobile.md	テスト手順

---

よくある問題と簡単な修正方法

/* 100vh overflow on mobile */     height: 100svh;            /* or min-height */
/* 300ms tap delay */              button, a { touch-action: manipulation; }
/* rubber-band scroll */           html { overscroll-behavior: none; }

            <meta name="viewport" content="..., viewport-fit=cover">
             <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

PWA をインストールできない場合： 有効な manifest.json · HTTPS · サービスワーカーの登録 · 192×192 と 512×512 のアイコンを含める。