Communitygithub.com

前端開發

用於建置、審查或修復瀏覽器 UI,例如頁面、元件、表單、客戶端狀態、圖表、列印或 PDF 檢視、無障礙性或網頁效能(Core Web Vitals、套件大小、渲染緩慢)。不適用於視覺方向、版面評論或品牌(請使用 `designer` 或 `visual-design`)。不適用於原生或 React Native 應用程式(請使用 `mobile`)。

前端開發 是什麼?

「前端開發」技能為建置真實使用者(包含使用鍵盤、螢幕閱讀器、慢速手機和印表機)的瀏覽器 UI 提供了一套關鍵標準。它涵蓋了當 UI「看起來完成」時經常被忽略的規則,例如使用正確的語意元素、實作所有非同步檢視的四種狀態(載入中、錯誤、空資料、有資料)、避免單獨使用顏色傳遞訊息,以及將可分享的狀態(如篩選條件、搜尋詞)放在 URL 中。此技能支援所有現代瀏覽器環境,包含 Claude Code、Cursor、Codex 等平台,並提供關於狀態管理位置、圖表實作、列印/PDF 檢視、效能優化目標(LCP ≤ 2.5 秒、INP ≤ 200 毫秒、CLS ≤ 0.1)以及常見陷阱的詳細指引。最後,它包含一個全面的驗證清單,用於測試無障礙性、鍵盤操作、效能預算和各狀態下的行為,確保 UI 在各種真實場景中都能可靠運作。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/heliacon/claude-skills/tree/HEAD/skills/frontend

在你喜歡的 AI 中提問

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

說明文件

前端開發 是做什麼的?

供真實使用者(使用鍵盤、螢幕閱讀器、慢速手機和印表機)瀏覽的瀏覽器 UI 標準。 以下規則是在 UI「看起來完成」時常常被跳過的項目。

最重要的規則

  1. 使用具有含義的元素。 <button> 用於動作,<a href> 用於導航,每個欄位都需要 <label>,表格資料使用 <table>。帶有點擊處理器的 <div> 無法聚焦、沒有角色,且對輔助技術不可見。ARIA 僅用於填補原生元素無法涵蓋的缺口。
  2. 每個非同步檢視都有四種狀態: 載入中、錯誤、空資料和有資料。在宣稱檢視完成之前,先寫好這四種狀態。空白區域即為錯誤。
  3. 絕不捏造資料。 缺失的期間應顯示為空缺或「無資料」標籤,絕不能顯示為零或插值線。預測值必須始終與實際值明顯區分。
  4. 絕不單獨使用顏色來傳遞訊息。 每個用顏色編碼的狀態也必須包含文字或具有可存取名稱的圖示。否則,灰階列印和色盲讀者將無法獲得任何資訊。
  5. 可分享的狀態應存在於 URL 中。 篩選條件、分頁標籤、搜尋詞、選取的 ID。返回、重新整理和分享都必須保留這些狀態。短暫狀態(懸停、開啟的工具提示)不應放入 URL。
  6. 由多個狀態推導出的值,應使用一個函數,並在任一狀態變更時呼叫。 切勿在屬於其中一個狀態的回呼函數內部計算它。範例:一個由截止日期和群組篩選器建構的下載連結,只在截止日期的擷取回呼中重建,因此在篩選器變更後,匯出功能會默默地指向整個清單。
  7. 從 320 CSS 像素寬度開始響應式設計。 無水平頁面滾動、無內容裁剪、文字可縮放至 200%。請同時在手機寬度和您設計的桌面寬度上進行測試。
  8. 根據需求選擇工具。 在現有儲存庫中,遵循已有的框架和建置工具。對於小型新頁面或內部工具,在引入建置流程之前,請先考慮純 HTML、CSS 和少量 JavaScript;當狀態管理確實需要時才使用框架。

何時不使用

  • 選擇視覺方向、字體或色板:請使用 designer 和 visual-design 技能。
  • 原生 iOS、Android 或 React Native:請使用 mobile 技能(Swift 程式碼使用 swift)。
  • API 形狀和伺服器端點:請使用 api-design 和 backend-patterns 技能。
  • 深入的測試技術:請使用 tdd 和 testing-strategy 技能。

狀態存放位置

在撰寫元件狀態之前決定。從本地開始,僅在有明確理由時才升級。

狀態存放位置範例
本地 UI元件狀態模態框開啟、輸入草稿、懸停
兄弟元件共享最近的共同父元件兩個面板讀取的作用中分頁
伺服器資料伺服器快取庫(TanStack Query、SWR)或框架的載入器API 回應、分頁、重新擷取
應用程式全域客戶端狀態小型 store(僅在需要時)已登入使用者、通知佇列
可分享的檢視狀態URL 查詢或路由篩選條件、搜尋、選取的 ID
跨重新整理持久化(每裝置)localStorage偏好設定、未發送的草稿

僅在以下情況升級:兩個不相關的元件需要相同狀態(提升它,或使用伺服器快取);狀態必須在重新整理後存活(URL 或 storage);資料來自伺服器(使用伺服器快取,而非全域 store)。將伺服器資料複製到全域 store 會導致資料過時,並重複載入和錯誤邏輯。

圖表、列印與簡化檢視

  • 圖表:前端和後端共享一個顏色對照表、明確的空資料狀態、誠實的空白缺口、一個 HTML 圖例。在建置或修改圖表之前,請閱讀 references/charts.md。
  • 列印或 PDF:在建置可列印檢視之前,請閱讀 references/print.md。Canvas 在沒有其所描述的擷取步驟時,無法可靠列印。
  • 為非技術讀者設計的簡化或唯讀檢視:無編輯控制項、寬裕的文字和目標點擊大小、同時使用顏色和文字表示狀態、從資料計算的淺顯易懂摘要、少數幾個畫面,以及使用標題數字搭配簡短句子,而非原始表格。

效能

按影響程度依序修復:首先是請求瀑布,然後是傳送的 JavaScript 量,接著是伺服器回應時間,最後是互動期間的主執行緒工作,微優化放在最後。目標:在實際訪問量的第 75 百分位數下,LCP 2.5 秒或更少、INP 200 毫秒或更少、CLS 0.1 或更少。當頁面載入緩慢時、在加入重量級依賴項之前,或在啟動具有效能目標的專案之前,請閱讀 references/performance.md。

常見陷阱

  • 渲染路徑是熱迴圈。 元件主體或計算屬性的 getter 在每次懸停和每次不相關的狀態變更時都會執行。在此進行大量推導會導致主執行緒阻塞,第一個症狀可能是其他地方出現不穩定的測試。先進行去重,然後對上游輸入進行記憶化(memoise)。
  • 未宣告的 CSS 自訂屬性會靜默失敗。 當 token 是 --font-mono 時,使用 var(--mono) 會使宣告在計算值時無效:屬性會繼承,且不會報錯。在簡寫屬性中(font: 400 10px/1 var(--mono)),字型大小和行高也會失效。請為 var() 提供後備值,或對照產生的樣式表檢查已宣告的 token 與被引用的 token。
  • 圖表的高度應設定在其外層容器上。 在 canvas 上設定高度會與函式庫的調整大小邏輯衝突,導致圖表在每次調整大小時都會變大。
  • 自訂小工具中的焦點管理是您的責任。 開啟對話框時應將焦點移入其中;關閉時應將焦點返回觸發元素;按下 Escape 鍵應關閉對話框。優先使用原生的 <dialog> 元素。使用 innerHTML 重建標記會遺失焦點。
  • 使用 outline: none 但未提供替代方案 會移除鍵盤使用者唯一的視覺提示。請改用 :focus-visible 來設定焦點樣式。
  • 僅圖示的按鈕需要名稱(使用 aria-label 或視覺上隱藏的文字)。
  • 僅在客戶端擷取後才存在的內容 在弱裝置上載入緩慢、在 JavaScript 失敗時呈現空白,且對爬蟲程式較不友善。在技術棧允許的情況下,應在伺服器端渲染有意義的內容。
  • 未設定尺寸的媒體會導致版面佈局位移。 在圖片、影片和嵌入內容上設定 width 和 height(或 aspect-ratio)。切勿對首屏最大的可視元素進行延遲載入。
  • 手動實作的下拉選單、分頁標籤和滑桿 需要符合 WAI-ARIA 創作實踐中的完整鍵盤模型。使用原生元素幾乎總是更經濟的選擇。
  • 手寫的虛擬 DOM 可能會使測試失效。 如果虛擬實作每次查詢都回傳一個新的物件,那麼寫入其中的每個屬性(href、disabled、value)都會丟失,且針對它的任何斷言都無法失敗。請還原該功能,並要求在信任測試之前,測試必須能夠失敗。
  • 使用固定的 CDN 版本,絕不要使用不固定的版本。 不固定的腳本會在您不知情且沒有提交記錄的情況下變更。

驗證

在新增工具之前,先使用專案已有的工具(其測試執行器、linter、型別檢查器、無障礙工具)來驗證。

  • 測試、lint 和型別檢查通過。任何新測試都應在還原該功能後能看到測試失敗。
  • 頁面已渲染並檢視過,包括手機寬度和桌面寬度。在可能的情況下,提供運行的預覽以及螢幕截圖給審查者。
  • 僅使用鍵盤:每個控制項都可到達、可操作且有可見的焦點;順序與視覺順序相符;無焦點陷阱。
  • 自動化無障礙審計(axe、Lighthouse 或專案的工具)無新增違規。使用工具檢查對比度:正文文字 4.5:1,大型文字和 UI 元件邊框 3:1(WCAG AA)。
  • 透過強制觸發,分別展示載入中、錯誤、空資料和有資料狀態。
  • 可分享的狀態在重新整理和返回後仍然存在。
  • 主控台在載入和使用期間無任何錯誤和警告。
  • 如果變更新增了依賴項或觸及了重量級檢視(使用套件分析器、限制速率的效能分析),則檢查效能預算。
  • 如果頁面可列印,則檢查列印預覽。

對於審查,請按檔案回報發現的問題,指出違反的規則和解決方案,並按嚴重程度排序,最嚴重的優先。

Individual skills in this repo

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

相關技能