Communitygithub.com

bompus/hr-better-layout

網頁 UI 版面規則:分組、對齊、間距、閱讀順序、響應式斷點、邏輯屬性及窄寬度裁切。用於建構或審查頁面或元件版面 CSS。

hr-better-layout 是什麼?

此技能為網頁 UI 版面提供結構化規則,強調在內容被閱讀前,透過位置、間距和對齊來傳達層級。它協助開發者在使用 Claude Code、Cursor 或 Codex 等 AI 代理時,建構和測試版面,確保在縮放、翻譯和 RTL 鏡像等情況下仍保持穩固。技能支援多種平台,並包含詳細的檢查清單與常見錯誤修復對照表,例如將 `margin-left` 替換為 `margin-inline-start`。核心原則包括:使用空間而非線條來分組、確保控制項與內容有明顯區別、對齊共享邊緣、依據重要性排序內容,以及為隱藏內容提供視覺提示。此外,技能也涵蓋響應式設計,建議使用容器查詢進行元件層級適應,並優先測試最小和最大尺寸。技能還包含錯誤報告格式,分為 HIGH、MEDIUM、LOW 三種嚴重等級,並要求提供位置、前後對照及影響原因,便於團隊追蹤與改進。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bompus/house-rules/tree/HEAD/skills/hr-better-layout

在你喜歡的 AI 中提問

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

說明文件

版面

位置、間距和對齊在文字被閱讀之前就已傳達層級。此技能旨在建構此結構並對其進行壓力測試:調整大小、翻譯、為 RTL 進行鏡像。

所有修正都應使用專案的樣式系統進行。以下數值是針對尚未建立密度系統的介面所提供的起點;若專案已有密度系統,則應依其書寫,而非使用看似熟悉的替代值。保留刻意設計的平台外觀、緊湊的專業工具以及專案權杖,前提是它們仍能通過壓力測試。

點擊區域和焦點行為屬於 hr-better-accessibility。圓角、陰影和動畫不在此技能範圍內。行長度和文字間距屬於 hr-better-typography。

以空間分組,而非線條

優先使用空間分組,其次是背景形狀,最後才是分隔線,且僅在空間本身無法承載結構時使用。組與組之間的間距必須至少是組內間距的 2 倍(例如組內 8px,組間 16px+),否則分組會讀起來像雜訊。對齊邊緣和重要性排序請參見 grouping-and-alignment.md。

保持控制項與內容有區別

每個可互動元素都應具備背景形狀、邊框或一致的放置區域。若控制項的樣式與其旁邊的靜態文字相同,則不會被識別為控制項。

對齊共享邊緣

選擇對齊邊緣並保持一致;每個不齊的邊緣讀起來都像雜訊。每個從屬層級使用一個專案間距單位,16px 是實用的預設值。

對於方向依賴的版面,使用邏輯屬性:padding-inline-start、margin-inline-end。僅在真正需要物理幾何時才保留使用物理的 left 和 right。

依重要性排序

最重要的內容應靠近頂部和前導邊緣。閱讀順序由上而下、由前導到後緣。思考方向時使用前導和後緣,而非左和右。

提示隱藏內容

漸進式揭露需要可見的提示。使用專案既有的提示方式,或讓下一項內容在滾動邊緣露出 16-32px,或顯示一個揭露控制項。沒有提示就隱藏的內容,等同於不存在。

目標之間的呼吸空間

若無既定的密度系統,相鄰的帶邊框或填充控制項之間從 12px 開始,無邊框的文字和圖標控制項周圍則為 24px。緊湊的版面可以使用較少間距,只要 hr-better-accessibility 的點擊區域不重疊且控制項保持區別即可。版面邊距和斷點方法請參見 spacing-and-adaptivity.md。

按鈕內縮遠離邊緣

在內容版面中,將全寬按鈕保持在版面邊距內,並具有明顯的圓角,在行動裝置上從 16px 左右的內聯邊距開始。邊到邊的操作只有在遵循既有的平台外觀、考慮安全區域且與系統 UI 可區分時才適用。

內容延伸,控制項浮動

背景和多媒體延伸至視口邊緣。控制項和文字則保持在版面邊距和安全區域(env(safe-area-inset-*))內。固定位置的平台外觀應浮在內容層之上,而非遮擋內容。

保持結構直到內容中斷

斷點應來自內容,而非裝置預設值。只要內容真正適合,就盡可能保持展開的版面,並在必要時才收縮。元件層級的適應優先使用容器查詢,並先測試最小和最大尺寸。

為文字增長和裁切做好準備

翻譯後的字串會增長,而短字串增長的比例更大,因此一個單詞按鈕是螢幕上風險最高的元素。不要在文字容器上設定固定的寬度或高度,並讓行可以自動換行。使用偽本地化和一個具代表性的語言環境進行測試,而非預留百分比空間。

切勿將關鍵操作放置在會因調整大小或滾動而被裁切的位置。應將其保留在正常流程中,或放置在適合產品的穩定外觀中。

完成前請檢查

錯誤修正
在可本地化的版面中使用 margin-left / padding-right改用 margin-inline-start / padding-inline-end
內容版面按鈕觸碰到視口邊緣內縮至專案邊距內;保留刻意設計的平台外觀
斷點設為 768/1024 因為它們是預設值在內容實際無法容納的地方設定斷點
為單一語言設定的固定寬度文字容器使用 max-width 和自動換行;測試偽本地化
主要操作位於容易裁切的窗格底部使用固定定位或具有安全區域內邊距的穩定外觀
在行動裝置上使用 100vh 作為應用程式外殼或首頁對於追蹤瀏覽器外觀的外殼使用 100dvh,對於首個畫面使用 100svh
長文字將一行的尾部操作推出螢幕或壓縮了頭像在文字欄上設定 min-width: 0,在固定尺寸項目上設定 flex-shrink: 0

回報

嚴重等級。 HIGH 在支援的視口尺寸下阻擋內容或操作。MEDIUM 損害層級、閱讀順序或適應性。LOW 屬於孤立的對齊或間距調整。

驗證。 沒有瀏覽器時:檢查邏輯屬性是否取代了物理屬性、容器和媒體查詢是否針對支援的視口列表、DOM 順序是否符合預期閱讀順序。有瀏覽器時:檢查每個支援的寬度、200% 縮放和 RTL 鏡像。將所有無法執行的檢查回報為 Not verified。

格式。 將發現的問題按照違反的原則分組,按嚴重等級排序,每個根本原因一行,列出所有出現的位置:

嚴重等級位置變更前變更後原因

位置 為 path/to/file:line。原因 說明違反的原則以及對使用者的影響。

若仍有任何 HIGH 等級問題未解決,則回報 Block;否則回報 Approve,並將其餘問題留在表格中作為待辦事項。切勿對你未檢查的範圍回報 Approve。若無任何需要回報的內容,請輸入 "無需處理的版面相關發現" 並說明驗證情況。

Individual skills in this repo

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

相關技能