Community程式設計與開發github.com

響應式網頁:行動優先、任何技術棧、經驗證

建立並驗證在任何螢幕寬度(從 320px 手機到 2560px 螢幕)都能正常顯示的網頁 UI,採用行動優先方法,支援任何技術棧:純 CSS、Tailwind、Bootstrap、SCSS、CSS modules、CSS-in-JS、React/Vue/Svelte/Angular 或伺服器渲染模板。內建一個 Playwright 檢查工具,可掃描 150 多種寬度以及橫向手機,並測量真實的佈局破損情況:橫向滾動、文字被截斷或重疊、覆蓋或過小的觸控目標、圖片拉伸、缺少或禁止縮放。

響應式網頁:行動優先、任何技術棧、經驗證 是什麼?

這個技能旨在建立真正響應式的網頁佈局,而非僅針對幾個設備寬度進行優化。它採用行動優先的設計理念,先為最小螢幕撰寫基礎樣式,再透過 `min-width` 媒體查詢逐步增加佈局,從而避免常見的桌面優先設計中因 `max-width` 修補而產生的間隙。該技能支援所有主流技術棧,包括 Tailwind、Bootstrap、SCSS、CSS modules、CSS-in-JS 以及 React/Vue/Svelte/Angular 等框架。驗證環節由 `scripts/check_responsive.py` 腳本自動完成,該腳本使用 Playwright 遍歷從 320px 到 1920px 的寬度,並檢查橫向滾動、文字溢出、觸控目標尺寸、圖片失真等多項指標,確保佈局在每個寬度下都完美運作。技能還提供詳盡的參考文件和修復指南,協助開發者快速定位並解決問題,最終以 0 錯誤為完成標準。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/isikenes35/responsive-web/tree/HEAD

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

響應式網頁:行動優先、任何技術棧、經驗證 是做什麼的?

目標是讓佈局在每個寬度下都能正常運作,而不是只適用於別人挑選的五個設備寬度。 錯誤往往藏在間隙中:412px、905px,或者某個寬度讓 max-width: 767px 和 min-width: 769px 同時失效。 因此,這個技能包含兩個相輔相成的部分:

  1. 行動優先開發:撰寫能自動適應的佈局,減少中斷點需求。
  2. 驗證:執行 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包含滾動條,因此在桌面上約寬 15px100%(或僅在真正需要全幅且謹慎使用時使用 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-viewportviewport 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. 修復循環

  1. 先修復最小的失敗寬度。行動版是基礎,修復它通常能解決其餘問題。
  2. 修復線索指出的根本原因,在專案使用的原始碼中(Tailwind class、SCSS partial、styled component),而不是用一次性覆寫。references/checks.md 列出了每個檢查項目的原因和修復方法。
  3. 重新執行(--quick),重複,然後執行一次完整執行。當錯誤為 0 且每個警告都已修復或有充分理由時停止。
  4. 是否有意違反規則的情況(例如裝飾性形狀溢出螢幕、英雄區拼貼中有意重疊)?為該元素標記 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 個測試案例)。在修改檢查工具後執行。

相關技能