adeyanjufuhad/astrolabe

用於建置可訪問、快速、令人愉悅的使用者介面的簡潔規則。使用 MUST/SHOULD/NEVER 來指導決策。

互動

鍵盤

• MUST: 根據 WAI-ARIA APG 提供完整的鍵盤支援
• MUST: 可見且不被遮擋的焦點環（:focus-visible；與 :focus-within 分組）；固定/粘性元素絕不覆蓋焦點
• MUST: 根據 APG 模式管理焦點（捕捉、移動、返回）
• NEVER: 在沒有可見焦點替代方案的情況下使用 outline: none

目標與輸入

• MUST: 點擊目標 ≥24px（行動裝置 ≥44px）；如果視覺元素 <24px，則擴大點擊區域
• MUST: 行動裝置 <input> 字型大小 ≥16px 以防止 iOS 縮放
• NEVER: 停用瀏覽器縮放（user-scalable=no、maximum-scale=1）
• MUST: 使用 touch-action: manipulation 防止雙擊縮放
• SHOULD: 設定 -webkit-tap-highlight-color 以符合設計

表單

• MUST: Hydration 安全的輸入（不會遺失焦點/值）
• NEVER: 在 <input>/<textarea> 中阻止貼上
• MUST: 載入中的按鈕顯示旋轉圖示並保留原始標籤
• MUST: Enter 鍵提交焦點所在的輸入；在 <textarea> 中，⌘/Ctrl+Enter 提交
• MUST: 保持提交按鈕啟用，直到請求開始；然後停用並顯示旋轉圖示
• MUST: 接受自由文字，之後再進行驗證——不要阻擋輸入
• MUST: 允許不完整的表單提交以顯示驗證錯誤
• MUST: 錯誤訊息內聯顯示在欄位旁邊；提交時，將焦點置於第一個錯誤
• MUST: 使用 autocomplete 並搭配有意義的 name；正確的 type 和 inputmode
• SHOULD: 對電子郵件、代碼、使用者名稱停用拼寫檢查
• SHOULD: 預留位置文字以 … 結尾，並顯示範例模式
• MUST: 在導航前警告未儲存的變更
• MUST: 與密碼管理器和 2FA 相容；允許貼上驗證碼
• MUST: 修剪值以處理文字擴展時產生的尾隨空格
• MUST: 核取方塊/單選按鈕沒有死區；標籤與控制項共享一個點擊目標

狀態與導航

• MUST: URL 反映狀態（深層連結篩選器、分頁、展開的面板）
• MUST: 返回/前進恢復滾動位置
• MUST: 連結使用 <a>/<Link> 進行導航（支援 Cmd/Ctrl/中鍵點擊）
• NEVER: 使用 <div onClick> 進行導航

回饋

• SHOULD: 樂觀 UI；回應後進行協調；失敗時回滾或提供復原
• MUST: 確認破壞性操作或提供復原視窗
• MUST: 使用禮貌的 aria-live 進行 Toast 提示和內聯驗證
• SHOULD: 省略號（…）用於開啟後續操作的選項（「重新命名…」）和載入狀態（「載入中…」）

觸控與拖曳

• MUST: 寬鬆的目標、清晰的提示；避免需要精細操作的互動
• MUST: 延遲第一個工具提示；後續對同類元素立即顯示
• MUST: 在模態框/抽屜中使用 overscroll-behavior: contain
• SHOULD: 當抑制頁面橡皮筋彈跳效果時，在 @media (pointer: fine) 內對 <html> 設定 overscroll-behavior: none；為粗指針裝置保留預設的拉動重新整理行為。測試混合觸控裝置：pointer 描述主要輸入方式，none 也會停用滾動鏈和原生的滑動導航
• MUST: 在拖曳過程中，停用文字選取，並對被拖曳的元素設定 inert
• MUST: 拖曳/滑動/捏合/路徑手勢必須有輕觸/點擊和鍵盤替代方案，除非是必要的核心功能
• MUST: 如果看起來可以點擊，就必須可以點擊

自動對焦

• SHOULD: 在桌面上，當只有一個主要輸入時自動對焦；在行動裝置上很少使用

動畫

• MUST: 遵循 prefers-reduced-motion（提供減少動畫版本或停用動畫）
• SHOULD: 優先使用 CSS > Web Animations API > JS 函式庫
• MUST: 僅對合成器友好的屬性（transform、opacity）進行動畫
• NEVER: 對佈局屬性（top、left、width、height）進行動畫
• NEVER: 使用 transition: all——明確列出屬性
• SHOULD: 僅在需要釐清因果關係或增加刻意設計的愉悅感時才使用動畫
• SHOULD: 選擇與變化（大小/距離/觸發方式）相匹配的緩動函數
• MUST: 動畫應可中斷且由輸入驅動；僅對非必要的循環設定自動播放
• MUST: 與其他內容並排顯示且自動播放超過 5 秒的動畫，必須提供暫停、停止或隱藏控制項
• MUST: 正確的 transform-origin（動畫從「物理上」應有的位置開始）
• MUST: SVG 變換應在帶有 transform-box: fill-box 的 <g> 包裝器上進行

佈局

• SHOULD: 視覺對齊；當感知重於幾何時，調整 ±1px
• MUST: 刻意對齊網格/基線/邊緣——不能是偶然放置
• SHOULD: 平衡圖示/文字組合（粗細/大小/間距/顏色）
• MUST: 在行動裝置、筆記型電腦、超寬螢幕（以 50% 縮放模擬超寬螢幕）上驗證
• MUST: 尊重安全區域（env(safe-area-inset-*)）
• MUST: 避免不必要的滾動條；修復溢出問題
• SHOULD: 使用 Flex/Grid 而非 JS 測量來進行佈局

內容與可訪問性

• SHOULD: 優先使用內聯幫助；工具提示是最後的手段
• MUST: 骨架畫面反映最終內容，以避免佈局偏移
• MUST: <title> 與當前上下文匹配
• MUST: 沒有死胡同；始終提供下一步/復原選項
• MUST: 設計空/稀疏/密集/錯誤狀態
• SHOULD: 使用彎曲引號（“ ”）；避免孤行（text-wrap: balance）
• MUST: 數字比較時使用 font-variant-numeric: tabular-nums
• MUST: 冗餘的狀態提示（不僅僅是顏色）；圖示帶有文字標籤
• MUST: 即使視覺上省略了標籤，也必須提供可訪問的名稱
• MUST: 使用 … 字元（而非 ...）
• MUST: 標題使用 scroll-margin-top；提供「跳至內容」連結；分層的 <h1>–<h6>
• MUST: 能妥善處理使用者產生的內容（短/中等/非常長）
• MUST: 使用語言環境感知的日期/時間/數字（Intl.DateTimeFormat、Intl.NumberFormat）
• SHOULD: 在品牌名稱、代碼符號和識別碼上使用 translate="no"，以防止自動翻譯出錯
• MUST: 準確的 aria-label；裝飾性元素設為 aria-hidden
• MUST: 僅含圖示的按鈕須有描述性的 aria-label
• MUST: 在 ARIA 之前優先使用原生語意（button、a、label、table）
• MUST: 多媒體內容應視情況提供字幕/逐字稿/描述；控制項可透過鍵盤操作；裝飾性媒體對輔助技術隱藏
• MUST: 使用不間斷空格：10 MB、⌘ K、品牌名稱

內容處理

• MUST: 文字容器處理長內容（truncate、line-clamp-*、break-words）
• MUST: Flex 子元素需要 min-w-0 以允許截斷
• MUST: 處理空狀態——空字串/陣列不應導致 UI 損壞

效能

• SHOULD: 在 iOS 低功耗模式和 macOS Safari 上進行測試
• MUST: 可靠地測量（停用會影響執行時間的擴充功能）
• MUST: 追蹤並最小化重新渲染（React DevTools/React Scan）
• MUST: 使用 CPU/網路限制進行效能分析
• MUST: 批次處理佈局讀取/寫入；避免重排/重繪
• MUST: 變更操作（POST/PATCH/DELETE）目標 <500ms
• SHOULD: 優先使用非受控輸入；受控輸入應確保每次按鍵的成本低廉
• MUST: 虛擬化大型列表（超過 50 個項目）
• MUST: 預載入折疊層以上的圖片；其餘部分延遲載入
• MUST: 防止 CLS（明確指定圖片尺寸）
• SHOULD: 為 CDN 網域使用 <link rel="preconnect">
• SHOULD: 關鍵字型：使用帶 font-display: swap 的 <link rel="preload" as="font">
• SHOULD: 使用 <video autoplay muted loop playsinline> 取代動畫 GIF；提供靜態/減少動畫的替代方案
• SHOULD: 簡短的非必要循環應包含 Safari H.264 MP4 <picture> 來源、prefers-reduced-motion 媒體條件以及靜態備份方案

暗色模式與主題

• MUST: 深色主題時在 <html> 上使用 color-scheme: dark
• SHOULD: <meta name="theme-color"> 與頁面背景匹配
• MUST: 原生 <select>：明確指定 background-color 和 color（Windows 修復）

Hydration

• MUST: 帶有 value 屬性的輸入需要 onChange（或使用 defaultValue）
• SHOULD: 保護日期/時間渲染免受 Hydration 不匹配的影響

設計

• SHOULD: 分層陰影（環境光 + 直接光）
• SHOULD: 透過半透明邊框和陰影實現清晰的邊緣
• SHOULD: 嵌套圓角：子元素 ≤ 父元素；同心
• SHOULD: 色調一致性：邊框/陰影/文字的顏色傾向背景色調
• MUST: 可訪問的圖表（色盲友好色板）
• MUST: 滿足對比度要求——優先使用 APCA 而非 WCAG 2
• MUST: 在 :hover/:active/:focus 狀態下增加對比度
• SHOULD: 使瀏覽器 UI 與背景匹配
• SHOULD: 避免深色漸層色帶（必要時使用背景圖片）