舒適視覺 (Easy on the Eyes)
螢幕前的眼睛疲勞多半來自網站無法控制的因素：眨眼、對焦距離、未矯正的視力、環境光線。網站能控制的，是它要求使用者額外付出的視覺工作量。這個技能消除了這些額外工作，並說明每條規則的證據強度。
它還能讓舒適的頁面看起來不像模板。在設計之前，它會先研究真實上線的網站，並攜帶一套工藝規則，用以處理那些會讓作品看起來像是生成出來的選擇。
你被允許提出的宣稱
你可以說該設計「不會增加可避免的視覺疲勞」。絕對不要寫該設計可以預防、減輕或治癒眼睛疲勞、保護眼睛，或是「抗藍光」。不要將深色模式、暖色調或特殊字體描述為健康功能。如果使用者要求這類文案，請解釋原因並提供誠實的措辭。
模式
讀取調用技能時提供的參數。
- 無參數，或是一個建置任務。 對於新頁面或區塊，先研究參考案例（見「設計前先研究」）。然後在編寫或編輯 UI 時套用規則。如果專案還沒有顏色或字體 tokens，請從
assets/tokens.css開始。UI 完成後，對原始碼執行audit.mjs，並對渲染後的頁面執行inspect.mjs，在宣告完成前，逐一檢查「腳本無法看到的項目」。 audit（選擇性後接路徑）。執行腳本，然後審查腳本無法看到的項目。使用下方的模板報告。不做任何修改。study後接一個或多個 URL。檢查每個頁面並報告其設計摘要：它的功能、值得借鑒之處，以及它違反了哪些舒適規則。不做任何修改。fix（選擇性後接路徑）。執行稽核。先修復錯誤，再修復警告。除非修正某個錯誤或警告需要依賴它，或者你自己的審查顯示它確實是問題，否則不要修改註解。重新執行腳本並報告。
執行腳本
從專案根目錄執行，並提供要檢查的路徑。腳本位於此技能的 scripts/ 資料夾中，因此請使用此技能被載入的路徑：
node <skill-dir>/scripts/audit.mjs src # 文字報告，有任何錯誤時退出碼為 1
node <skill-dir>/scripts/audit.mjs src --json # 機器可讀格式
node <skill-dir>/scripts/audit.mjs src --strict # 連警告也會導致退出碼為 1
node <skill-dir>/scripts/audit.mjs contrast "#1f2328" "#ffffff" # 檢查一組顏色
node <skill-dir>/scripts/audit.mjs contrast "#8a8f98" "#ffffff" --min 3 # 檢查邊框或圖示
node <skill-dir>/scripts/inspect.mjs https://example.com # 設計摘要與渲染後的舒適度檢查
node <skill-dir>/scripts/inspect.mjs http://localhost:3000 --out shots # 同時儲存亮色與深色截圖
node <skill-dir>/scripts/inspect.mjs dist/index.html --json
audit.mjs讀取原始檔案。inspect.mjs在真實瀏覽器中開啟頁面，因此它測量的是讀者實際獲得的內容：真實文字在其真實背景上的對比度、每行實際字元數、是否存在深色配色方案，以及在要求減少動畫時動畫是否停止。inspect.mjs可作用於任何 URL 或本地 HTML 檔案。它需要專案中安裝 Playwright（npm i -D playwright && npx playwright install chromium）。如果缺少 Playwright 且無法安裝，請說明渲染檢查未執行。- 路徑是必要的。如果使用者未提供，請使用存放 UI 原始碼的資料夾。
- 顏色可以是十六進位、
rgb()、hsl()、oklch()、white或black。 - 若要忽略某項發現（因為是故意的），請在該行加上包含
easy-on-the-eyes-ignore的註解，或在前一行加上easy-on-the-eyes-ignore-next-line。 - 腳本需要 Node 18 或更新版本，且無外部依賴。如果缺少 Node，請手動套用規則，並說明腳本未執行。
兩個腳本都會回報下方表格中的規則 ID。請在你的報告中使用相同的 ID。
設計前先研究
模型會產出它們所見過內容的平均值，而平均值正是人們可以辨識出是生成內容的關鍵。先觀察具體的、已上線的作品，能讓你獲得真實的決策來做出反應。
- 挑選三到五個與你正在建置的內容屬於相同類別的現有網站。使用使用者指定的網站。否則，透過網頁搜尋，或使用任何連接到此會話的設計參考或截圖工具來尋找它們。
- 對每個網站執行
inspect.mjs，加上--out參數，這樣你可以開啟截圖並仔細查看。 - 針對每個網站，記錄其字體和字體級別、使用了多少種顏色以及強調色放在哪裡、行長度、區塊結構，以及一個讓它與眾不同的特點。
- 閱讀每個參考網站的舒適度檢查結果。令人欣賞的網站經常使用極小的文字、微弱的對比度和大量的動畫。借鑒其構圖，但留下這些缺點。
references/craft.md中有對應的表格。 - 告訴使用者你研究了哪些網站，以及你從每個網站中學到了什麼。借鑒結構和決策。絕不複製品牌的名稱、商標、措辭、圖片或精確的佈局。
如果你無法開啟任何參考網站，請說明，並僅根據規則和 references/craft.md 進行設計。
證據等級
每條規則都帶有一個等級。當你解釋某項發現時，請重複該等級，這樣才不會有人把習慣誤認為事實。
| 等級 | 含義 |
|---|---|
research | 受到控制實驗或系統性回顧的支持 |
standard | 由 WCAG 2.2 成功標準設定。參考檔案會給出該標準及其等級 |
convention | 合理且被廣泛使用，但背後沒有試驗支持 |
inference | 從相關刺激的研究推導而來，未在網頁上測試 |
規則
嚴重性決定處理順序：先錯誤，再警告，最後是備註。在同一嚴重性級別內，按表格順序處理。表格中顯示的是通常的嚴重性。腳本在無法判斷某一行是否為問題時（例如，一個可能是標籤的小尺寸），會降低其嚴重性，而當你的審查顯示實際危害較大時，你可以提高嚴重性。
| ID | 規則 | 嚴重性 | 等級 | 參考文件 |
|---|---|---|---|---|
type-rem-zoom | 文字必須能承受縮放。使用 rem 單位，沒有僅基於 viewport 的字體大小，且永遠不允許禁用縮放。 | error | standard | typography |
contrast-floor | 每組文字配對至少 4.5:1。大型文字和 UI 元件至少 3:1。 | error | standard | contrast-and-color |
contrast-color-alone | 絕不單獨使用顏色來傳達狀態。 | error | standard | contrast-and-color |
motion-flash | 任何內容每秒閃爍不得超過三次。 | error | standard | motion |
motion-autoplay | 沒有自動播放且無控制項的影片。任何持續移動超過 5 秒（文字除外）的內容都必須提供暫停功能。除了文字之外，不能有無限循環的動畫。 | error | standard | motion |
motion-reduced | 動畫效果只能存在於 prefers-reduced-motion: no-preference 的條件下。 | error | standard | motion |
theme-focus | 絕不刪除焦點輪廓，除非有可見的替代方案且對比度至少為 3:1。 | error | standard | theming |
type-body-size | 內文文字最小 1rem，長篇閱讀建議 1.125rem 到 1.25rem。任何可讀文字不得小於 0.875rem。 | warning | research | typography |
motion-triggers | 不使用視差捲動、劫持捲軸或大面積縮放。淡入淡出和顏色變化是可以接受的。 | warning | research | motion |
contrast-dark-secondary | 深色背景上的次要文字，對比度需達到 8.5:1 或更好。僅 AA 級別在深色背景上顯得不夠。 | warning | inference | contrast-and-color |
contrast-saturated-on-dark | 深色背景上，不要使用飽和的紅色或藍色作為小文字。在深色主題中使用較淺、較柔和的強調色。 | warning | research | contrast-and-color |
lum-section-steps | 不要交替使用全幅的深色和白色區塊。在深色主題中不要使用白色嵌入內容或彈出視窗。 | warning | inference | layout-and-patterns |
lum-white-flash | 主題化的 html 背景，以及 color-scheme 宣告和 meta 標籤。 | warning | convention | theming |
layout-shift | 為多媒體元素預留尺寸，匹配替代字體的度量，將 CLS 維持在 0.1 或以下。 | warning | research | layout-and-patterns |
contrast-pure-extremes | 使用接近黑色搭配接近白色、米白色搭配深灰色。避免在頁面文字和背景中使用純黑色和純白色。 | warning | convention | contrast-and-color |
type-leading | 內文 line-height 設為 1.5（範圍 1.4 到 1.6）。標題設為 1.1 到 1.3。 | warning | convention | typography |
type-weight | 內文字重 400 或以上。在內文尺寸中不要使用 100 到 300 的字重。 | warning | convention | typography |
type-align | 使用 text-align: start。不要使用左右對齊的內文。僅對短標籤使用全大寫。 | warning | standard | typography |
layout-targets | 指標目標至少 24 x 24 CSS 像素，主要操作至少 44 x 44 像素。句子中的連結不受此限。 | warning | standard | layout-and-patterns |
theme-both-schemes | 同時提供亮色和深色主題，並遵循 prefers-color-scheme。可選的手動切換開關應預設使用系統設定。 | note | research | theming |
pattern-stripes | 在大面積區域中，不要使用週期為 7 到 27 像素的高對比度條紋或網格。 | note | inference | layout-and-patterns |
type-measure | 閱讀文字的最大寬度限制在 50ch 到 60ch，這大約是 65 到 78 個字元。 | note | convention | typography |
motion-duration | 動畫時長 100 到 300 毫秒，上限 500 毫秒，入場動畫使用 ease-out。 | note | convention | motion |
theme-preferences | 遵循 prefers-contrast、forced-colors 和 prefers-reduced-transparency 使用者偏好。 | note | convention | theming |
pattern-clutter | 每個視圖只有一個主要強調點。使用少量強調色、尺寸和邊框樣式。 | note | research | layout-and-patterns |
craft-copy | 具體的文案。絕不虛構統計數據、推薦語、評分或客戶標誌。 | warning | convention | craft |
craft-reference | 在設計之前，研究同類別的三到五個真實網站。借鑒決策，絕不抄襲。 | note | convention | craft |
craft-one-idea | 每個視圖只有一個獨特的想法。其他一切都保持低調。 | note | convention | craft |
craft-palette | 使用帶有色調的中性色和一個強調色。不使用靛藍色或紫色漸層，不使用漸層文字。 | note | convention | craft |
craft-show-product | 展示真實的介面、數據或程式碼。不要使用一排三個相同的圖標卡片，不要使用 emoji 圖標。 | note | convention | craft |
craft-layout | 不要將所有內容置中。使用不均勻的網格分割和變化的區塊結構。 | note | convention | craft |
craft-restraint | 使用平坦表面和極細線條。少量陰影，一個圓角半徑比例尺，不要疊加模糊和發光效果。 | note | convention | craft |
參考檔案包含推理過程、來源以及修改前後的程式碼範例。每當你套用或報告某條規則時，請閱讀所有相關的參考檔案。要修復整個頁面的問題，通常需要三到四個參考檔案。
references/contrast-and-color.md：選擇顏色、建立調色板或深色主題、解釋對比度檢查結果。references/typography.md：字體大小、行長度、間距、字體、流體排版。references/motion.md：動畫、轉場、影片、捲動效果、載入指示器。references/layout-and-patterns.md：表格、網格、條紋、密度、區塊背景、圖片、版面位移。references/theming.md：亮色與深色主題、主題切換開關、焦點樣式、使用者偏好 media query、Tailwind 和 shadcn/ui。references/craft.md：設計新頁面或區塊、看起來像模板或生成的結果、從參考網站借鑒什麼以及留下什麼。references/evidence.md：當使用者詢問原因、質疑某條規則，或詢問關於藍光、深色模式、閱讀困難字體或 APCA 時。
無需詢問即可寫入的預設值
:root {
color-scheme: light dark;
--bg: light-dark(oklch(0.985 0.002 90), oklch(0.18 0.01 255));
--text: light-dark(oklch(0.24 0.01 255), oklch(0.93 0.005 255));
--muted: light-dark(oklch(0.48 0.01 255), oklch(0.78 0.01 255));
--accent: light-dark(oklch(0.5 0.19 255), oklch(0.74 0.13 255));
}
html { background-color: var(--bg); color: var(--text); }
body { font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem); line-height: 1.6; }
p, li { max-inline-size: 55ch; }
:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
@media (prefers-reduced-motion: no-preference) {
.card { transition: transform 200ms ease-out; }
}
在頁面 <head> 中加入 <meta name="color-scheme" content="light dark">。
內文文字在亮色主題下測量為 15.75:1，在深色主題下為 15.30:1。次要文字測量值為 6.25:1 和 9.39:1。強調色測量值為 5.78:1 和 8.14:1，這就是為什麼它被用於焦點環：系統的 Highlight 顏色在深色背景上可能低於 3:1。assets/tokens.css 包含完整集合，包括表面色、控制項邊框色、長篇閱讀尺寸以及可選的調暗主題。
僅在頁面確實為兩種配色方案都設定了顏色後，才加入 color-scheme: light dark。在一個已寫死亮色顏色的頁面上，這會在白色頁面上產生深色捲軸和表單控制項。請在同一次修改中修復 theme-both-schemes。
Tailwind 和 shadcn/ui 使用純白色搭配接近黑色（約 19.8:1），並使用 bg-white / text-black 作為純值。請覆寫 --background 和 --foreground，並使用像 bg-background 和 text-foreground 這樣的語義化工具類別。
腳本無法看到的項目
當你可以在渲染後的頁面上執行 inspect.mjs 時，它會檢查下方清單中的第一、三和五項。其餘項目，以及當它無法執行時的所有項目，請透過閱讀程式碼或頁面來檢查。如果你無法檢查某個項目，請將其列在「未驗證」下並說明原因。
- 每個真實文字和背景配對的對比度，包括圖片和漸層上的文字。使用
contrast命令測量配對 - 小文字是內文還是短標籤
- 渲染佈局中的行長度。在幾個完整行中計算字元數
- 動畫和影片的閃爍頻率
- 區塊之間的亮度跳躍，以及深色主題中的白色嵌入內容
- 載入期間的版面位移，包括沒有
width和height屬性的圖片和影片 - 狀態是否僅由顏色傳達
- 忽略減少動畫偏好的 JavaScript 驅動動畫
- 使用
em、百分比或font簡寫設定的尺寸，以及使用background-size建構的條紋
報告模板
Easy on the Eyes 檢查報告
路徑 / URL：
結果：
### 錯誤
- [規則 ID]: [發現內容]（[等級]）
### 警告
- [規則 ID]: [發現內容]（[等級]）
### 備註
- [規則 ID]: [發現內容]（[等級]）
### 腳本無法看到的項目
- [項目]: [已驗證 / 未驗證 / 不適用]
### 總覽
總檢查項目數：
錯誤：
警告：
未驗證：
限制
此技能不提供完整的 WCAG 遵循性稽核。它著重於減少可避免的視覺疲勞與避免模板化設計。它不包含個人眼睛健康建議。對於正式的無障礙遵循性稽核，請使用專業工具或諮詢專家。