Communitygithub.com

fresh-eyes

建立並審查網頁產品的 UI(應用螢幕、儀表板、設定、表格、表單、引導流程、空狀態、錯誤狀態,以及銷售產品的登陸頁、首頁和定價頁),使其讀起來像是出自細心的人之手,而非範本。每個畫面都根據使用者的任務和真實內容建構,透過實際渲染和另一雙眼睛檢查,符合 WCAG 2.2 AA 標準,且不含機器生成的痕跡。

fresh-eyes 是什麼?

這個 AI 技能(skill)專注於設計與審查網頁應用程式的 UI,強調以使用者為中心的流程和真實內容。它透過「理解、設計前決定、先寫文字、依序建構、渲染檢查、新鮮眼光、修正並停止」七步驟循環,確保每個畫面都清晰、易用且無機器感。此技能支援 Claude Code、Cursor 等開發工具,要求 Node 20 以上環境執行腳本,並整合 Playwright 進行跨瀏覽器渲染檢查。它可處理從簡單的元件到完整的頁面設計與審查,特別適用於 SaaS 產品、儀表板、設定頁等;但不適用於 Logo、簡報或原生手機 App。技能的核心在於模擬真實使用者體驗,並透過「新鮮眼光」子代理(subagent)或自我檢視,驗證設計意圖是否達成,最終產出符合 WCAG 2.2 AA 可及性標準的成品。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bernardoo-soares/fresh-eyes/tree/HEAD

在你喜歡的 AI 中提問

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

說明文件

新鮮眼光

為將使用這個畫面的使用者而設計,從他們來此要完成的工作以及他們會看到的內容出發。 判斷力優先;參考資料幫助你更敏銳,腳本則協助檢查。沒有什麼比常識更重要:如果一個畫面令人困惑,但沒有任何規則能說明原因,它仍然令人困惑。

以下 <skill> 指的是此技能的目錄:${CLAUDE_SKILL_DIR}(如果顯示為文字變數,請使用讀取此檔案的資料夾)。

設定

腳本需要 Node 20 或更新版本。當腳本表示需要設定時,請執行它輸出的指令:npm --prefix "<skill>" install 和/或 node "<skill>/node_modules/playwright/cli.js" install chromium,這些指令可以在任何資料夾和任何 shell 中執行。

如果腳本在此環境中無法執行(沒有 shell、沒有 Node、無法下載瀏覽器),請不要停下來:使用當前會話中可用的瀏覽器工具擷取螢幕截圖,或逐行根據 references/floor.md 檢查程式碼,並在報告中說明渲染檢查未執行。永遠不要僅根據程式碼就做出視覺檢查的報告。

循環

用於建立和審查。對於審查,請先閱讀 references/review.md:其中的步驟會取代步驟 1 到 4,而改進後的版本會是原始版本的副本,除非對方要求修改他們的檔案。

  1. 理解。 誰會使用這個畫面?為了什麼工作?多常使用?在什麼裝置上?使用什麼真實內容?如果專案有 DESIGN-CONTEXT.md 請閱讀它(references/design-context.md)。如果沒有,則從程式碼、文案和請求中推斷,並記錄你的假設。不要停下來先訪談使用者。
  2. 在設計樣式之前先決定。 在建立之前,簡短地在你的工作筆記或回覆中寫下:這個畫面只有一個目的;使用者的目光應該首先落在哪裡;在桌面和手機上,第一個畫面必須包含哪些內容以做出主要決定;其他所有元素的順序;唯一的首要操作;你決定省略什麼。舉出這個類別的使用者已經喜歡的兩到三個產品,你將遵循它們的結構,以及這個產品自己的一個標誌性動作(references/modern.md)。這是你的意圖,步驟 6 會驗證它。
  3. 先寫文字。 標題、標籤、按鈕、空狀態和錯誤狀態,使用使用者自己的語言,並基於真實資料(references/words.md)。永遠不要編造數字、姓名、推薦或趨勢;如果沒有真實資料,請使用可見的佔位符。
  4. 依序建構: 結構,然後階層,最後工藝。如果專案有自己的元件和 token,則使用它們(對於使用 shadcn/ui 的 React,請閱讀 references/stacks/react-shadcn.md)。新的視覺系統從 node "<skill>/scripts/tokens.mjs" --accent "<hex>" --out <dir> 開始,它會檢查每一對顏色。
  5. 渲染並檢視。 對於應用程式,啟動它的開發伺服器並傳遞 URL。將 --out 寫入專案外的暫存資料夾:node "<skill>/scripts/render.mjs" <page.html | url> --out <dir>(如果它要求設定或無法執行,請參閱設定);如果頁面需要登入,請加上 --storage-state <file>。它會儲存桌面和手機、淺色和深色的螢幕截圖,並列出它可以測量的問題(對比度、焦點指示、橫向捲動、小型目標、衝突的首要按鈕、邊緣色條、em dash),然後是「肉眼檢查」清單。修正每個問題,或在報告中說明為什麼保留某個問題;審查時,必須修正 floor 問題、色條和 em dash,並將其他可測量的問題列為發現事項。如果它警告淺色和深色看起來相同,請加上 --theme-mode class 重新執行。檢視螢幕截圖,先看四張 -first.png,然後看每個「肉眼檢查」項目:空的清單表示 floor 是乾淨的,不代表畫面是好的。使用壓力內容渲染一次:最長的真實姓名、最大的金額、空的帳戶。
  6. 新鮮眼光。 啟動一個新的子代理(subagent),它與此對話完全無關(不是此對話的分支);如果有的話,使用 first-look 代理類型。它的完整提示是:Read <skill>/agents/first-look.md and follow it. The job: <one sentence>. Images: <absolute paths, first-screen ones first>. Open no other file. 不要添加任何關於你的意圖或你建立/修改的內容。將它的回答與步驟 2 進行比較:錯誤的「這是什麼」、錯誤的第一個點擊、猶豫或「感覺不對勁」都是需要修正的問題;在對一個已正常運作的頁面進行審查時,一個既不阻礙也不誤導工作的猶豫,可以作為可選的建議,而不是必須修正的問題。如果沒有子代理,請僅從第一張螢幕截圖回答 first-look 的問題,然後再重新閱讀你的程式碼。
  7. 修正並停止。 首先用結構(一個標籤、一個列表、一個視覺元素、一個重新分組)來修正每個猶豫;只有當沒有任何其他方法時,才添加一句話。對名稱的懷疑,要用更好的名稱來修正,而不是在名稱下方加一行解釋,而且選單內永遠不需要解釋。最多再進行兩輪步驟 5 和 6,然後說明仍然有待解決的問題。回答 references/modern.md 中測試的三個問題(哪個類別的產品會稱這個為「當前」;標誌性動作在哪裡;這個畫面是否可能屬於任何新創公司),並提出報告。

最簡單的路徑優先。 主要操作在畫面打開時就能立即使用;額外的功能(編輯每一行、批次工具)放在下一層,永遠不會擋在第一個畫面之前(references/structure.md)。

完成,而非簡陋。 避免機器生成的痕跡並非目標。畫面應該看起來像個完成的產品:使用者操作的單元放在它們自己的容器中,圖示和小型視覺元素在它們能傳達意義的地方出現,整個決策過程在第一個畫面上就能完成。一整欄灰色的句子也是一種失敗(references/hierarchy.md)。

根據請求調整規模。 僅修改文字(標籤、錯誤訊息):步驟 1 到 3。一個元件或一個小修正:步驟 1 到 5。一個完整的畫面或審查:全部七個步驟。

決定大多數畫面的問題

提問閱讀參考資料
誰來這裡、多常來、為了什麼工作?密度應該如何(姿態)?事物如何分組、命名和到達?references/structure.md
目光應該首先落在哪裡?是否只有一個首要操作?每個數字是否都有其比較對象、單位和日期?references/hierarchy.md
初次使用者能否分辨這是什麼、他們在哪裡以及下一步該做什麼?references/clarity.md
每個區域處於哪個狀態,而且是否恰好只有一個狀態?當使用者操作錯誤時,是復原還是確認?references/states.md
文字是否以使用者習慣的方式為事物命名?每個錯誤訊息是否說明了修正方法?references/words.md
字體、間距、色彩、深色模式和動畫是否經過深思熟慮?references/craft.md
它看起來像個完成的產品,還是像一份文件?第一個畫面是否容納了決策?references/hierarchy.md
它看起來像當代的產品,而不像生成的?它的標誌性動作是什麼?references/modern.md
這個畫面是否可能屬於任何產品?可以移除什麼?references/tells.md
這是登陸頁、首頁還是定價頁?訪客必須做出什麼決定?references/landing.md
鍵盤操作、對比度、重新排版、標籤名稱、目標大小,在淺色和深色主題下都符合嗎?references/floor.md

當你面前的畫面上出現了某個問題時,才去閱讀對應的參考資料,不需要一次讀完所有的。每個卡片中都有一個決定、一個做法、為什麼及其來源、要注意什麼,以及何時不適用(除非)。例外情況與規則本身同等重要。

不可動搖的原則

  • 僅使用真實內容:不編造數字、人物、引言或歷史。
  • 可及性基準(references/floor.md)在淺色和深色模式下都必須成立。
  • 不要在元素的一側邊緣使用有色色條作為強調色,不要在文案中使用 em dash(references/tells.md)。
  • 在審查時,保留頁面上已有的每一筆資料和每一個操作;可以移動或降級,但不要刪除。
  • 當沒有任何事物對使用者造成負擔時,「無需修改」就是一個完整的審查。永遠不要為了個人品味而修改。

報告

用簡潔的語言撰寫:

  • 你建立或修改了什麼,每一點都要連結到使用者的工作以及為他們節省了什麼;在審查中,每一項修改,無論多小(大小、間距、顏色),都以簡短的表格說明「原本」、「現在」以及為使用者節省了什麼:你沒有說明的修改就是違背承諾;
  • 你做出的假設,最多三項,以及如果某項假設錯誤會導致什麼改變;
  • 你檢查了什麼:修改前後的渲染問題,以及「新鮮眼光」的結果與你的意圖相比如何;
  • 你沒有測試什麼(手勢操作、真實手機、Safari、螢幕閱讀器),以及渲染檢查是否執行。

不要使用分數、ID 或規則編號。如果專案沒有 DESIGN-CONTEXT.md,可以根據你的假設主動提供一份。

相關技能