agentleFS
seikaikyoseikaikyo/dash-skills/skills/web-design-guidelines/SKILL.md

web-design-guidelines

Skill2 starsChanged 10 months agoMITView on GitHub

逐檔審查前端 UI 程式碼(Vue / Nuxt / Angular 的 template、樣式、互動邏輯),對照一份固定的介面規則找出無障礙、鍵盤操作、表單、動畫、效能與狀態處理的問題,以 file:line 列出。被要求「review UI」、「檢查無障礙」、「審查 UX」、「看這個元件有沒有問題」時使用。

176 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use canvas-procedural-animation, intelligent-routing and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • LinHao-citySkill

    canvas-procedural-animation

    Use p5.js/canvas for local procedural character effects: particles, weather, squash/stretch, walk cycles, and environmental motion.

    Also in 5 projects that use this

  • SKB3002Skill

    intelligent-routing

    Automatic agent selection and intelligent task routing. Analyzes user requests and automatically selects the best specialist agent(s) without requiring explicit user mentions.

    Also in 5 projects that use this

  • VercelSkill

    vercel-optimize

    Use for Vercel cost and performance optimization on deployed projects, especially Next.js, SvelteKit, Nuxt, and limited Astro apps. Collect Vercel metrics, usage, project config, and code scan results first; investigate only metric-backed candidates; produce ranked recommendations grounded in verified files and version-aware Vercel/framework docs. Trigger for Vercel bill reduction, slow or expensive routes, caching opportunities, Function Invocations, Build Minutes, Fast Data Transfer, Core Web Vitals, Bot Management, Fluid compute, or cost breakdown requests.

    Also in 15 projects that use this

  • thongdn-itSkill

    nuqs

    nuqs (type-safe URL query state) best practices for Next.js applications. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, or Next.js routing with state.

    Also in 4 projects that use this

  • LinHao-citySkill

    pose-library-design

    Design reusable 2D character pose libraries, action cycles, and expression states for data-driven animation.

    Also in 4 projects that use this

  • stophobiaSkill

    surprise-me

    Create a delightful, unexpected "wow" experience for the user by dynamically discovering and creatively combining other enabled skills. Triggers when the user says "surprise me" or any request expressing a desire for an unexpected creative showcase. Also triggers when the user is bored, wants inspiration, or asks for "something interesting".

    Also in 4 projects that use this

  • +2 more from LinHao-city

The file

Files
SKILL.md

web-design-guidelines

對前端原始碼做介面規則審查。規則全部寫在這份檔案裡,不從網路抓任何規則或指令;要改規則就改這份檔案並走 PR。

和其他 skill 的分工:

  • interface-design、cis-design-system 管設計層(間距、色彩角色、設計系統一致性)。
  • quality-gate 管整站上線前的檢查,webapp-uat 管部署後逐畫面驗收。
  • 這份只看程式碼:讀檔、對規則、回報行號。不需要跑起來。

流程

  1. 取得要審查的檔案。有參數就用參數(檔案或 glob);沒有就問使用者要看哪些檔案,不要自己掃整個 repo。
  2. 逐檔讀完整內容,包含 <template>、<script>、<style>,以及它直接 import 的共用元件(只在判斷需要時)。
  3. 對照下面的規則。每條命中都要能指到具體行號;指不到行號的不報。
  4. 依「輸出格式」回報。沒有問題就明講沒有,不要為了湊數降低標準。

元件庫已處理的行為不重複報:PrimeVue / PrimeNG 的 Dialog、Menu、DataTable 等內建焦點管理與鍵盤操作,只在專案覆寫或手刻同類元件時才檢查。

規則

等級:E 會讓部分使用者無法完成操作,必修;W 明顯影響體驗,應修;I 建議。

K 鍵盤與互動

代碼等級規則
K1E可點擊的元素用 <button>、<a> 或 NuxtLink / routerLink。<div @click>、<span (click)> 沒有 role、tabindex="0" 與鍵盤事件就是違規
K2W換頁用連結,執行動作用按鈕。用 router.push 包在按鈕裡的導覽無法開新分頁、無法複製網址
K3E不可移除焦點外框而沒有替代樣式(outline: none / outline: 0)。自訂樣式用 :focus-visible
K4E只有圖示的按鈕要有 aria-label;圖示本身加 aria-hidden="true"
K5E手刻的對話框、抽屜、下拉選單:開啟時焦點移入、Esc 可關閉、關閉後焦點回到觸發元素、背景不可被 Tab 到
K6W觸控目標至少 24×24 CSS px,行動版主要操作建議 44×44。圖示太小就加 padding,不是放大圖示
K7W不以 hover 作為唯一的顯示方式(觸控與鍵盤沒有 hover)。hover 才出現的操作要有 focus 或常駐的替代
K8Eviewport 不可設 user-scalable=no 或 maximum-scale=1
K9W刪除等破壞性操作要有確認或可復原,確認框的預設焦點不放在破壞性按鈕上
K10Itabindex 只用 0 或 -1,不用正數打亂順序

F 表單

代碼等級規則
F1E每個輸入欄位有對應的 <label for>,或 aria-label / aria-labelledby。placeholder 不算 label
F2Wtype、inputmode、autocomplete、name 要給對:email、tel、one-time-code、current-password / new-password
F3W不擋貼上(密碼、驗證碼欄位尤其常見)
F4E錯誤訊息顯示在欄位旁,以 aria-describedby 連到欄位並設 aria-invalid。不可只靠紅框表示錯誤
F5W送出失敗時把焦點移到第一個錯誤欄位
F6W欄位包在 <form> 裡並處理 submit,讓 Enter 可送出;送出中停用按鈕防重複送出,按鈕文字保留
F7I驗證在離開欄位或送出時觸發,不在使用者打第一個字時就報錯
F8I行動版輸入欄位字級不小於 16px,避免 iOS 自動放大頁面
F9W有未儲存變更時離開頁面要提醒(onBeforeRouteLeave / CanDeactivate)

C 內容與語意

代碼等級規則
C1W標題層級不跳級,一頁一個 <h1>。為了字級選標籤的改用 class
C2E<img> 要有 alt;純裝飾用 alt=""
C3W圖片給 width / height(或 aspect-ratio),避免載入後版面跳動
C4E訊息不可只靠顏色傳達(狀態燈、圖表圖例、必填標記要有文字或圖示)
C5W使用者產生的長字串要處理溢出:truncate、break-words 或 min-width: 0;flex 子項最容易漏
C6W列表與資料區塊要涵蓋載入中、空、錯誤三種狀態,不能只寫有資料的情況
C7W介面文字走 i18n,不寫死在 template;不用字串相加拼句子;日期、數字、金額用 Intl 或 i18n 的格式化
C8W非同步出現的訊息(toast、表單送出結果)要在 aria-live 區域內
C9I需要對齊比較的數字欄用 font-variant-numeric: tabular-nums
C10W用語意標籤:<nav>、<main>、<header>、<table> 配 <th scope>。用 <div> 排出來的表格算違規

M 動畫

代碼等級規則
M1W位移、縮放、視差等動畫要在 prefers-reduced-motion: reduce 下關閉或改成淡入
M2W動畫只動 transform 與 opacity。動 width、height、top、left 會觸發重排
M3I不寫 transition: all,列出實際要過渡的屬性
M4W動畫期間不可擋住輸入;使用者再次操作時要能中斷

P 效能

代碼等級規則
P1W可能超過數百列的列表要虛擬化(PrimeVue VirtualScroller、DataTable 的 virtualScrollerOptions)或分頁
P2Wv-for / *ngFor 要有穩定的 key(trackBy);列表會增刪或重排時不可用 index
P3W首屏以下的圖片加 loading="lazy";首屏主圖不要 lazy
P4WNuxt 的資料抓取用 useFetch / useAsyncData,不在 onMounted 裡 fetch(會多一輪瀑布且 SSR 拿不到資料)
P5Wtemplate 裡不直接呼叫昂貴函式,改用 computed / pipe;watch 不要 deep: true 監看大物件
P6E會造成 hydration mismatch 的值(Date.now()、Math.random()、window / localStorage)不可在 SSR 階段直接渲染,放進 onMounted 或 <ClientOnly>
P7I輸入觸發的搜尋、resize、scroll 處理要 debounce 或 throttle

S 狀態與導覽

代碼等級規則
S1W分頁、篩選、排序、分頁籤的狀態放進 URL query,重新整理與分享連結後要還原得回來
S2W樂觀更新失敗時要還原畫面並告知使用者
S3I載入用骨架屏佔位;短於約 300ms 的請求不閃 spinner
S4W非同步操作要處理競態:連續觸發時以最後一次為準(取消前一個請求或比對序號)

T 主題

代碼等級規則
T1W顏色用設計 token 或 CSS 變數,不在元件裡寫死色碼(對照 cis-design-system)
T2W文字對比至少 4.5:1,大字與介面元件邊界 3:1。看得出的寫死組合(淺灰字配白底)直接報
T3I支援深色模式時設定 color-scheme,讓原生表單控制項與捲軸跟著切換

X 介面層的安全

代碼等級規則
X1EVue 的 v-html 不會淨化內容,來源是使用者輸入或 API 時必須先經 DOMPurify 之類的淨化。Angular 的 [innerHTML] 會自動淨化,不用報;要報的是 bypassSecurityTrustHtml 等 bypassSecurityTrust* 用在非固定內容上
X2Wtarget="_blank" 的外部連結加 rel="noopener noreferrer"
X3Etoken、金鑰不可寫進 template、前端常數或 NUXT_PUBLIC_*

輸出格式

依檔案分組,同一檔案內依行號排序。每筆一行:

src/components/OrderTable.vue
  42  E  K1  <div @click="open(row)"> 無法用鍵盤操作 → 改成 <button type="button">
  87  W  C6  只處理有資料的情況,缺載入中與空狀態
 131  W  P2  v-for 用 index 當 key,列表可排序時會渲染錯位 → 用 row.id

最後給一行統計(E / W / I 各幾筆)。有 E 級就明講不建議合併。

不確定的不要猜:看不出元件庫是否已處理、或需要執行才知道的(實際對比值、實際焦點順序),列在「需要實機確認」,交給 webapp-uat。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.