Communitygithub.com

モバイルでネイティブ感を実現

Webアプリをモバイルでネイティブアプリのように感じさせるためのCSSとメタタグの修正をまとめたスキルです。

モバイルでネイティブ感を実現 とは?

このスキルは、Webアプリがモバイルブラウザ上で「ただのWebサイト」ではなく、「インストールされたアプリ」のように振る舞うために必要な、細やかな修正を提供します。デスクトップでは再現しないが実機でのみ発生する、スクロールのジャック、タップの遅延、ホバーステートの固着、セーフエリアの問題など、11の一般的なモバイルUIの課題を解決します。各修正には理由が明記されており、開発者は「なぜその修正が必要か」を理解した上で適用できます。Chromeのデベロッパーツールのデバイスエミュレーションでは再現できないバグに対処するため、実機テストの重要性を強調している点が特徴です。このスキルは、`animate`(モーション設計)や`animate-expo`(React Native向け)とは異なり、ビューポート、タッチ、スクロール、セーフエリアといったプラットフォームレイヤーに特化しています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CharbelElBateh/personal-website/tree/HEAD/.claude/skills/mobile-native

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

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

ドキュメント

モバイルでネイティブ感を実現 は何をしますか?

初期応答

このスキルが初めて呼び出され、特定の質問がない場合、以下のみを応答してください:

私はあなたのWebアプリをモバイルでネイティブのように感じさせる準備ができています。私の知識はEmil Kowalskiのデザインエンジニアリング哲学に基づいています。

ユーザーが質問するまで、これ以上の情報は提供しないでください。

これは修正スキルです。ただ一つのことを行います:電話画面上でWebサイトのように感じられるWebアプリから、その兆候を一つずつ取り除きます。モーションの設計(animate)、モーションのレビュー(review-animations)、React Native向けの構築(animate-expo)は行いません。ここでのルールはプラットフォームレイヤー(ビューポート、タッチ、スクロール、セーフエリア、ブラウザのクローム)に関するものです。わずかなコード行で、アプリが「インストールされている」ように感じられるか、「埋め込まれている」ように感じられるかが決まります。

運用姿勢

あなたは、実際のスマートフォンにドロワー、シート、ジェスチャー駆動のUIをリリースし、以下のすべての項目で痛い目にあったことのあるシニアデザインエンジニアです。デスクトップブラウザでデバイスツールバーをオンにしたものはスマートフォンではないことを知っています。また、「アプリがモバイルでカクつく」という報告のほとんどがアニメーションの問題ではなく、300msのタップ遅延、タップ時の灰色のフラッシュ、または離れないホバーステートであることも知っています。

ユーザーの電話が唯一の真実です。ハードウェアで実行できない場合は、以下の修正のうちどれをコードで検証でき、どれが実機を必要とするかを伝えてください。

2つの失敗モードがありますが、最初の方がより深刻です:

  1. デスクトップで見えるものを修正すること。 このスキルにあるバグはChromeのデバイスエミュレーションでは再現しません。そこでしかテストしなければ、これらすべてを出荷することになります。
  2. CSSやメタタグでできることにJavaScriptに頼ること。 ここにあるほとんどすべての項目は、たった一つの宣言で済みます。ホバーステートを隠すためのuseIsTouchDevice()フックは間違ったツールです。メディアクエリが正しいツールです。

厳格なルール

  1. すべての修正は理由と共に出荷されます。 以下の各ルールには理由があります。その理由が当てはまる場所にのみ適用し、習慣でグローバルに適用しないでください。ボディテキストへのuser-select: noneは欠陥ですが、ボタンへの適用は正しいです。
  2. デバイス検出よりもメディアクエリ。 (hover: hover)、(pointer: fine)、env()、dvh — プラットフォームが何ができるかを教えてくれます。タッチを推測するためにユーザーエージェント文字列や画面幅で分岐しないでください。
  3. タッチとマウスは排他的ではありません。 トラックパッド付きのiPad、タッチスクリーン付きのノートパソコン、マウス付きのスマートフォン。両方同時に書くこと。デバイスではなく、機能でゲートを設けてください。
  4. ズームを無効にしないでください。 user-scalable=noとmaximum-scale=1はアクセシビリティの失敗です。代わりに、ズームの原因となっている入力フォントサイズを修正してください。
  5. ハードウェアでテストしてから完了と呼んでください。 電話を接続し、IPで開発サーバーを開き、SafariのWeb InspectorまたはChromeのリモートデバッグを使用してください。エミュレーションでは、スティッキーホバー、タップ遅延、ラバーバンディング、セーフエリア、キーボードを再現できません。

症状テーブル

ここから始めてください。ユーザーが見ているものに一致させ、対応するセクションを読んで理由と正確なコードを確認してください。

問題解決策
タップ後にホバーステートが固着@media (hover: hover) and (pointer: fine) でラップ
タップ時に灰色/青色のフラッシュ-webkit-tap-highlight-color を削除
レイアウトの高さが間違っている100dvh(アプリ)または 100svh(ヒーロー)
入力にフォーカスするとページがズーム入力フォントサイズを最低16pxに
タップが遅く感じられるポインターダウンのフィードバック + touch-action: manipulation
プル・トゥ・リフレッシュがスクロールを乗っ取るhtml, body に overscroll-behavior: none
ノッチでコンテンツが途切れるviewport-fit=cover + env(safe-area-inset-*)
長押しでボタンテキストが選択されるuser-select: none を追加
カルーセルが縦にスクロールジェスチャー面に touch-action: pan-y
ステータスバーの色が合わないカラースキームごとに theme-color
Chromeでは正しいが電話では間違っている実際のハードウェアでテスト

修正

1. タップ後にホバーステートが固着

タッチにはホバーがないため、ブラウザはそれを偽装します:要素への最初のタップで:hoverが適用され、ユーザーが別の場所をタップするまでそのまま残ります。ホバー時に拡大するボタンは、タップされた後も拡大されたままです。すべてのホバースタイルを機能クエリの背後にゲートしてください。

@media (hover: hover) and (pointer: fine) {
  .button:hover {
    background: var(--gray-3);
    transform: scale(1.02);
  }
}

両方の条件が重要です。(hover: hover)は、プライマリ入力がホバーできることを意味します。(pointer: fine)は、マウスのように精密であることを意味し、スタイラスやホバーサポートを主張する奇妙なAndroidデバイスを排除します。Tailwind v4ではhover:バリアントがすでに@media (hover: hover)にコンパイルされます。v3ではfuture.hoverOnlyWhenSupportedを設定してください。

タッチユーザーにはまだプレスフィードバックが必要です。すべての入力タイプで動作する:active(§5参照)でそれを与えてください。

2. タップ時に灰色/青色のフラッシュ

iOS SafariとAndroid Chromeは、クリックハンドラーを持つタップされた要素の上に半透明のハイライトをペイントします。これは「これはWebサイトです」という最大のシグナルであり、あなたがデザインしたプレスフィードバックと競合します。

html {
  -webkit-tap-highlight-color: transparent;
}

一度、グローバルに設定してください。その後、すべてのタップ可能な要素が独自の:active状態を持つことを確認してください。ブラウザが与えていた唯一のフィードバックを削除したからです。

3. レイアウトの高さが間違っている

モバイルでの100vhは最大のビューポート、つまりブラウザのクロームが折りたたまれたときの高さです。ページ読み込み時にはURLバーが表示されているため、100vhの要素はそのバーの高さだけあふれ、下部に固定されたボタンはその下に座ります。代わりに動的ユニットと小ユニットを使用してください:

/* アプリシェル、ドロワー、クロームの表示/非表示に応じて表示領域を追跡するもの */
.app { height: 100dvh; }

/* ヒーローと最初の画面 — ビューポートが最も小さくなるため、何も切り取られない */
.hero { min-height: 100svh; }

dvhはURLバーが折りたたまれるとリサイズされます。これはアプリシェルには正しいですが、マーケティングコンテンツではスクロール中にレイアウトシフトを引き起こします。svhは安定しており、あふれることがないため、ヒーローには適切です。lvhは古いvhであり、ほとんど必要ありません。プロジェクトのサポートマトリックスが要求する場合にのみ、古いブラウザ向けに上に100vhのフォールバック行を残してください。

4. 入力にフォーカスするとページがズーム

iOS Safariは、フォントサイズが16px未満の入力にフォーカスが当たるとページをズームし、ブラーしてもズームを戻しません。ユーザーは切り取られ、ずれたレイアウトを見ることになります。これが人々がmaximum-scale=1に手を出す理由ですが、それは間違った修正です(厳格なルール4)。

input, textarea, select {
  font-size: 16px; /* 最小値。デフォルトのルートサイズで1rem */
}

デスクトップの入力でより小さいテキストがデザイン上必要な場合は、それが重要になる場所だけでスケールアップしてください:

@media (pointer: coarse) {
  input, textarea, select { font-size: 16px; }
}

入力にいる間に、キーボードも設定してください:コードにはinputmode="numeric"、金額にはinputmode="decimal"、それぞれのフィールドにはtype="email"とtype="tel"、ユーザー名とコードにはautocapitalize="none"とautocorrect="off"、リターンキーに動作を表示するためにenterkeyhint="send" / "search" / "done"。

5. タップが遅く感じられる

ここでは2つの異なる原因が重なっています。

300msのクリック遅延。 ブラウザはタップ後、別のタップが来るかどうかを確認するために待機します。これはダブルタップズームのためです。モダンブラウザはビューポートがwidth=device-widthの場合は待機をスキップしますが、すべての場合ではありません(iOS Safariは一部の要素でまだ遅延します)。touch-action: manipulationは、この要素がダブルタップズームを決して行わないことをブラウザに伝え、clickを即座に発生させます:

button, a, [role="button"], .tappable {
  touch-action: manipulation;
}

リリース時のフィードバック、プレスの代わりに。 ネイティブボタンは指が着地した瞬間に応答します。clickでのみ変化するWebボタンは、指が離れたときに応答し、0msでも遅延として読み取られます。:activeをスタイル設定し、JavaScriptが必要な場合は、clickではなくpointerdownをリッスンしてください:

.button {
  transition: transform 100ms var(--ease-out), background 100ms;
}
.button:active {
  transform: scale(0.97);
  background: var(--gray-4);
}

プレスフィードバックは100〜160ms、ease-outに保ってください。コードベースがanimateスキルのトークンを使用している場合は、それらを使用してください。新しいカーブをフォークしないでください。

6. プル・トゥ・リフレッシュがスクロールを乗っ取る

ページの先頭を超えてスクロールすると、Android Chromeではプル・トゥ・リフレッシュが、iOSではページ全体のラバーバンドがトリガーされます。ドキュメントでは問題ありません。独自のスクロールコンテナ、ユーザーが下にドラッグするドロワー、またはキャンバスがあるアプリでは間違っています。

html, body {
  overscroll-behavior: none;
}

次に、内部のスクロール可能な要素(シートのコンテンツ、チャットリスト、サイドバー)で、スクロールが端に達したときにページに連鎖するのを防ぎます:

.sheet-content {
  overflow-y: auto;
  overscroll-behavior: contain;
}

containはコンテナ自体のバウンス(ネイティブに感じられる)を維持しますが、背後にあるページが動くのを防ぎます。ルートにはnone、子要素にはcontainを使用してください。このためにtouchmove + preventDefault()リスナーに決して手を出さないでください。スクロールを完全にブロックし、リスナーを非パッシブにしてフレームを犠牲にします。

7. ノッチでコンテンツが途切れる

デフォルトでは、ブラウザはあなたのページをセーフエリア内にレターボックス化し、ノッチ、Dynamic Island、ホームインジケーターゾーンをボディの背景色のままにします。ネイティブアプリは端から端までペイントし、そのコンテンツをこれらのゾーンからパディングで遠ざけます。2つのステップ:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
.app-header {
  padding-top: env(safe-area-inset-top);
}
.bottom-bar {
  padding-bottom: env(safe-area-inset-bottom);
}
.sheet {
  padding-bottom: calc(1rem + env(safe-area-inset-bottom));
}

viewport-fit=coverはページをノッチの下に広げます。env(safe-area-inset-*)は、パディングで戻すためのインセットを提供します。メタタグがないと、env()の値はすべて0pxになります。固定ヘッダー、下部タブバー、トースト、シートがこれを必要とする要素です。通常のページコンテンツは、通常ヘッダーのパディングを通じて無料でそれを取得します。calcで値が使用される場合は、env()にフォールバック(env(safe-area-inset-bottom, 0px))を与えてください。

8. 長押しでボタンテキストが選択される

Webボタンに指を置いたままにすると、iOSはそのラベルを選択するか、リンクでコピー/共有のコールアウトをポップアップ表示します。ネイティブコントロールは決してそれをしません。コントロールであるテキストは選択可能であってはなりません。コンテンツであるテキストは選択可能のままでなければなりません。

button, [role="button"], .tab, .chip, .drag-handle {
  user-select: none;
  -webkit-user-select: none;   /* Safariはまだプレフィックスが必要 */
  -webkit-touch-callout: none; /* コントロールとして使用されるリンク/画像で長押しコールアウトを表示しない */
}

bodyにuser-select: noneを絶対に設定しないでください。ユーザーはアドレス、エラーメッセージ、注文番号をコピーします。それらはコンテンツです。

9. カルーセルが縦にスクロールする

カルーセルでの水平スワイプはブラウザにとって曖昧です。ページをスクロールしているのかトラックをスクロールしているのかわからないため、推測します。その推測は、カルーセルが動いている間にページが上下にジッターすることがよくあります。要素がどの軸を所有するかを伝えてください:

.carousel {
  touch-action: pan-y; /* カルーセルは水平を処理。ブラウザは垂直を保持 */
}
.drag-surface {
  touch-action: none;  /* カスタムジェスチャー(ドラッグで閉じるシート、スライダー)がすべての軸を所有 */
}
.vertical-sheet-handle {
  touch-action: pan-x; /* シートは垂直ドラッグを処理。水平はブラウザに残る */
}

値は、ブラウザがまだ実行できることを示します。水平カルーセルでのpan-yは、「ブラウザよ、垂直パンはあなたが維持する。水平は私が処理する」という意味です。noneは要素がすべてを処理することを意味します — 本当にそうする要素にのみ使用してください。そうしないと、ユーザーはそれらをスクロールして通過できなくなります。

カルーセルがJSジェスチャーではなくネイティブスクロールの場合は、トラックにscroll-snap-type: x mandatory、スライドにscroll-snap-align: startを優先してください。ブラウザ自身の物理法則が手作りのスプリングに勝り、touch-actionは不要になります。

10. ステータスバーの色が合わない

ステータスバーとブラウザのクロームはtheme-colorから色を取得します。一つの値は、ライトモードでダークバー、またはダークモードで白いバーを意味します。各カラースキームに独自のものを与えてください:

<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a" />
<meta name="color-scheme" content="light dark" />

値をページの最上部の色(ブランドカラーではなく、ヘッダーの背景色)に一致させてください。Next.jsではviewportエクスポート(themeColor: [{ media, color }])で設定します。アプリがOS設定ではなくクラスでテーマを切り替える場合は、トグル時にJavaScriptからタグを更新してください。インストールされたPWAの場合、apple-mobile-web-app-status-bar-styleとマニフェストのtheme_color/background_colorは同じ決定です。

11. Chromeでは正しいが電話では間違っている

上記のどれもデバイスエミュレーションでは再現しません。スティッキーホバー、タップハイライト、URLバーのvhへの影響、入力ズーム、クリック遅延、オーバースクロール、セーフエリア、ソフトウェアキーボード — すべてが実際のハードウェアの動作です。

  • 電話をUSBで接続し、0.0.0.0で開発サーバーを実行し、マシンのLAN IPで開いてください。
  • iOS: Safari → 現像 → デバイス。Android: chrome://inspect。
  • 机の上の最新の電話ではなく、数年前の電話でテストしてください。キーボードを開いてテストしてください。一度は横向きでテストしてください。
  • それがターゲットであれば、インストールされたPWAとしてテストしてください。スタンドアロンモードはビューポート、セーフエリア、ステータスバーの動作を変更します。

Xcodeシミュレーターはエミュレーションよりはましですが、それでもタッチの感触を逃します。実際のハードウェアが基準です。

ベースライン

モバイル向けアプリを始めるとき、これが最低限です。最初のコンポーネントの前にこれを出荷してください:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a" />
html {
  -webkit-tap-highlight-color: transparent;
  -webkit-text-size-adjust: 100%; /* 横向きでフォントが膨張しない */
  overscroll-behavior: none;
}

input, textarea, select {
  font-size: 16px;
}

button, a, [role="button"], .tappable {
  touch-action: manipulation;
}

button, [role="button"], .tab, .chip, .drag-handle {
  user-select: none;
  -webkit-user-select: none;
  -webkit-touch-callout: none;
}

.carousel, [data-gesture-horizontal] {
  touch-action: pan-y;
}

下部の2つのルールはセマンティッククラスを使用しています。データ属性をオプトインとして使用すると、フレームワークに依存せず、予想外の要素にtouch-actionを適用しません。

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

CharbelElBateh/personal-website

Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.

CharbelElBateh/personal-website

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.

CharbelElBateh/personal-website

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

CharbelElBateh/personal-website

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

CharbelElBateh/personal-website

Guide to Sonner, the React toast library — install and wire up the Toaster, pick the right toast() call, promise and loading toasts, updating, dismissing and persisting toasts, styling, theming and icons, positioning and multiple toasters. Use when working with Sonner or troubleshooting it — toasts that don't appear, appear twice, lose their styles, ignore Tailwind classes, sit behind a modal, or don't follow dark mode.

CharbelElBateh/personal-website

Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion use review-animations.

CharbelElBateh/personal-website

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

CharbelElBateh/personal-website

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

CharbelElBateh/personal-website

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

CharbelElBateh/personal-website

Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

CharbelElBateh/personal-website

How to write modern Swift well — modeling with value types, Swift 6 data-race safety and approachable concurrency (@concurrent, main-actor-by-default, actors, task groups), protocols and generics (some vs any), API design, performance and ARC, Swift Testing, macros, and the modern language features agents don't know about yet. Use when writing, reviewing, or migrating Swift, or when a concurrency error, a hang, a data race, a retain cycle, or a performance problem needs fixing.

関連スキル