響應式網頁:行動優先、任何技術棧、經驗證 是做什麼的?
目標是讓佈局在每個寬度下都能正常運作,而不是只適用於別人挑選的五個設備寬度。
錯誤往往藏在間隙中:412px、905px,或者某個寬度讓 max-width: 767px 和 min-width: 769px 同時失效。
因此,這個技能包含兩個相輔相成的部分:
- 行動優先開發:撰寫能自動適應的佈局,減少中斷點需求。
- 驗證:執行
scripts/check_responsive.py,它會渲染頁面並測量每個寬度下的佈局。僅靠一兩張螢幕截圖說「看起來沒問題」不算完成。完成的標準是檢查工具回報 0 個錯誤。
檢查工具只檢視渲染後的頁面(DOM 盒模型和計算後的樣式),因此它不關心 CSS 是如何撰寫的。這正是它適用於任何技術的原因。
0. 先閱讀專案
在撰寫 CSS 之前,花一分鐘了解:
- 此處的樣式撰寫方式:Tailwind(
tailwind.config.*或 CSS 中的@theme)、Bootstrap/SCSS 變數、CSS modules、styled-components/emotion、Vue/Svelte 範圍樣式、純 CSS 檔案。請使用相同的系統和 token 撰寫新程式碼。引入第二套樣式系統是一種維護上的錯誤。 - 現有的中斷點,並重複使用它們。除非內容需要,否則不要發明新的中斷點。
- 如何查看頁面:靜態
.html檔案,或開發伺服器(npm run dev、php artisan serve、python manage.py runserver、rails s、dotnet watch...)。你需要一個檢查工具可存取的 URL 或檔案路徑。
references/stacks.md 展示了常見技術棧的行動優先語法及中斷點位置。
1. 行動優先開發
針對最小螢幕撰寫基礎樣式,不使用媒體查詢。隨著空間增加,使用 min-width 查詢來添加佈局。 手機獲得最簡單的 CSS,內容自然堆疊,每個中斷點只添加東西。桌面優先的方式(先寫桌面版,再用 max-width 向下修補)會在修補之間留下空隙,而這些空隙正是大多數響應式錯誤的來源。
如果程式碼庫已經是桌面優先,請不要重寫它。請在其慣例內以行動優先方式撰寫你新增或修改的部分,並修復檢查工具發現的問題。
優先使用無需中斷點即可適應的佈局
- 網格:
grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr))。欄位會隨著空間允許而出現,無需中斷點,且在 320px 時不會溢出(其中的min(100%, …)部分就是防止溢出的關鍵)。 - 應換行的列:
display: flex; flex-wrap: wrap; gap: …搭配合理的flex-basis。 - 尺寸:使用
width: 100%; max-width: 40rem而非width: 640px。使用clamp(min, 首選, max)實現流體排版和間距。 - 會在不同寬度的插槽(側邊欄 vs. 主欄)中顯示的元件:使用容器查詢(
container-type: inline-size+@container),使其回應其容器而非視窗。 - 在內容中斷的地方添加中斷點(縮小視窗直到某些東西看起來不對勁),而非在設備寬度處。
常見的佈局破壞者。撰寫時逐一檢查。
| 破壞者 | 為何破壞 | 替代方案 |
|---|---|---|
容器使用固定的 width/min-width(px) | 比 320px 手機還寬 | max-width + width:100%、%、fr、minmax() |
| flex/grid 子元素包含長內容 | 子元素預設 min-width: auto,拒絕縮小 | 在子元素上設定 min-width: 0(或 minmax(0,1fr)) |
| 長單字、URL、郵件、程式碼 | 無斷行機會 | 在文字容器上使用 overflow-wrap: anywhere |
按鈕/標籤/導航上的 white-space: nowrap | 文字無法換行,撐開寬度 | 允許換行,或使用 min-width:0 搭配 title 屬性顯示省略號 |
| 圖片、影片、iframe、嵌入內容 | 原始寬度大於螢幕 | max-width:100%; height:auto;嵌入內容使用 aspect-ratio |
| 表格 | 欄位無法縮小到內容以下 | 包裹在 overflow-x:auto 容器中,或在小型螢幕上堆疊為列 |
pre/code 區塊 | 保留空白 | 在區塊上使用 overflow-x:auto |
100vw | 包含滾動條,因此在桌面上約寬 15px | 100%(或僅在真正需要全幅且謹慎使用時使用 100dvw) |
包含文字的盒子使用固定 height | 文字在手機上換行後會溢出/被裁切 | min-height,或不設定高度 |
| 內容使用絕對定位 | 不佔用空間;在其他寬度下會碰撞 | 正常流/網格;僅裝飾性元素使用絕對定位 |
height: 100vh 的英雄區 | 手機瀏覽器工具列和短橫向螢幕會將其裁切 | min-height: 100svh(在此之前加上 100vh 作為降級方案) |
絕不隱藏症狀
- 不要在
html/body上使用overflow-x: hidden來阻止橫向滾動。這會隱藏錯誤,同時內容仍被裁切(而且會破壞position: sticky)。請找出過寬的元素。檢查工具會將此類隱藏行為報告為clipped-offscreen。 - 不要使用
user-scalable=no或maximum-scale=1。禁止縮放是一種無障礙失敗(WCAG 1.4.4)。 - 不要使用 JavaScript 寬度檢查或用戶代理嗅探來處理佈局。CSS 媒體/容器查詢可以無閃爍地完成這項工作。JavaScript 適合用於行為(
matchMedia),但不適合用於佈局。 - 不要為了通過測試而修改測試(提高
--min、添加忽略讓錯誤消失)。
觸控、輸入、視口
- 每個頁面的
<head>中都需包含<meta name="viewport" content="width=device-width, initial-scale=1">。 - 觸控目標至少 24x24px(WCAG 2.2 AA)。按鈕和觸控螢幕上的圖示控制項建議達到 44x44px,並在相鄰元素之間保留空間。
- 僅懸停狀態的 UI(選單、揭示內容的工具提示)需要
@media (hover: hover)以及點選替代方案。 - 手機上的表單欄位
font-size: 16px或以上,否則 iOS Safari 會在聚焦時放大。請使用適當的type、inputmode和autocomplete。 - 短橫向手機(高度 320–430px)是真實存在的。固定頁首加上 cookie 橫幅不應覆蓋超過螢幕約三分之一的高度。在高度較短時(
@media (max-height: 500px))折疊或縮小它們。 - 有瀏海的設備:僅在配合
viewport-fit=cover時使用env(safe-area-inset-*)內邊距。
排版、媒體、導航、內容
- 文字使用
rem,標題使用clamp(),行長限制(max-width: 65ch左右),無單位的行高。 - 圖片:照片使用
srcset/sizes,使用width/height屬性或aspect-ratio以避免版面位移,當盒子比例與圖片不同時使用object-fit: cover(否則圖片會被拉伸)。 - 導航:在小螢幕上,使用一個真正的
<button>,搭配aria-expanded/aria-controls來開啟選單。在寬度足夠容納內聯連結時才顯示它們。 - 保持內容一致性:不要因為難以容納就在手機上刪除內容。可以重新排序、壓縮或折疊它們。
references/patterns.md 提供了上述每一項(網格、導航、表格、表單、英雄區、卡片、媒體)的可複製 CSS。
2. 驗證:執行檢查工具
一次性設定(Python 3.9+):
pip install playwright
python -m playwright install chromium
對渲染後的頁面執行。如果有的話,請先啟動開發伺服器。
python <skill-dir>/scripts/check_responsive.py http://localhost:5173/ --out responsive-report
python <skill-dir>/scripts/check_responsive.py site/index.html --out responsive-report # 靜態檔案
- 多個頁面:傳遞多個 URL。檢查你修改的每個頁面或路由,以及一個使用共用佈局(頁首/頁尾)的頁面。
- 延遲渲染的 SPA:
--wait-for "#app main"。需要登入的頁面:--storage-state state.json。 - 修復期間的內部循環:
--quick(約 5–10 秒)。在你聲明完成之前執行一次完整執行(每個頁面約 20–40 秒)。 - 退出碼:0 = 無錯誤,1 = 發現錯誤(或搭配
--strict時的警告),2 = 無法執行。
檢查工具的作用:以 10px 為步進掃描 320→1920px,加上常見的設備寬度,以及頁面自身 CSS 中每個中斷點的兩側。它會使用真實的手機模擬(觸控、meta viewport)重新載入關鍵寬度,並檢查四個短橫向手機。在每個寬度下,它會測量:
| 錯誤(必須修復) | 意義 |
|---|---|
horizontal-overflow | 頁面橫向滾動;指出突出的元素及其變寬的原因 |
clipped-offscreen | 內容在螢幕邊緣被裁切(常被 body 上的 overflow-x:hidden 隱藏) |
occluded-target | 連結/按鈕被另一個元素覆蓋(或被固定欄在每個滾動位置覆蓋) |
small-target | 觸控目標小於 24px 且與相鄰元素擁擠 |
text-spill / text-clipped | 文字溢出其盒子 / 被固定尺寸 + overflow:hidden 裁切 |
text-overlap | 兩個不相關區塊的文字重疊繪製 |
distorted-media | 圖片/影片被拉伸(盒子比例 ≠ 原始比例,無 object-fit) |
viewport-meta, layout-viewport | viewport meta 缺失/禁止縮放;手機以桌面寬度渲染 |
警告(修復它們或解釋為何不修復):touch-target(觸控寬度下 <44px 的控制項)、small-text(手機上 <12px)、input-zoom(<16px 的輸入框)、fixed-coverage(固定/黏性欄佔據短螢幕超過 35%)。
報告(report.md、report.json)會像這樣分組發現結果:
1. **horizontal-overflow** 於 320-610px;568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
- 最差情況:在 320px 時超出右邊緣 296 px
- 線索:在每個失敗的寬度下都恰好保持 600px 寬:一個固定寬度 - 改用 max-width/%/fr/minmax
- 特寫:responsive-report/closeups/01-horizontal-overflow-320.png
線索行就是診斷結果。在開啟 CSS 之前先閱讀它。
3. 修復循環
- 先修復最小的失敗寬度。行動版是基礎,修復它通常能解決其餘問題。
- 修復線索指出的根本原因,在專案使用的原始碼中(Tailwind class、SCSS partial、styled component),而不是用一次性覆寫。
references/checks.md列出了每個檢查項目的原因和修復方法。 - 重新執行(
--quick),重複,然後執行一次完整執行。當錯誤為 0 且每個警告都已修復或有充分理由時停止。 - 是否有意違反規則的情況(例如裝飾性形狀溢出螢幕、英雄區拼貼中有意重疊)?為該元素標記
data-responsive-ignore="text-overlap"(以空格分隔的檢查名稱),並在程式碼中添加註釋說明原因。為了通過測試而忽略真實內容,就等同於沒有測試。
4. 視覺檢視
檢查工具能找出可量化衡量的問題。有些問題無法衡量:尷尬的換行(按鈕上孤單的一個字)、孤獨的最後一個網格項目、1920px+ 時巨大的空白間隙、裁切到主體的圖片裁剪、技術上沒問題但難以使用的選單。請打開執行時儲存的螢幕截圖(screens/320.png、375、768、1024、1440 以及 closeups/)並仔細查看。如果你無法檢視圖片,請在報告中說明,而不是聲稱已進行視覺審查。
當你向使用者報告視覺問題時,請透過元素是什麼以及在何處來描述它們(例如「產品照片上的價格標籤」、選單網格中的第二張卡片),而不是使用 class 名稱。使用者不閱讀 DOM 選擇器。請將選擇器保留在你自己的筆記中,以便尋找程式碼。
5. 僅審計要求
如果使用者要求檢查或審計一個網站(而非修復),請先執行完整的檢查工具,並按嚴重性和寬度範圍分組報告發現結果(附上螢幕截圖),然後再碰觸程式碼。如果範圍很大,請在修復前先詢問。
6. 告知使用者已驗證的內容
最後提供一個簡短、基於事實的總結:
- 你修改了哪些內容(檔案、元件);
- 測試了哪些項目:頁面、
N 個寬度 320–1920px、橫向手機;檢查工具結果(0 個錯誤,1 個警告); - 每個剩餘的警告以及為何保留它;
- 螢幕截圖的位置;
- 未驗證的內容。檢查工具僅使用 Chromium,因此 Safari/Firefox 的怪異行為、真實設備的鍵盤、純文字 200% 縮放、RTL 以及未提供儲存狀態的登入後頁面,除非你個別測試過,否則不在涵蓋範圍內。
參考檔案
references/patterns.md:常用建構區塊的可複製行動優先 CSS。在建構新佈局或元件時閱讀。references/stacks.md:行動優先和中斷點在 Tailwind、Bootstrap、SCSS、CSS modules、CSS-in-JS、MUI/Chakra、Vue/Svelte/Angular、伺服器範本中的呈現方式,以及如何為檢查工具提供每種方式的服務。references/checks.md:每個檢查工具的發現結果,包含典型原因、修復方法和已知的誤報。當發現結果的原因不明顯時閱讀。scripts/selftest/run_selftest.py:證明檢查工具仍能捕捉到每種錯誤類型(14 個測試案例)。在修改檢查工具後執行。