Communitygithub.com

ShortArrow/interface-design

決定螢幕的外觀與行為,當使用者即將做出未經審查的決定時觸發:關於版面、顏色、位置、圖表繪製、面板寬度、檢視分割等問題,並將測量標準與公開規範作為依據。

interface-design 是什麼?

這項技能旨在將介面設計的決策從主觀偏好轉化為客觀測量與標準。它針對開發者與 AI 代理在提出任何關於外觀、佈局或互動的問題之前使用,確保先以 WCAG 2.2、設計系統、axe-core 與 Lighthouse 等工具進行測量與驗證。技能明確指出,對比度、目標尺寸、重排寬度、焦點可見性與資訊順序等都有可測量的門檻,而非純粹的品味問題。它支援在瀏覽器環境中進行螢幕截圖、視窗調整與焦點順序檢查,並要求所有外觀宣稱都附上測量結果與視埠尺寸。最終,只有三類問題值得留給使用者:未確定的目標市場或受眾、品牌約束(但仍需符合對比度標準)、以及已從兩方面充分測量但證據無法取捨的權衡。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ShortArrow/skills/tree/HEAD/skills/interface-design

在你喜歡的 AI 中提問

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

說明文件

介面設計

關於螢幕的問題,不是品味的問題。 對比度有比率、目標有尺寸、 重排有必須仍能運作的寬度、 版面有資訊順序,取決於使用者先做什麼。 這些都由測量與公開標準決定, 因此將它們作為「你偏好哪個」交給使用者, 是在消耗他們的注意力於代理應完成的工作上。

測量後留下的才是真正的問題, 而這項技能的目的就是讓那個殘留的部分變小,並附上證據。 own-the-call 則規範如何提出該問題。

這項技能取代的時刻

即將...改為
詢問使用者偏好哪種顏色、尺寸、間距或位置根據以下標準測量;只問沒有門檻能解決的事
稱視覺選擇為主觀命名它通過或失敗的準則——對比度、目標尺寸、重排寬度、焦點可見性、資訊順序
說「看起來不錯」開啟它、截圖,並說明在什麼視埠測量了什麼
憑目測調整控制項尺寸24×24 CSS px 是 WCAG AA 最低標準;設計系統可能設定更嚴格的標準(Material:48dp)
憑外觀從調色板選色計算比率:正文 4.5:1,大型文字與非文字 3:1
在一個視窗尺寸下檢查佈局就出貨檢查 320 CSS px 寬與 256 CSS px 高,重排必須仍能運作
將綠色的 axe 執行結果視為無障礙axe 約僅發現 57%;其餘是鍵盤、焦點順序與意義
設計一個設計系統已定義的元件採用他們的,並說明採用哪一個
詢問如何繪製圖表從使用者最先追蹤的內容決定,然後呈現一個繪製結果

在詢問之前先根據標準決定

四個主體回答了大部分問題, 且它們並非完全一致——當它們有差異時, 應採用較嚴格的數值, 因為滿足它就同時滿足兩者。

WCAG 2.2 是底線,且具規範性:W3C 建議標準, 以及 ISO/IEC 40500。 目標 Level AA;AAA 並非所有內容都可達到,W3C 也如此說明。

準則等級門檻
1.4.3 對比度(最低)AA文字 4.5:1;大型文字(≥18 pt 或 14 pt 粗體)3:1
1.4.11 非文字對比度AA與相鄰顏色 3:1
1.4.4 調整文字大小AA200% 時仍可使用
1.4.10 重排AA寬 320 px 或高 256 px 時無雙軸捲動
1.4.12 文字間距AA行高 ≥1.5 倍、段落 ≥2 倍、字母 ≥0.12 倍、單詞 ≥0.16 倍字型大小
2.4.7 焦點可見AA焦點指示器可見的模式
2.4.11 焦點未被遮蔽AA焦點控制項未完全隱藏
2.5.8 目標尺寸(最低)AA24×24 CSS px,或 24 px 間距
2.4.13 焦點外觀AAA≥2 px 周長,聚焦與未聚焦之間 3:1
2.5.5 目標尺寸(增強)AAA44×44 CSS px

設計系統 解決 WCAG 未明確規定的部分:間距尺度、 字型尺度、元件結構、色彩角色。 採用其元件不是捷徑, 而是決策本身——並且它承載了已完成的無障礙工作。 Material Design 3 設定 48×48 dp 觸控目標, 比 WCAG 的 24 px 更嚴格, 並要求顏色以角色(primary、on-primary、surface)而非固定色碼選擇, 因此主題與深色模式無需另行決定。 對於日本面向公眾的工作,數位廳設計系統(design.digital.go.jp,β版為進行中標準)提供元件、 指引與設計權杖,權杖與範例元件在 GitHub 上以 MIT 授權釋出。

axe-core 測量可測量的部分,並說明其限制: 平均約 57% 的 WCAG 問題。 因此綠色執行結果僅是關於 57% 問題的證據, 而說「axe 通過」卻不提及該數字會誇大其詞——measured-claims 也適用於此數值。

npx @axe-core/cli http://localhost:5173 --tags wcag2a,wcag2aa,wcag22aa
npx lighthouse http://localhost:5173 --only-categories=accessibility --quiet

Lighthouse 的無障礙評分是同一引擎的加權結果。 其稽核是 axe-core 規則——每個規則都連結到 Deque 的規則頁面——因此繼承了 57% 的限制, 而分數又增加了兩種被誤解的方式。 它是加權平均, 權重 3 到 10 基於 axe 的使用者影響評估, 且手動與最佳實踐稽核完全被排除在外, 因此算術無法觸及需要人工檢查的部分。 每個稽核也是二元結果: 一個未標籤的按鈕直接導致「按鈕應有可存取名稱」失敗, 沒有部分分數。 所以 100 分意味著「加權的自動子集通過」, 而完美分數的誠實報告應如此說明,而非「無障礙」。 將其用於需要修正項目的排名清單; 當發現本身比排名更重要時,使用 axe 的 JSON 輸出。 Lighthouse 的效能類別屬於 web-perf, 非此技能範疇。

兩者都無法看到的:焦點順序是否跟隨閱讀順序、 標籤是否正確命名其標示的項目、 圖示的意義在無顏色時是否仍然成立、 版面的資訊順序是否符合任務。 這些需要人工閱讀,而該人員可以是代理。

查看它,然後說明所見

一個沒有觀察背後的介面宣稱,是 measured-claims 的謠言另一種形式。 主機有瀏覽器,因此觀察是可行的:

mcp__claude-in-chrome__navigate      → 頁面
mcp__claude-in-chrome__read_page     → 結構、標題、標籤
mcp__claude-in-chrome__computer      → 在指定視埠的螢幕截圖
mcp__claude-in-chrome__resize_window → 320 px,測試重排

報告發現時應附上視埠。 「它看起來OK」沒有指定寬度與測量; 「在 320 px 時第二欄包裹到第一欄下方,且沒有橫向捲動」則是一個可供他人檢查的閱讀結果。 鍵盤順序透過 Tab 鍵走訪並以觀察到的序列報告, 因為這是 axe 未涵蓋的一半。

資訊順序是推導而來,而非選擇

某個元素的位置取決於使用者對它的操作, 這是 reader-map 的問題應用於螢幕:誰來了、 他們來做什麼、他們首先需要什麼。 只在設定時使用一次的控制項,與每分鐘使用的控制項,不會競爭同一個位置。

因此「這個應該放在哪裡」應透過命名任務來回答, 而非列出三個位置。 當兩個任務確實競爭且沒有一個佔主導地位時, 那就是值得詢問的殘留部分——並且在詢問時應附上競爭的任務名稱, 而非作為角落的選擇。

同樣的原則也適用於圖表。 使用者最先追蹤的內容決定了流向; 形狀跟隨追蹤軌跡, 並且只顯示一個繪製結果,而非描述三個。

真正屬於使用者的部分

測量後倖存的三件事:

  • 介面服務的對象或市場, 當尚未確定時——它決定了應採用哪個標準(受監管市場適用 regulated-claims)。
  • 品牌約束——必須的顏色、字型或標誌。 約束屬於他們;但仍需測量其是否符合 4.5:1, 失敗的品牌顏色將附上對比度比率與最接近的通過變體一併報告。
  • 已從兩方面充分測量的權衡, 證據無法決定:密度對抗可掃讀性、 單一螢幕對抗雙螢幕。 附上兩項測量結果後提出, 這是 own-the-call 允許的問題。

其他所有事項——對比度、間距、目標尺寸、焦點、重排、 元件選擇、圖表形狀、 跟隨任務的位置——都已決定並報告。

檢查清單

  • 對比度已計算,而非目測:文字 4.5:1,大型文字與非文字 3:1
  • 互動目標 ≥24×24 CSS px, 或設計系統的更嚴格數值
  • 在寬 320 px 與高 256 px 檢查,無雙軸捲動
  • 每個互動元素焦點可見,且未被遮蔽
  • Tab 順序已走訪並以觀察結果報告
  • 採用設計系統中已定義的元件,並命名
  • 已執行 axe 或 Lighthouse,並說明 57% 的限制,而非暗示
  • Lighthouse 無障礙評分報告為加權自動子集, 從不稱為「無障礙」
  • 每個外觀宣稱都附上觀察時的視埠
  • 留給使用者的問題為上述三種, 並附上證據

與其他技能的關聯

own-the-call 塑造此技能後殘留的問題; 大多數關於螢幕的問題不應到達它。 reader-map 提供此技能應用於位置安排的工作順序。 measured-claims 規範此處的每個比率與百分比, 包括 57%。 document-structure 與 cognitive-rhythm 負責頁面上的文字; 此技能負責文字周圍的框架。 any-screenshot 是在瀏覽器外捕捉螢幕的方式。 載入與互動速度、Core Web Vitals 及 Lighthouse 的效能評分屬於 web-perf(在 cloudflare 外掛中); 此技能只處理 Lighthouse 的無障礙類別。

來源

  • W3C, "Web Content Accessibility Guidelines (WCAG) 2.2", W3C 建議標準 2024 年 12 月 12 日(www.w3.org/TR/WCAG22/): 四個原則、A/AA/AAA 等級, 以及移除已過時的 4.1.1 解析。
  • W3C, "How to Meet WCAG 2.2 (Quick Reference)"(www.w3.org/WAI/WCAG22/quickref/): 上表中每個門檻, 以 Level AAA 閱讀以包含 2.4.13 與 2.5.5。
  • Deque Labs, axe-core README(github.com/dequelabs/axe-core):MPL-2.0; 規則對應 WCAG 2.0、2.1 與 2.2 的 A、AA 與 AAA 等級; "you can find on average 57% of WCAG issues automatically"。
  • Chrome for Developers, "Accessibility scoring in Lighthouse"(developer.chrome.com/docs/lighthouse/accessibility/scoring): 分數是加權平均,權重 3 到 10, "based on axe user impact assessments", 每個稽核連結到 Deque University axe-core 4.11 規則頁面; 每個稽核是二元結果; 手動與低影響稽核被排除在分數之外。 該頁面本身並未說明完美分數代表頁面可存取——也未說明相反, 因此上述警告是此技能的觀點。
  • デジタル庁デザインシステム(design.digital.go.jp):v2.18.2, 標示為 β版,意指進行中標準。 該網站未說明 WCAG 等級或 JIS X 8341-3 目標。 digital-go-jp/design-tokens、 design-system-example-components-react 與 -html 在 GitHub 上以 MIT 授權釋出。
  • Material Design 3 的 48×48 dp 觸控目標及其色彩角色指引取自引用 m3.material.io 的次要來源, 而非該網站本身:其頁面透過腳本渲染,此處無法讀取。 48 dp 的數值是設計建議, 而非平台強制的最低要求。

關於這些來源彼此不一致, 且應採用較嚴格數值的說法, 是此目錄擁有者的解讀,而非它們任何一方的公開立場。

撰寫此技能時未執行上述任何指令: 兩者都在首次使用時擷取套件, 而此沙盒拒絕執行剛下載的程式碼。 旗標來自各工具的說明文件而非實際執行, 因此專案中的第一次使用也是對呼叫的第一次測試。

Individual skills in this repo

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

ShortArrow/library-design

Designing a library — a published package, or an in-app module from the moment it has a second consumer. The implementation stays editable forever, while the public API, the dependency set, the performance characteristics and every observable behaviour freeze at first external use (Hyrum's law). Five duties to the caller: take no control, add no hidden cost (zero-cost abstraction as the bar), hold no hidden state, hide no failure, block no escape. Use when designing or reviewing a public API, when extracting shared code into a module, when asked to "make this reusable", when a signature-compatible change alters an observable behaviour, and when an application is being shaped around a framework's types and lifecycle.

ShortArrow/test-design

Deriving test cases, triggered by the moments that produce weak ones: about to write a test list that is the happy path restated, about to derive tests by reading the implementation they check, about to test the bound the specification names and not the other one, about to enumerate the roles the specification lists and skip the caller it forgot, about to vary one condition at a time from the happy path, about to draw a state or decision table without tying each row to a test, about to write an expected result with "or" in it, about to skip the error paths as unlikely, about to leave a path unimplemented and untested, or about to grade a suite as adequate by reading it. A test derived from the implementation passes by construction; coverage counts classes, not tests. Use when writing a test plan or list, when a use case is the specification in hand, when adding tests to existing code, when reviewing a suite for gaps, and when a suite is all green and proves little.

相關技能