antislop-human
反垃圾內容：AI 編碼代理規則。人類技能
屬於 antislop 系統的一部分。請與
antislop.md（核心）一同閱讀。此技能深入探討人類關懷：UI 必須讓不同眼睛、手部與設備配置的人都能使用。包含對比度、鍵盤、焦點、狀態，以及那些會排除使用者的行動端細節。
如何使用此技能
- 與
antislop.md一起載入，但凡任務涉及建置或編輯 UI 時。核心包含機制（目的測試、三層級、交付閘門）；此技能則提供人類端的深度：UI 中會排除不同眼睛、手部與設備配置使用者的部分。 - 每個條目都有相同的結構：說明（模式）、原因（它排除了誰，以及為何看起來未完成）、修正（改採的做法），並引用核心規則編號 R-XX。
- 無障礙不是最後才加上的一串核取清單。它是核心承諾「UI 經得起考驗」（C-4）的一部分。核心中的交付閘門仍是閘門；本檔案結尾的「人類技能檢查清單」則是與之搭配執行的補充。
- 對比度檢查工具（公式 + 參考表格 + 腳本）位於此技能中。對於所有無法肉眼驗證的顏色配對，請使用它。
- 此技能僅保留那些會排除使用者的行動端細節：縮放，以及螢幕鍵盤。
色彩與對比度
低對比度文字
- 說明： 淺灰色文字放在白色或接近白色的背景上，纖細的主體文字，選擇因為「優雅」而變淡的標籤，但難以閱讀。
- 原因： 它排除了低視力使用者以及所有在強光下的人。這是一個未檢查標準的視覺選擇，正是此過濾器要捕捉的那種預設行為。
- 修正： 符合 WCAG AA 最低標準（R-25）：一般文字 4.5:1，大型文字（18px 以上）3:1。計算比例，不要目測。
照片或漸層上的文字
- 說明： 白色文字直接放在圖片或漸層上，該區域某些部分較亮，僅在一個亮點檢查。
- 原因： 對比度是區域性的。在圖片亮的區域，即使整體看起來仍「良好」，文字對比度仍會低於 4.5:1。R-25 要求測試文字覆蓋的整個區域，而不是單一點。
- 修正： 在文字後面添加遮罩或純色區塊，然後驗證最差的位置，而不是最好的位置。如果文字區域的任何部分未通過，則該處理方式失敗。
灰色對灰色的幻覺
- 說明： 宣稱「深灰配黑」或「淺灰配白」通過 AA 標準，但未經計算。
- 原因： 這是最常見的無障礙幻覺。人眼會高估灰色配對的對比度，而代理會因為聽起來合理而重複此說法。#555555 配黑色的比例是 2.8:1。它未通過。
- 修正： 切勿斷言配對通過。請執行對比度檢查工具（如下）或應用公式。若兩者皆不可行，請使用參考表格。
非文字對比度
- 說明： 互動元件（按鈕、圖示、輸入框邊框、焦點指示器、圖表區段）與其背景的區分低於 3:1。
- 原因： 非文字 UI 透過形狀與邊緣傳達資訊。當邊緣只有細微色調時，低視力使用者無法找到控制項。相同的標準也適用於懸停和選中等狀態。
- 修正： 為每個元件邊界和每個狀態指示器提供與相鄰顏色 3:1 的比例（WCAG 1.4.11）。將圖示與符合 4.5:1 的文字標籤配對。
對比度檢查工具
對比度檢查工具的大本營。分為三層，從最方便到最不方便：
腳本。 當腳本執行環境可用且檔案存在時，請執行它，而不是手動計算。腳本位於此技能的資料夾中（contrast-check.py，與此 SKILL.md 同一層）。在 macOS 和 Linux 上用 python3 執行，在 Windows 上用 python 執行：
python3 "${CLAUDE_SKILL_DIR}/contrast-check.py" "#FFFFFF" "#777777"
# 一般文字：失敗 (4.48 < 4.5)
# 大型文字：通過 (4.48 >= 3.0)
如果此代理中沒有 ${CLAUDE_SKILL_DIR} 變數，請直接將腳本路徑指向此技能的資料夾。腳本的存在是為了讓代理停止幻覺 AA。它接受兩個十六進位顏色，並輸出比例和兩種文字大小的判定結果。如果檔案遺失，下方的公式和表格本身已完整。切勿因為腳本而停滯。
公式（WCAG 2.x）。
- 對比度比例 = (L1 + 0.05) / (L2 + 0.05)，其中 L1 是較亮的相對亮度，L2 是較暗的。
- 單一顏色的相對亮度 L：將每個通道轉換為 0-1（
c = hex / 255），然後線性化：如果c <= 0.03928，則c_lin = c / 12.92；否則c_lin = ((c + 0.055) / 1.055)^2.4。 L = 0.2126*R + 0.7152*G + 0.0722*B。- 比較未四捨五入的比例：一般文字為 4.5:1，大型文字為 3:1（18px 以上，依據 R-25）。僅在顯示時四捨五入，因此比例為 4.498:1 的配對顯示為 4.50，但仍未通過 4.5:1。最大比例為 21.0（白底黑字）。
參考表格（常見配對，使用公式計算）：
| 配對（文字於背景上） | 比例 | 一般文字 (4.5) | 大型文字 (3.0) |
|---|---|---|---|
| 白底黑字 | 21.00 | 通過 | 通過 |
| 黑底白字 | 21.00 | 通過 | 通過 |
| #333333 底白字 | 12.63 | 通過 | 通過 |
| #666666 底白字 | 5.74 | 通過 | 通過 |
| 白底 #777777 | 4.48 | 失敗 | 通過 |
| #070707 底 #777777 | 4.50 | 失敗 | 通過 |
| #888888 底白字 | 3.54 | 失敗 | 通過 |
| #999999 底白字 | 2.85 | 失敗 | 失敗 |
| 黑底 #555555 | 2.82 | 失敗 | 失敗 |
#070707 底 #777777 這行是接近閾值的案例：4.4983:1 顯示為 4.50，但仍未通過 4.5:1。
將此表格視為合理性檢查，而非替代品。任何未列出的配對，或任何接近閾值的配對，都需透過公式或腳本進行檢查。
鍵盤
移除焦點外框
- 說明：
outline: none或outline: 0且沒有替代的焦點樣式。 - 原因： 鍵盤使用者看不到他們的位置。這是讓 UI 在沒有滑鼠時變得無法使用的最快方法，R-32 直接禁止此做法。
- 修正： 保留或替換外框為可見的
:focus-visible樣式，該樣式需符合相同的對比度標準（與相鄰元素 3:1）。切勿在沒有替代方案的情況下設定outline: none。
僅限滑鼠的模式
- 說明： 僅在懸停時開啟的選單、點擊開啟但無法用鍵盤開啟的下拉選單、沒有鍵盤替代方案的拖放功能。
- 原因： 每一個都會排除鍵盤與輔助科技使用者（R-32）。如果一個控制項無法透過 Tab、Enter 或 Space 鍵到達和操作，它對一整群人而言就不存在。
- 修正： 每個互動元素都能透過鍵盤到達和操作（R-32）：遵循視覺順序的邏輯 Tab 順序、使用 Enter 或 Space 啟動、對話框可用 Escape 關閉（R-26）。
中斷的 Tab 順序
- 說明： 因為 DOM 順序與視覺順序不符，焦點在頁面上跳來跳去、跳過內容，或落在隱藏元素上。
- 原因： 讀取程式碼順序而非視覺順序的 Tab 順序會使導航變得無法預測（R-32）。使用者會失去他們的位置，頁面感覺故障。
- 修正： 使原始碼順序與視覺順序一致，為長頁面添加跳過連結，並且切勿為真實內容設定
tabindex="-1"，除非它是受控焦點陷阱（例如對話框）的一部分。
焦點與狀態
微弱或不可見的焦點指示器
- 說明： 與背景顏色相同的焦點環、僅在懸停時出現的環，或者比 1px 邊框還細的指示器。
- 原因： 焦點指示器是鍵盤使用者知道他們位置的方式。如果它未通過對比度標準或僅在懸停時顯示，則僅使用鍵盤的操作就會中斷（R-32, R-34）。
- 修正： 每個互動元素上都有一個可見的焦點指示器，與相鄰顏色有 3:1 的對比度，在你提供的每個主題中都要有。在深色和淺色模式中檢查它。
僅用色彩的回饋
- 說明： 成功、錯誤和狀態僅透過顏色傳達：紅色的錯誤文字、綠色的成功邊框、有顏色的標籤，沒有圖示、標籤或文字。
- 原因： 它排除了色盲和低視力使用者，並且在強制色彩模式下完全消失。依賴於看到色調的狀態不是真正的狀態（C-4）。
- 修正： 將每個顏色信號與文字、圖示或模式配對。錯誤狀態首先是文字：「密碼長度至少需要 8 個字元」，而不僅僅是紅色邊框。
缺少 UI 狀態
- 說明： 沒有空白、載入或錯誤狀態的資料視圖，或者狀態存在但不可見：沒有文字的旋轉動畫、沒有說明的空白畫面。
- 原因： R-27 要求這三種狀態；從無障礙角度來看，每個狀態都必須是可感知且資訊豐富的，而不只是裝飾性的。沒有上下文的載入旋轉動畫，對螢幕閱讀器使用者來說就像當機的頁面。
- 修正： 每個資料視圖都有全部三種狀態（R-27），並且每個狀態都被宣告或可見：明確的空白訊息、帶有文字的載入狀態、以及說明發生什麼事以及如何繼續進行的錯誤狀態。
縮放與行動端使用
行動端的版面機制（斷點、縮放、網格、溢出、觸控目標）是 antislop-layoutmobile 的範圍。本節僅保留那些會排除使用者的行動端細節：縮放，以及螢幕鍵盤。
無法縮放的文字
- 說明： 固定的像素字體大小，或者使用
overflow: hidden的容器在 200% 縮放時裁剪文字。 - 原因： 使用者必須能夠調整文字大小（WCAG 1.4.4）。如果縮放到 200% 會裁剪內容或強制水平滾動，則文字實際上無法調整大小。
- 修正： 使用隨著縮放而重排的流動字型，不要在文字上使用會裁剪的容器，並驗證在窄視口上以 200% 縮放時版面仍能保持（R-35）。
行動鍵盤遮蓋表單
- 說明： 視口底部的輸入框被螢幕鍵盤遮蓋，沒有滾動到視野中，也沒有為輸入框留下空間。
- 原因： 使用者看不到也摸不到的表單，就是他們無法完成的表單。這是僅限行動端的排除情況（R-03）。
- 修正： 當輸入框獲得焦點時，它應滾動到鍵盤上方進入視野，並有足夠的底部內邊距，使得焦點欄位永遠不會被遮蓋。在真實設備或模擬鍵盤上測試。
人類技能檢查清單
當任務涉及 UI 時，請與核心交付閘門一起執行這些檢查。所有答案必須是是：
- 每個文字與背景的配對是否都已透過對比度檢查工具（公式、表格或腳本）驗證，包括圖片和漸層上的文字？（R-25）
- 每個互動元件的邊界和狀態指示器是否都與其背景達到 3:1 的對比度？（非文字對比度）
- 焦點指示器是否在所有主題的每個互動元素上都可見、高對比度且存在？（R-32, R-34）
- 每個互動元素是否都能透過鍵盤到達和操作，對話框可透過 Escape 關閉，且沒有未經替代的
outline: none？（R-32, R-26） - 每個資料視圖的空白、載入和錯誤狀態是否存在且可感知，而非僅以顏色區分？（R-27, C-4）
- 文字能否調整大小至 200% 而不被裁剪，且行動鍵盤是否從未遮蓋有焦點的輸入框？（R-35）