Communitygithub.com

CharbelElBateh/personal-website

讓網頁應用在手機上感覺像原生應用——那些微小的 CSS 和 meta 標籤修正,能將「瀏覽器中的網站」與「已安裝的 App」區分開來。

personal-website 是什麼?

這是一個專門用於修復行動端網頁體驗的 AI 技能,旨在消除讓網頁看起來不像原生應用的各種「線索」。它涵蓋了從黏滯的 hover 狀態、點擊閃爍、100vh 高度錯誤、輸入框放大頁面,到觸控延遲、下拉刷新劫持捲動、內容被瀏海遮擋、長按選取按鈕文字、輪播捲動方向錯誤、狀態列顏色不匹配等 11 個常見問題。每個問題都附有精確的 CSS 或 HTML 解法,並強調使用媒體查詢(如 `(hover: hover)`)而非設備嗅探,以及禁止停用縮放等無障礙原則。此技能特別適用於建構 PWA、底部抽屜、輪播、全螢幕版面或任何觸控互動的場景,並且要求最終必須在真實硬體上測試,因為這些 bug 無法在 Chrome 的設備模擬中重現。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

在行動裝置上感覺像原生應用

初始回應

當此技能首次被調用但沒有特定問題時,僅回覆:

我已準備好讓你的網頁應用在行動裝置上感覺像原生應用,我的知識來自 Emil Kowalski 的設計工程理念。

在使用者提問之前,請勿提供任何其他資訊。

這是一個「修復型」技能。它只做一件事:讓一個在手機上看起來像網站的網頁應用,逐一消除那些暴露它身份的線索。它不處理動畫設計(那是 animate 的範疇)、不審查動畫(那是 review-animations 的範疇)、也不為 React Native 建構(那是 animate-expo 的範疇)。這裡的規則都關於平台層——視口、觸控、捲動、安全區域、瀏覽器 chrome——也就是那幾行程式碼決定應用感覺是「已安裝」還是「嵌入」的地方。

操作姿態

你是一位資深設計工程師,曾將抽屜、表單和手勢驅動的 UI 實際交付到真實手機上,並被以下每個項目都狠狠教訓過。你知道開啟了設備工具列的桌上型瀏覽器不等於手機。你知道大多數「應用在行動裝置上感覺卡頓」的報告都不是動畫問題——而是 300ms 的點擊延遲、點擊瞬間的灰色閃爍,或是揮之不去的 hover 狀態。

使用者的手機是真相的來源。如果你無法在硬體上執行,請說明以下哪些修正你可以從程式碼中驗證,哪些需要真實設備才能確認。

有兩種失敗模式,第一種更嚴重:

  1. 修復桌面顯示給你看的東西。 此技能中的 bug 在 Chrome 的設備模擬中無法重現。如果你只在該環境中測試,你會把所有 bug 都發佈出去。
  2. 在 CSS 或 meta 標籤就能解決時,改用 JavaScript。 這裡的幾乎每個項目都是一行宣告即可。用一個 useIsTouchDevice() 鉤子來隱藏 hover 狀態是錯誤的工具;使用媒體查詢才是正確的。

嚴格規則

  1. 每個修正都必須附上原因。 下面的每個規則都包含一個為什麼。只在該原因適用的地方應用它,而不是出於習慣全域套用——在 body 文字上使用 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 遠端除錯。模擬無法重現黏滯 hover、點擊延遲、橡皮筋效應、安全區域或鍵盤。

症狀對照表

從這裡開始。比對使用者看到的問題,然後閱讀對應章節了解原因和確切程式碼。

問題解決方案
點擊後 hover 狀態卡住包裹在 @media (hover: hover) and (pointer: fine) 內
點擊時出現灰色/藍色閃爍移除 -webkit-tap-highlight-color
版面高度錯誤使用 100dvh(應用)或 100svh(首屏)
頁面會放大到輸入框輸入框字型大小至少設為 16px
點擊感覺遲鈍在 pointer-down 時提供回饋 + 使用 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 狀態卡住

觸控沒有 hover,因此瀏覽器偽造了一個:第一次點擊元素時套用 :hover 並保持該狀態,直到使用者點擊其他地方。一個在 hover 時放大的按鈕,在點擊後會保持放大狀態。將每個 hover 樣式都設定在能力查詢之後。

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

兩個條件都重要。(hover: hover) 表示主要輸入裝置可以 hover。(pointer: fine) 表示它是精確的,例如滑鼠——它排除了觸控筆和那些聲稱支援 hover 的奇怪 Android 設備。在 Tailwind v4 中,hover: 變體已編譯為 @media (hover: hover);在 v3 中設定 future.hoverOnlyWhenSupported。

觸控使用者仍然需要按壓回饋。透過 :active(參見 §5)提供給他們,這在所有輸入類型上都有效。

2. 點擊時出現灰色/藍色閃爍

iOS Safari 和 Android Chrome 會在帶有點擊處理器的任何點擊元素上繪製一個半透明的反白。這是「這是一個網站」最明顯的信號,而且它會與你設計的任何按壓回饋產生衝突。

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

全域設定一次。然後確保每個可點擊元素都有自己的 :active 狀態,因為你剛剛移除了瀏覽器提供的唯一回饋。

3. 版面高度錯誤

行動裝置上的 100vh 是最大的視口——也就是瀏覽器 chrome 收合時的高度。頁面載入時,網址列是可見的,因此 100vh 元素會超出該列的高度,而底部固定的按鈕會位於它下方。改用動態和小型單位:

/* 應用外殼、抽屜,以及任何應隨著 chrome 顯示/隱藏而追蹤可視區域的元素 */
.app { height: 100dvh; }

/* 首屏和第一畫面——視口的最小值,確保沒有任何東西被切掉 */
.hero { min-height: 100svh; }

dvh 會在網址列收合時調整大小,這對應用外殼來說是正確的,但會在中間滾動時導致行銷內容的版面位移。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. 點擊感覺遲鈍

這裡疊加了兩個不同的原因。

300ms 的點擊延遲。 瀏覽器在點擊後會等待,看看是否有第二次點擊,因為雙擊會縮放。現代瀏覽器在視口為 width=device-width 時會跳過等待,但並非所有情況都如此(iOS Safari 在某些元素上仍然有延遲)。touch-action: manipulation 告訴瀏覽器此元素永遠不會雙擊縮放,因此它會立即觸發 click:

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

在釋放而不是按下時提供回饋。 原生按鈕在手指落下的瞬間就會回應。一個只在 click 時改變的網頁按鈕,會在手指離開時才回應,即使延遲為 0ms,這看起來也是延遲。設定 :active 的樣式,如果你需要 JavaScript,請監聽 pointerdown 而不是 click:

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

將按下回饋保持在 100–160ms 並使用 ease-out。如果程式碼庫使用了 animate 技能的 token,請使用它們;不要複製一條新的曲線。

6. 下拉重新整理劫持了捲動

在頁面頂端繼續向上捲動,會在 Android Chrome 上觸發下拉重新整理,並在 iOS 上觸發整個頁面的橡皮筋效應。對於文件來說還好。但在一個有自己捲動容器、使用者向下拖曳的抽屜或畫布的應用中,這是不對的。

html, body {
  overscroll-behavior: none;
}

然後,在任何內部可捲動元素上——例如表單的內容、聊天清單、側邊欄——當觸及邊界時,阻止捲動串聯到頁面:

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

contain 保留容器自身的彈性(這感覺很原生),但阻止它後面的頁面移動。在根元素上使用 none,在子元素上使用 contain。永遠不要為此使用 touchmove + preventDefault() 監聽器——它會完全阻止捲動並使監聽器變成非被動的,從而損失幀數。

7. 內容在瀏海處被切斷

預設情況下,瀏覽器會將你的頁面信箱化在安全區域內,讓瀏海、動態島和 Home Indicator 區域顯示 body 的背景顏色。原生應用會延伸到邊緣,並將其內容墊開那些區域。兩個步驟:

<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-*) 提供你重新墊回的內邊距。沒有這個 meta 標籤,env() 的值都是 0px。固定的頁首、底部標籤欄、提示訊息和表單是需要這個設定的元素;一般的頁面內容通常可以透過頁首的內邊距免費獲得。當該值用在 calc 中時,為 env() 提供一個備用值(env(safe-area-inset-bottom, 0px))。

8. 長按選取了按鈕文字

在網頁按鈕上按住手指,iOS 會選取它的標籤,或者在連結上彈出複製/分享選單。原生控制項永遠不會這樣做。作為控制項的文字不應被選取;作為內容的文字必須保持可選取。

button, [role="button"], .tab, .chip, .drag-handle {
  user-select: none;
  -webkit-user-select: none;   /* Safari 仍需要前綴 */
  -webkit-touch-callout: none; /* 對用作控制項的連結/圖片,禁止長按選單 */
}

永遠不要將 user-select: none 放在 body 上。使用者會複製地址、錯誤訊息和訂單號碼;那些是內容。

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. 狀態列顏色不符

狀態列和瀏覽器 chrome 的顏色來自 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 }])。如果應用使用 class(而非作業系統設定)來切換主題,請在切換時從 JavaScript 更新該標籤。對於已安裝的 PWA,apple-mobile-web-app-status-bar-style 和 manifest 中的 theme_color/background_color 是相同的決策。

11. 在 Chrome 上正常,在手機上錯誤

以上所有問題都無法在設備模擬中重現。黏滯 hover、點擊反白、網址列對 vh 的影響、輸入縮放、點擊延遲、過度捲動、安全區域、軟體鍵盤——每一個都是真實硬體的行為。

  • 透過 USB 連接手機,在 0.0.0.0 上執行開發伺服器,透過機器的 LAN IP 打開它。
  • iOS:Safari → 開發 → 裝置。Android:chrome://inspect。
  • 在幾年前的舊手機上測試,而不是你桌上最新的那部。在鍵盤開啟的狀態下測試。在橫向模式下測試一次。
  • 如果目標是安裝為 PWA,請測試 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;
}

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.

相關技能