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
- vaferkhanom/Website-skillstheir own version, first seen Nov 16, 2026
- FimawLLC/fimaw-skillstheir own version, first seen Nov 15, 2026
- alexj11324/Mikkatheir own version, first seen Nov 15, 2026
- QiYueran-source/waymarktheir own version, first seen Nov 15, 2026
- joaoguirunas/team-ostheir own version, first seen Nov 15, 2026
- laguagu/claude-code-nextjs-skillstheir own version, first seen Nov 14, 2026
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-citySkillcanvas-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
SKB3002Skillintelligent-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
VercelSkillvercel-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-itSkillnuqs
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-citySkillpose-library-design
Design reusable 2D character pose libraries, action cycles, and expression states for data-driven animation.
Also in 4 projects that use this
stophobiaSkillsurprise-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
Other versions176 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 176
- bytedance/deer-flow★ 85ksame name
- calesthio/OpenMontage★ 81ksame name
- OpenMontageInc/OpenMontage★ 81ksame name
- multica-ai/multica★ 56ksame name
- moeru-ai/airi★ 51ksame name
- vercel-labs/agent-skills★ 33ksame name
- awesome-dsh-plugin/awesome-dsh-plugin★ 25ksame name
- open-metadata/OpenMetadata★ 16ksame name
- trycompai/crm★ 12ksame name
- mengxi-ream/read-frog★ 10ksame name
166 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- pi-agent/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- angular-primengSkill
- architecture-auditSkill
- build-error-resolverSkill
- cis-design-systemSkill
- doubt-driven-developmentSkill
- fastapi-patternsSkill
- humanizer-enSkill
- humanizer-zh-twSkill
- interface-designSkill
- interview-meSkill
- openspecSkill
- quality-gateSkill
- refactor-cleanerSkill
- security-radarSkill
- security-reviewerSkill
- security-scanSkill
- sketchSkill
- ui-ux-pro-maxSkill
- webapp-uatSkill
The file
Files
web-design-guidelines
對前端原始碼做介面規則審查。規則全部寫在這份檔案裡,不從網路抓任何規則或指令;要改規則就改這份檔案並走 PR。
和其他 skill 的分工:
interface-design、cis-design-system管設計層(間距、色彩角色、設計系統一致性)。quality-gate管整站上線前的檢查,webapp-uat管部署後逐畫面驗收。- 這份只看程式碼:讀檔、對規則、回報行號。不需要跑起來。
流程
- 取得要審查的檔案。有參數就用參數(檔案或 glob);沒有就問使用者要看哪些檔案,不要自己掃整個 repo。
- 逐檔讀完整內容,包含
<template>、<script>、<style>,以及它直接 import 的共用元件(只在判斷需要時)。 - 對照下面的規則。每條命中都要能指到具體行號;指不到行號的不報。
- 依「輸出格式」回報。沒有問題就明講沒有,不要為了湊數降低標準。
元件庫已處理的行為不重複報:PrimeVue / PrimeNG 的 Dialog、Menu、DataTable 等內建焦點管理與鍵盤操作,只在專案覆寫或手刻同類元件時才檢查。
規則
等級:E 會讓部分使用者無法完成操作,必修;W 明顯影響體驗,應修;I 建議。
K 鍵盤與互動
| 代碼 | 等級 | 規則 |
| K1 | E | 可點擊的元素用 <button>、<a> 或 NuxtLink / routerLink。<div @click>、<span (click)> 沒有 role、tabindex="0" 與鍵盤事件就是違規 |
| K2 | W | 換頁用連結,執行動作用按鈕。用 router.push 包在按鈕裡的導覽無法開新分頁、無法複製網址 |
| K3 | E | 不可移除焦點外框而沒有替代樣式(outline: none / outline: 0)。自訂樣式用 :focus-visible |
| K4 | E | 只有圖示的按鈕要有 aria-label;圖示本身加 aria-hidden="true" |
| K5 | E | 手刻的對話框、抽屜、下拉選單:開啟時焦點移入、Esc 可關閉、關閉後焦點回到觸發元素、背景不可被 Tab 到 |
| K6 | W | 觸控目標至少 24×24 CSS px,行動版主要操作建議 44×44。圖示太小就加 padding,不是放大圖示 |
| K7 | W | 不以 hover 作為唯一的顯示方式(觸控與鍵盤沒有 hover)。hover 才出現的操作要有 focus 或常駐的替代 |
| K8 | E | viewport 不可設 user-scalable=no 或 maximum-scale=1 |
| K9 | W | 刪除等破壞性操作要有確認或可復原,確認框的預設焦點不放在破壞性按鈕上 |
| K10 | I | tabindex 只用 0 或 -1,不用正數打亂順序 |
F 表單
| 代碼 | 等級 | 規則 |
| F1 | E | 每個輸入欄位有對應的 <label for>,或 aria-label / aria-labelledby。placeholder 不算 label |
| F2 | W | type、inputmode、autocomplete、name 要給對:email、tel、one-time-code、current-password / new-password |
| F3 | W | 不擋貼上(密碼、驗證碼欄位尤其常見) |
| F4 | E | 錯誤訊息顯示在欄位旁,以 aria-describedby 連到欄位並設 aria-invalid。不可只靠紅框表示錯誤 |
| F5 | W | 送出失敗時把焦點移到第一個錯誤欄位 |
| F6 | W | 欄位包在 <form> 裡並處理 submit,讓 Enter 可送出;送出中停用按鈕防重複送出,按鈕文字保留 |
| F7 | I | 驗證在離開欄位或送出時觸發,不在使用者打第一個字時就報錯 |
| F8 | I | 行動版輸入欄位字級不小於 16px,避免 iOS 自動放大頁面 |
| F9 | W | 有未儲存變更時離開頁面要提醒(onBeforeRouteLeave / CanDeactivate) |
C 內容與語意
| 代碼 | 等級 | 規則 |
| C1 | W | 標題層級不跳級,一頁一個 <h1>。為了字級選標籤的改用 class |
| C2 | E | <img> 要有 alt;純裝飾用 alt="" |
| C3 | W | 圖片給 width / height(或 aspect-ratio),避免載入後版面跳動 |
| C4 | E | 訊息不可只靠顏色傳達(狀態燈、圖表圖例、必填標記要有文字或圖示) |
| C5 | W | 使用者產生的長字串要處理溢出:truncate、break-words 或 min-width: 0;flex 子項最容易漏 |
| C6 | W | 列表與資料區塊要涵蓋載入中、空、錯誤三種狀態,不能只寫有資料的情況 |
| C7 | W | 介面文字走 i18n,不寫死在 template;不用字串相加拼句子;日期、數字、金額用 Intl 或 i18n 的格式化 |
| C8 | W | 非同步出現的訊息(toast、表單送出結果)要在 aria-live 區域內 |
| C9 | I | 需要對齊比較的數字欄用 font-variant-numeric: tabular-nums |
| C10 | W | 用語意標籤:<nav>、<main>、<header>、<table> 配 <th scope>。用 <div> 排出來的表格算違規 |
M 動畫
| 代碼 | 等級 | 規則 |
| M1 | W | 位移、縮放、視差等動畫要在 prefers-reduced-motion: reduce 下關閉或改成淡入 |
| M2 | W | 動畫只動 transform 與 opacity。動 width、height、top、left 會觸發重排 |
| M3 | I | 不寫 transition: all,列出實際要過渡的屬性 |
| M4 | W | 動畫期間不可擋住輸入;使用者再次操作時要能中斷 |
P 效能
| 代碼 | 等級 | 規則 |
| P1 | W | 可能超過數百列的列表要虛擬化(PrimeVue VirtualScroller、DataTable 的 virtualScrollerOptions)或分頁 |
| P2 | W | v-for / *ngFor 要有穩定的 key(trackBy);列表會增刪或重排時不可用 index |
| P3 | W | 首屏以下的圖片加 loading="lazy";首屏主圖不要 lazy |
| P4 | W | Nuxt 的資料抓取用 useFetch / useAsyncData,不在 onMounted 裡 fetch(會多一輪瀑布且 SSR 拿不到資料) |
| P5 | W | template 裡不直接呼叫昂貴函式,改用 computed / pipe;watch 不要 deep: true 監看大物件 |
| P6 | E | 會造成 hydration mismatch 的值(Date.now()、Math.random()、window / localStorage)不可在 SSR 階段直接渲染,放進 onMounted 或 <ClientOnly> |
| P7 | I | 輸入觸發的搜尋、resize、scroll 處理要 debounce 或 throttle |
S 狀態與導覽
| 代碼 | 等級 | 規則 |
| S1 | W | 分頁、篩選、排序、分頁籤的狀態放進 URL query,重新整理與分享連結後要還原得回來 |
| S2 | W | 樂觀更新失敗時要還原畫面並告知使用者 |
| S3 | I | 載入用骨架屏佔位;短於約 300ms 的請求不閃 spinner |
| S4 | W | 非同步操作要處理競態:連續觸發時以最後一次為準(取消前一個請求或比對序號) |
T 主題
| 代碼 | 等級 | 規則 |
| T1 | W | 顏色用設計 token 或 CSS 變數,不在元件裡寫死色碼(對照 cis-design-system) |
| T2 | W | 文字對比至少 4.5:1,大字與介面元件邊界 3:1。看得出的寫死組合(淺灰字配白底)直接報 |
| T3 | I | 支援深色模式時設定 color-scheme,讓原生表單控制項與捲軸跟著切換 |
X 介面層的安全
| 代碼 | 等級 | 規則 |
| X1 | E | Vue 的 v-html 不會淨化內容,來源是使用者輸入或 API 時必須先經 DOMPurify 之類的淨化。Angular 的 [innerHTML] 會自動淨化,不用報;要報的是 bypassSecurityTrustHtml 等 bypassSecurityTrust* 用在非固定內容上 |
| X2 | W | target="_blank" 的外部連結加 rel="noopener noreferrer" |
| X3 | E | token、金鑰不可寫進 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。
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
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.

