Communitygithub.com

coastdigitalgroup/coastai-skills

為設計系統中的所有互動元素設計、規範與稽核高對比、穩固的鍵盤焦點指示器,確保符合 WCAG 2.1/2.2 標準、無縫的品牌整合以及原生高對比模式支援。

coastai-skills 是什麼?

這個「焦點指示器設計系統」技能提供了一套完整的方法論,用於在設計系統中設計、規範與稽核所有互動元素的鍵盤焦點指示器。它強調焦點指示器是鍵盤導航、螢幕閱讀器以及替代輸入使用者主要的視覺路標,並指出移除或弱化預設焦點環會造成嚴重的無障礙問題。此技能支援透過設計 Token、元件規範與高對比模式降級,建立品牌化、高對比且符合 WCAG 2.1 和 2.2 標準的焦點狀態。它提供詳細的工作流程(元件分類、尺寸與佈局模型、WCAG 對比度與尺寸 Token、指標與鍵盤狀態分離、高對比模式降級)、決策規則(內環 vs. 外環、單色 vs. 雙色光暈、邊框半徑對齊)以及驗證標準,確保焦點指示器在各種背景、主題與跨平台輸入方式下都能穩固可視且不影響美觀。它也列出常見的失敗模式(如 outline: none 刪除、低對比幽靈環、被裁切的輪廓等),並強調使用 :focus-visible 偽類別與透明 outline 降級。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/coastdigitalgroup/coastai-skills/tree/HEAD/website-design/focus-indicator-design-system

在你喜歡的 AI 中提問

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

說明文件

焦點指示器設計系統

目的

焦點指示器設計系統提供了一套系統化的方法,用於在所有互動元素(按鈕、連結、表單輸入、自訂切換開關、複雜小工具)上設計、規範與稽核鍵盤焦點指示器。

焦點指示器是鍵盤導航者、螢幕閱讀器使用者以及使用替代輸入裝置的人最主要視覺路標。當設計師因為預設瀏覽器焦點環「看起來很醜」而將其隱藏,或用低對比度的覆蓋樣式取代它時,他們就立即創造了一個災難性的無障礙障礙。此系統確保焦點指示器具有品牌特色、高對比、穩固定位,且符合 WCAG 2.1 和 2.2 標準,而不犧牲視覺美感。

使用案例

  • 建立設計系統: 在品牌 UI 套件中建立基於 Token 的全局焦點狀態。
  • 元件設計規範: 為複雜元素(例如自訂核取方塊、範圍滑桿或標籤組)定義自訂焦點環。
  • 無障礙改善稽核: 識別並修復現有網站上不可見或低對比度的焦點輪廓。
  • 主題與背景適配: 為淺色、深色和品牌色背景標準化焦點指示器。
  • 跨平台輸入最佳化: 配置 :focus-visible 行為,確保滑鼠使用者不會看到分散注意力的焦點環,而鍵盤導航者能看到高可視性的指示器。

何時不該使用

  • 靜態內容: 不要為非互動元素(例如純文字段落、圖片、標題或不含連結的資訊卡)設計焦點指示器。
  • 原生未修改的控制項: 如果專案完全依賴預設瀏覽器控制項且沒有任何自訂樣式或品牌覆蓋,且原生焦點行為完全未受修改。
  • 替代路標模式: 在語音控制的智慧顯示器或純觸控的原生行動應用程式上,鍵盤風格的焦點環並非該平台標準無障礙架構的一部分。

輸入

  1. 品牌色板與背景 Token: 核心顏色、背景顏色(淺色、深色和品牌色調)以及容器邊框。
  2. 互動元素清單: 所有需要焦點狀態的互動 UI 元件清單(按鈕、連結、文字欄位、選項按鈕、自訂覆蓋層)。
  3. 邊框半徑系統: 元件圓角的 Token 值(例如 --radius-s、--radius-m),以確保焦點環與元素形狀匹配。
  4. 目標 WCAG 等級: 標準 AA 最低符合度(WCAG 2.1/2.2)或 AAA 目標。

輸出

  1. 全局焦點 Token: 標準化的設計 Token,定義焦點環顏色、厚度、輪廓樣式和偏移間距。
  2. 元件特定的焦點規範: 內部焦點環、外部焦點環以及複雜巢狀輪廓的空間佈局規則。
  3. 高對比(強制色彩)樣式規則: 確保與 Windows 強制色彩模式相容的 CSS 規範。
  4. 僅焦點可視整合邏輯: 區分鍵盤導航提示與滑鼠點擊回應的規範。

工作流程

1. 分類元件上下文

稽核互動元件,並根據其容器背景進行分組,以確定焦點對比度需求:

  • 淺色背景: 需要深色焦點環。
  • 深色背景: 需要淺色焦點環。
  • 品牌背景(例如亮藍色): 可能需要中性白色或次要高對比環,因為標準品牌色輪廓會與背景融合。

2. 定義尺寸與佈局模型

選擇元素與其焦點環之間的幾何關係:

  • 外部偏移輪廓: 焦點環透過透明間距(偏移)定位在元素邊框外側。建議用於按鈕、標籤和連結。
  • 內嵌焦點環: 焦點環定位在元素邊框內側。建議用於文字欄位、下拉選單和受 overflow: hidden 剪裁的項目。
  • 對比光暈(雙環): 外部環包裹在對比的次要線條中(例如 2px 白色環加上 1px 黑色輪廓)。極為穩固,可確保在任何背景上都清晰可見。

3. 建立 WCAG 對比度與尺寸 Token

確定滿足 WCAG 的最小樣式值:

  • 將焦點環厚度設為至少 2px(建議 3px)。
  • 與相鄰背景以及元素的未聚焦狀態之間維持至少 3:1 的對比度。
  • 確保焦點指示器的面積至少等於圍繞控制項周長的 2px 實心邊框(WCAG 2.2 焦點外觀)。

4. 分離指標與鍵盤狀態

使用 :focus-visible 偽類別避免「設計摩擦」。

  • 鍵盤導覽(:focus-visible): 觸發高對比度、視覺上突出的焦點指示器。
  • 滑鼠/觸控互動(沒有 :focus-visible 的 :focus): 在滑鼠點擊時保持焦點環隱藏或極為細微,在維持完整無障礙性的同時防止設計投訴。

5. 定義高對比模式降級

確保焦點指示器不會在輔助樣式偏好設定(例如 Windows 高對比模式 / 強制色彩)下消失:

  • 帶有透明顏色的原生 outline 會由強制色彩自動映射,但自訂的 box-shadow 樣式會被丟棄。
  • 始終包含 outline 降級方案(即使設定為 outline: 2px solid transparent 或在媒體查詢中使用 outline-color: CanvasText),以便高對比模式能渲染出可見的輪廓。

決策規則

規則 1:內部 vs. 外部環放置

  • 如果元素具有自訂邊框且沒有溢位遮罩(overflow: hidden),則使用外部偏移輪廓。
  • 如果元素屬於緊密網格的一部分、其父容器設有 overflow: hidden,或是外部輪廓會與相鄰元素重疊的文字輸入欄位,則使用內嵌焦點環(box-shadow: inset ...)。

規則 2:單色 vs. 雙色光暈

  • 如果背景統一且可預測(例如始終為淺色或始終為深色),且對比度經驗證大於等於 3:1,則使用單色環。
  • 如果元素位於圖片、漸層、使用者生成內容之上,或在不同背景之間切換(例如在區塊邊界上滾動的固定頁首),則使用雙色對比光暈(例如深藍色內環、純白色外環)。

規則 3:焦點環邊框半徑

  • 焦點輪廓必須反映其父級控制項的 border-radius。
  • 確保 outline-offset 為正值(例如 2px 或 4px),且輪廓的邊框半徑與卡片/按鈕的曲率匹配,或使用能自然映射到元件圓角的 box-shadow。
正確:
[   按鈕 (半徑 8px)   ]
   (間距: 2px)
============================= 焦點輪廓 (半徑 10px)

錯誤:
[   按鈕 (半徑 8px)   ]
   (間距: 2px)
----------------------------- 焦點輪廓 (尖銳 90 度角)

限制

  • 無障礙(對比度): 焦點環與其周圍背景的對比度至少需達到 3:1(WCAG 2.1 SC 1.4.11 非文字對比度)。
  • 無障礙(可視性): 指示器必須完全可見。焦點指示器絕不能隱藏在固定頁首、浮動聊天小工具或覆蓋層後面(WCAG 2.2 SC 2.4.11 焦點不被遮蔽)。
  • 無障礙(外觀): 焦點指示器必須足夠大。它必須符合 WCAG 2.2 SC 2.4.13(焦點外觀)的計算:最小寬度 2px,且最小面積等於周長乘以 2px。
  • 回應性: 焦點指示器不得拉伸容器或觸發水平頁面佈局溢出。始終使用絕對定位、絕對 CSS 輪廓或內嵌 box-shadow,這些都不會改變 DOM 佈局流程。

常見失敗模式

  • :focus { outline: none; } 清除者: 完全隱藏焦點指示器,而未提供穩固的偽類別替代方案。
  • 低對比「幽靈」環: 在白色背景上使用淺灰色輪廓,使活動焦點狀態對低對比度視覺的使用者來說不可見。
  • 「剪裁輪廓」陷阱: 將外部焦點環放置在巢狀於設有 overflow: hidden 的容器內的元素上。焦點指示器的左右兩側被切掉,只留下水平細條。
  • 「固定頁頭遮蓋」: 將 Tab 焦點移到位於視口頂部的錨點元素,但固定導覽列重疊並完全遮蓋了它(違反 WCAG 2.2 SC 2.4.11)。
  • 點擊觸發的焦點雜亂: 未使用 :focus-visible,導致每次滑鼠點擊時都會出現厚重的藍色環閃爍,這讓設計團隊感到沮喪,並促使他們要求完全移除焦點樣式。
  • 強制色彩清除: 僅使用 CSS 自訂屬性和 box-shadow 值建立美觀的焦點環,卻沒有透明 outline 降級方案,導致在 Windows 高對比模式下焦點指示器完全不可見。

驗證標準

  • 每個互動元素在透過 Tab 鍵導覽時,都顯示一個高度可見、獨特的焦點指示器。
  • 每個全局和元件焦點指示器的對比度經驗證,至少為 3:1。
  • 自訂焦點樣式使用 :focus-visible 選擇器,確保在鍵盤導覽時觸發,而在滑鼠點擊時保持乾淨。
  • 沒有任何焦點指示器被父容器的 overflow: hidden 規則剪裁或切割(偏移已調整或轉為內嵌)。
  • 對靠近固定頁首或浮動元素的元素進行鍵盤導覽時,聚焦的元素保持完全可見(使用 scroll-margin-top 覆蓋)。
  • 使用透明輪廓規則,在高對比/強制色彩模式下驗證焦點指示器。
  • 自訂指示器的周長表面積符合 WCAG 2.2 SC 2.4.13 的最小計算值。

Individual skills in this repo

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

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for progressive disclosure using accordions, ensuring structural integrity, visual affordances, and accessibility across different content densities and devices.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for long-form content, managing readability, vertical rhythm, and information density to ensure a superior reading experience.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for informational elements that communicate state (Badges) and categorization (Tags) with clarity and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for non-overlay notifications, managing global announcements and contextual inline alerts to communicate system states without interrupting the user's flow.

coastdigitalgroup/coastai-skills

Design and implement a systematic, asymmetrical bento-grid layout framework to organize diverse content types cohesively while maintaining strict visual hierarchy, logical focus order, and responsive flexibility.

coastdigitalgroup/coastai-skills

Design a responsive, mobile-first bottom navigation bar and persistent action dock system for mobile websites and web applications, establishing spatial anchors, tab bar anatomy, badge indicators, thumb-zone ergonomics, safe area inset handling, active/inactive state contrast, and desktop responsive adaptation rules.

coastdigitalgroup/coastai-skills

Design a mobile-first bottom sheet overlay system with configurable detents, drag affordances, safe area padding, responsive desktop modal/popover adaptation, and WCAG AA accessibility compliance.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for secondary navigation trails that provide orientation, context, and one-click access to parent levels in deep information architectures.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for buttons and interactive triggers, managing visual hierarchy, variant logic, and action grouping to ensure clear intent and accessible interaction.

coastdigitalgroup/coastai-skills

Design a systematic framework for date and time selection, managing calendar grids, range pickers, and scheduling interfaces to ensure precision and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for modular content containers that maintain hierarchy, structural integrity, and action alignment across variable content and responsive viewports.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for horizontal discovery components, managing navigation affordances, scroll behavior, and accessibility to ensure effective content density without compromising usability.

coastdigitalgroup/coastai-skills

Design a systematic, highly accessible, and developer-friendly UI layout framework for code blocks, snippet showcases, multi-file code tabs, line-highlighting, diff views, and syntax token contrast in technical documentation and developer platforms.

coastdigitalgroup/coastai-skills

Design a systematic framework for global command menus (Cmd+K panels) that combines keyboard-driven navigation, command execution, and shortcut discovery into an accessible, responsive overlay.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for threaded conversations, managing nesting depths, action hierarchies, and community signaling to foster engagement and readability.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for side-by-side comparison interfaces, managing high attribute density and responsive complexity to support informed decision-making.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for user privacy, managing consent banners, preference centers, and persistent privacy controls to balance legal compliance with user trust.

coastdigitalgroup/coastai-skills

Design and implement a systematic, highly accessible, and responsive visual layout framework for conversational chat widgets, live chat boxes, and chatbot panels that ensures clear message scannability, native focus flow, and seamless mobile keyboard adaptation.

coastdigitalgroup/coastai-skills

Design a systematic, accessible, and high-conversion framework for custom select dropdowns and comboboxes, defining anatomy, states, search-filtering, and responsive mobile-adaptive patterns.

coastdigitalgroup/coastai-skills

Design and implement a systematic color palette that ensures WCAG 2.2 accessibility compliance. Trigger this skill when asked to define brand colors, create UI themes, or establish a visual system for a website.

相關技能