s0up4200/mobile-adapt

Mobile Adapt (行動適應)

目標 (Goal)

在不移除核心功能的前提下，將現有介面改編為適合手機使用。除非使用者指定其他目標，否則優先針對 iPhone 等級的行動網頁進行最佳化。

預設目標 (Default target)

如果使用者未指定裝置或瀏覽器，請優先針對以下項目進行最佳化：

• iPhone Pro Max 等級（直向和橫向）
• iOS Safari
• 寬度約 375-440 CSS px 的緊湊觸控螢幕
• 鍵盤開啟狀態、大字型、安全區域 (safe areas) 以及減少動畫效果 (reduced motion)

何時進行研究 (When to research)

此技能依賴當前的平台行為。

• 當使用者詢問最新/當前指南、iPhone 特定行為、Safari/WebKit 怪異行為、安全區域行為、PWA/主畫面行為或直接引用來源時，請瀏覽官方來源。
• 偏好使用 Apple Developer、WebKit、W3C/WCAG、MDN、Android Developers 和 web.dev。
• 引用最新的平台變更時，請使用絕對日期。

如需瞭解當前最具參考價值的規則和來源，請參閱 references/mobile-ui-2026.md。

核心規則 (Core rules)

• 保持緊湊型手機為單欄式。 不要因為橫向手機超過了通用斷點就切換到桌面資訊架構。手機橫放時仍然是雙手手持、手臂伸展的狀態——使用者的心智模型是「手機」，而不是「平板」。採用多欄式佈局會造成混亂的體驗，沒有一個區域大到足以舒適使用。

• 僅為真正的頂層區塊使用底部優先的行動導覽。 將導覽項目限制在 3-5 個主要目的地；超出部分移至「更多」、選單表或次要流程。螢幕底部是拇指的自然休息區——將主要導覽放在那裡表示最常見的操作需要最少的力氣。超過 5 個項目會讓點擊目標縮小到無法使用的尺寸，並導致視覺混亂。

• 每個互動目標至少應為 44x44 CSS px（雙向）。 這包括容易忽略的次要元素：行內操作按鈕（編輯、刪除、檢視）、展開/收合切換開關、篩選標籤、工具列中的圖示按鈕、選單表上的關閉按鈕，以及核取方塊/選項按鈕行（使用 <label> 作為完整觸控目標，而非僅輸入本身）。電容式觸控螢幕會在大約 44pt 的位置感應手指接觸區域的中心——較小的目標會導致點錯挫敗感，尤其是在移動中。常見的 Tailwind 類別中不足的有：h-8 (32px)、h-9 (36px)、p-1 圖示 (~24px)、p-1.5 (~28px)、p-2 (~32px)。請使用 h-11 (44px)、min-h-[44px] 或等效類別作為每個可點擊元素的基準。此規則符合 Apple HIG 標準，並超過 WCAG 2.2 的 24px 最低要求。

• 不要依賴懸浮、微小圖示點擊或隱藏列操作。 觸控裝置沒有懸浮狀態——任何需要懸浮才能發現的操作都是不可見的。請使用可見的控制項、帶有視覺提示的滑動手勢，或上下文選單表/選單。

• 避免頁面水平捲動。 單手使用手機時是垂直的拇指捲動。水平捲動會破壞使用者的空間模型，並將內容隱藏在螢幕外，且沒有可見的提示。請改用重新排版、堆疊、分頁或區域性捲動表格和圖表，而非整個頁面。

• 使用 viewport-fit=cover、env(safe-area-inset-*) 和 min-height: 100dvh。 現代 iPhone 具有圓角、Dynamic Island 和主畫面指示器——這些都會佔用矩形視埠的空間。如果沒有明確處理安全區域，內容會被硬體鏡頭或狀態列遮擋。dvh 能處理舊版 vh 無法處理的、Safari 工具列收合問題。

• 將主要操作保持在瀏覽器工具列、主畫面指示器、圓角和螢幕鍵盤之外。 一個隱藏在鍵盤後面或與主畫面指示器重疊的「提交」按鈕在功能上是壞掉的——使用者要嘛看不到，要嘛無法點擊而不觸發系統手勢。

• 對於表單密集型或鍵盤密集型流程，偏好單一主要捲動容器。 iOS Safari 上的巢狀捲動區域會產生捲動陷阱：使用者的拇指在無意間捲動了內部容器，而他們原本想捲動的是頁面，反之亦然。WebKit 在這裡有持續存在的錯誤（請參閱參考文件）。僅在沒有替代方案時才使用巢狀捲動。

• 使用語意化的行動輸入元件。 標籤置於欄位上方（而不是旁邊——沒有水平空間），並使用正確的 type、inputmode、autocomplete 和 enterkeyhint。這些屬性控制顯示哪種鍵盤——inputmode="decimal" 會為貨幣顯示數字鍵盤，enterkeyhint="next" 讓使用者能逐項填寫表單而無需關閉鍵盤。

• 將大字型視為真實的佈局輸入。 iOS 使用者可以設定系統範圍的大字型，而且很多人都這麼做。請讓文字換行和重新排版——不要用截斷來隱藏關鍵意義。如果一個被截斷的標籤讓使用者猜測他們看到的是「儲蓄帳戶」還是「薪轉帳戶」，那麼這個佈局就失敗了。

• 在手機上，圖表是輔助說明的角色，而非全部。 一個手機螢幕大約只能顯示 5-6 個可辨識的長條或一個甜甜圈圖。這樣的資料密度不足以讓圖表自明。請以關鍵數字和文字摘要為主；將圖表作為視覺輔助。

• 保留產品現有的品牌和設計系統，除非使用者要求進行更廣泛的重新設計。行動適應是關於佈局和互動的調整，而不是重新換膚。

範例 (Examples)

在更改導覽外殼、資料表格或帶有提交按鈕的表單之前，請閱讀 references/mobile-examples.md。其中包含了側邊欄變成底部導覽列、表格變成手機卡片列表，以及表單提交按鈕保持在鍵盤上方的 before/after 程式碼範例。

工作流程 (Workflow)

1. 鎖定目標上下文。
   • 裝置、瀏覽器、方向、使用情境
   • 如未指定，預設為 iPhone Pro Max + iOS Safari
2. 先稽核外殼。
   • 導覽模式
   • 安全區域
   • 固定/黏貼工具列
   • 橫向行為
   • 鍵盤行為
3. 稽核每個畫面或元件。
   • 列表和列
   • 表單
   • 表格
   • 圖表
   • 空白/錯誤/載入狀態
4. 選擇硬轉折點。
   • 哪些變成單欄
   • 哪些變成卡片
   • 哪些移入選單表/抽屜
   • 哪些變成「更多」下的次要項目
5. 實作行動優先的適應。
   • 對於元件內部，優先使用容器查詢 (container queries)
   • 對於外殼/佈局模式變更，優先使用視埠查詢 (viewport queries)
   • 除非明確要求，否則不要保留一半桌面/一半行動的舊行為
6. 在緊湊直向和緊湊橫向上驗證。
   • 先測試 Safari/WebKit
   • 然後測試 Chromium
7. 優先報告風險最高的問題，然後是具體的變更和任何剩餘的差距。

畫面檢查清單 (Screen Checklist)

外殼與導覽 (Shell and navigation)

• 在橫向手機上保持手機外殼。
• 避免對仍是手機的裝置使用硬性的 md => 桌面側邊欄 切換。
• 使用 env(safe-area-inset-bottom) 為底部 UI 增加間距。
• 讓黏貼操作元素位於底部導覽之上。
• 保持行動標籤簡短。

列表與列 (Lists and rows)

• 讓標題、中繼資料和金額在需要時換行成兩列。
• 為價格、餘額和總額保留穩定的空間。
• 偏好堆疊的中繼資料而非擠壓的行內中繼資料。
• 使用可見的控制項或選單表/選單來顯示操作，不要用懸浮。
• 調整列操作按鈕（編輯、刪除、檢視、展開）的大小至少為 44x44 CSS px——不僅是主要導覽和工具列按鈕需要如此。

表單 (Forms)

• 在緊湊型手機上使用單欄。
• 保持提交按鈕在鍵盤上方可見。
• 使用清晰的全寬主要行動呼籲 (CTA)。
• 將長流程拆分成步驟或漸進式揭露。
• 如果格式或精度重要，避免對貨幣使用 type="number"。

表格與匯入/審查流程 (Tables and import/review flows)

• 將密集的可編輯表格轉換為手機上的卡片/列表。
• 如果必須保留真實表格，請將水平捲動限制在表格本身。
• 保持黏貼標題和工具列不遮擋已聚焦的輸入欄位。

圖表與統計 (Charts and stats)

• 以關鍵數字和簡短說明為主。
• 加入緊湊的圖例和文字備用方案。
• 偏好水平捲動或分頁比較，而非無法閱讀的密集長條圖。
• 避免在緊湊螢幕上使用微小的圓餅圖/甜甜圈圖。

驗證 (Verification)

對於以下每個檢查項目，請確認具體的通過條件，並使用建議的工具。真實裝置測試是黃金標準——模擬器有助於迭代，但無法完全重現鍵盤時序、捲動慣性或觸控精度。

• 直向和橫向 (Portrait and landscape) — 手機在兩種方向下都保持在行動外殼中。沒有佈局破損、內容溢出，或突然切換到桌面側邊欄或多欄視圖。在直向下測試 375px (iPhone SE/mini 等級)、390px (iPhone Pro) 和 430px (iPhone Pro Max)，以及其等效的橫向解析度。使用 Chrome DevTools 裝置工具列或 Xcode 模擬器。

• iOS Safari 安全區域 (iOS Safari safe areas) — 內容不會被 Dynamic Island、圓角或主畫面指示器遮擋。底部固定元素具有可見的 env(safe-area-inset-bottom) 間距（在 Face ID iPhone 上約為 34px）。確認視埠 meta 標籤中已設定 viewport-fit=cover——沒有它，所有 env(safe-area-inset-*) 值都將返回 0。最佳測試工具為 Xcode 模擬器（每個裝置的精確內嵌值）或 Polypane 26+（具有真實安全區域內嵌預設值的桌面瀏覽器）。Chrome DevTools 135+ 支援 Emulation.setSafeAreaInsetsOverride，但需要手動設定。

• 鍵盤開啟的表單流程 (Keyboard-open form flow) — 依序聚焦每個輸入欄位並驗證：(1) 聚焦的欄位會捲動至可視區域，(2) 提交操作是可見且可點擊的，(3) 黏貼標題不會遮擋聚焦的欄位。請注意，position: fixed; bottom: 0 元素會隱藏在 iOS 鍵盤後面（佈局視埠不會縮小），而 position: sticky; bottom: 0 在鍵盤顯示期間也無法固定（WebKit bug #202120）。Playwright 和 Cypress 無法觸發真實的螢幕鍵盤——這需要真實裝置測試或帶有 Safari Web Inspector 的 Xcode 模擬器。

• 大字型 / 顯示縮放 (Large text / display zoom) — WCAG 1.4.4 (AA) 要求文字可調整至 200% 而不遺失內容。WCAG 1.4.10 (AA) 要求在 400% 縮放（相當於 320px 寬的視埠）下重新排版且無水平捲動。測試方式：(1) 將瀏覽器縮放設定為 200%，並確認沒有截斷或重疊，(2) 將視埠設定為 1280px 並縮放至 400% 以模擬 320px 的重新排版需求，(3) 啟用 iOS 設定 > 輔助使用 > 顯示與文字大小 > 更大字體至最大。確認視埠 meta 標籤未設定 user-scalable=no 或 maximum-scale 低於 2.0。

• 減少動畫效果 (Reduced motion) — 動畫尊重 prefers-reduced-motion: reduce。過渡效果仍會傳達狀態變更，但使用交叉淡入或透明度而非移動效果。iOS Safari 在「減少動畫效果」開啟時不會自動抑制網頁動畫——開發者必須自行處理。測試方式：Chrome DevTools 的 Rendering 分頁 > "Emulate prefers-reduced-motion"、Safari Web Inspector 偏好設定覆蓋（自 2022 年底起可用），或 Playwright 的 page.emulateMedia({ reducedMotion: 'reduce' })。

• 空白/錯誤/載入狀態 (Empty/error/loading states) — 這些狀態在緊湊螢幕上正確呈現。載入骨架 (skeleton) 符合行動佈局，而非桌面佈局。錯誤訊息可讀且無需捲動。

• 獨立/PWA 模式 (Standalone/PWA mode)（相關時）— 如果應用程式支援 display: standalone，請確認狀態列區域、主畫面指示器和手勢區域已處理。svh 和 dvh 在獨立模式下解析為相同的值，因為沒有可收合的工具列（WebKit bug #261185）。WebKit bug #254868 可能導致高度值不正確。WebKit bug #265578 導致當 Safari UI 動畫回到視圖時，可視視埠高度更新延遲。

• 無水平文件捲動 (No horizontal document scroll) — 在頁面主體上向左/向右滑動不會產生任何移動。任何水平捲動都應限制在特定容器（表格、輪播）內，並具有可見的溢出提示和 overscroll-behavior: contain，以防止觸發 Safari UI 的偏移（WebKit bug #240861）。使用 Playwright 進行自動化驗證：

  const hasOverflow = await page.evaluate(() =>
    document.documentElement.scrollWidth > document.documentElement.clientWidth
  );
  expect(hasOverflow).toBe(false);
  

交付成果 (Deliverable)

使用此技能時，應產出：

• 一份簡短的行動適應計畫
• 優先列出風險最高的問題
• 具體的每畫面變更
• 已執行的驗證
• 任何剩餘的裝置/瀏覽器不確定性