Communitygithub.com

coastdigitalgroup/coastai-skills

設計一個用於非持久性UI圖層(模態框、抽屜、彈出面板)的系統化框架,平衡使用者專注度、上下文與中斷層級。

coastai-skills 是什麼?

此技能提供了一套系統化的方法,用於管理在主介面之上的臨時內容圖層。它確保中斷程度與使用者的當前任務成比例,盡可能保留上下文,並在使用模態框、抽屜或彈出面板時,維持介面的可存取性與回應性。技能透過中斷層級(高、中、低)來決定使用哪種模式:高中斷使用模態框(禁用背景)、中斷使用抽屜(從邊緣滑入)、低中斷使用彈出面板(錨定於特定元素)。它強調原生 `<dialog>` 元素的優勢,包括自動管理堆疊層級、提供 `::backdrop` 偽元素以及原生支援 Escape 鍵關閉。此技能支援所有平台(桌面、行動裝置、響應式),並提供了詳細的決策規則,例如「模態框 vs 抽屜」規則和「拇指」規則。它還涵蓋了可存取性要求(焦點捕捉、ARIA 角色)、響應式適應(例如桌面彈出面板轉為行動裝置抽屜)以及常見失敗模式(如覆蓋混亂、上下文遺失)。其工作流程包含五個步驟:按中斷層級分類、定義內部層級結構(標題、內容、頁尾)、建立高程與背景遮罩、設計響應式適應、以及定義關閉與退出模式。

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

在你喜歡的 AI 中提問

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

說明文件

覆蓋層與對話框系統

目的

「覆蓋層與對話框系統」技能提供了一套管理臨時內容圖層的方法論,這些圖層位於主要介面之上。它確保中斷程度與使用者的任務成比例,盡可能保留上下文,並在使用模態框(Modal)、抽屜(Drawer)或彈出面板(Popover)時,維持介面的可存取性與回應性。

使用案例

  • 為破壞性操作設計確認流程(模態框)。
  • 建立次要工作區,用於編輯複雜細節而不失去頁面上下文(抽屜)。
  • 為特定 UI 元素實作上下文幫助或工具提示(彈出面板)。
  • 為行動裝置設計特定的探索層,用於篩選或搜尋(抽屜)。

何時不應使用

  • 主要導航: 請勿將覆蓋層用於主要網站結構;應改用 site-navigation-system。
  • 持久性內容: 如果資訊對使用者至關重要,需要隨時可見,則應屬於基礎頁面佈局的一部分,而非覆蓋層。
  • 複雜的多頁流程: 如果任務需要超過 2-3 個步驟,請考慮使用專用頁面而非模態框,以避免使用者迷失方向。
  • Toast/Snackbar 通知: 對於被動、非阻斷性的狀態回饋(例如「已儲存」、「已複製到剪貼簿」),請改用 toast-and-snackbar-system —— 該技能詳細涵蓋了該圖層的定位、堆疊、持續時間和可存取性。

輸入

  1. 內容量: 需要顯示多少資訊?
  2. 中斷層級: 使用者是否必須在繼續前完成此任務,還是可選擇?
  3. 觸發上下文: 使用者從何處來,他們預期會發生什麼?
  4. 平台/視埠: 這是為行動裝置、桌面還是響應式混合環境設計?

輸出

  1. 模式選擇: 根據中斷矩陣,在模態框、抽屜或彈出面板之間做出明確選擇。
  2. 結構規格: 定義的區域(標題、內容、頁尾/操作)及其內部層級結構。
  3. 行為規格: 背景遮罩行為、關閉觸發器和響應式適配的規則。
  4. 可存取性要求: 焦點管理與 ARIA 角色定義。

工作流程

1. 按中斷層級分類

確定覆蓋層所需的「重力」:

  • 層級 1(高):模態框。 停用背景。用於關鍵決策或專注任務。
  • 層級 2(中):抽屜。 從邊緣滑入。用於需要看到父層上下文的複雜子任務。
  • 層級 3(低):彈出面板。 錨定到特定元素。用於上下文設定或資訊。

對於被動、非阻斷性的狀態回饋(層級 4),請參閱 toast-and-snackbar-system —— 此處不討論。

2. 定義內部層級結構(結構)

將 visual-hierarchy-system 應用於覆蓋層:

  • 標題: 清晰的標題和一致的「關閉」機制(X 按鈕)。
  • 主體: 主要內容區域。如果內容很長,請定義滾動行為(固定標題/頁尾)。
  • 頁尾: 主要和次要操作,一致對齊(桌面通常右對齊,行動裝置則為全寬)。

3. 建立高程與背景遮罩

  • Z-Index 策略: 確保覆蓋層位於正確的堆疊上下文中。建議對模態框使用原生的 <dialog> 元素——它會自動管理其頂層堆疊,提供 ::backdrop 偽元素用於遮罩,並原生處理 Escape 鍵關閉。
  • 背景遮罩(Scrim): 用於模態框和抽屜,以調暗背景並集中注意力。定義點擊背景遮罩是否關閉覆蓋層。使用 <dialog> 時,請透過 ::backdrop 設定遮罩樣式,而不是手動渲染一個覆蓋的 <div>。
  • 背景不活動性: 當覆蓋層開啟時,頁面的其餘部分必須不可互動,並對輔助技術隱藏。<dialog>.showModal() 會自動執行此操作;對於自訂(非 <dialog>)的覆蓋層,請對背景內容應用 inert 屬性,而不是僅依賴 aria-hidden。
  • 陰影: 使用深度來指示覆蓋層位於基礎層之上的位置。

4. 設計響應式適應

覆蓋層必須根據螢幕尺寸進行轉換:

  • 桌面彈出面板 → 行動裝置抽屜: 小型上下文選單通常會變成行動裝置上底部對齊的抽屜,以便於拇指觸及。
  • 桌面模態框 → 行動裝置全螢幕: 大型模態框應在小螢幕上佔據整個視埠,以最大化空間。
  • 抽屜行為: 確保抽屜在行動裝置上不超過視埠寬度的 90%。

5. 定義關閉與退出模式

  • 提供至少三種關閉非關鍵覆蓋層的方式:「關閉」按鈕、Escape 鍵以及點擊背景遮罩。
  • 對於關鍵(警報)模態框,要求執行明確操作(例如「取消」或「確認」)。

決策規則

  • 「模態框 vs. 抽屜」規則: 如果使用者需要在工作時參考背景內容,請使用抽屜。如果任務是需要「停下並修正」的時刻,請使用模態框。
  • 「拇指」規則: 在行動裝置上,請優先使用底部抽屜來執行操作,以使其保持在拇指的自然觸及範圍內。
  • 「兩步驟」規則: 如果一個覆蓋層需要兩個以上的內部「檢視」或步驟,則它很可能屬於自己的頁面。
  • 背景遮罩邏輯: 僅對非破壞性的覆蓋層允許「點擊外部關閉」。絕對不要用於可能遺失資料的表單。

限制條件

  • 可存取性: 必須可透過鍵盤導航。模態框必須捕捉焦點(原生 <dialog> 元素在透過 showModal() 開啟時預設執行此操作)。背景內容必須設為 inert(或等效處理),以便螢幕閱讀器和鍵盤焦點無法逃逸到其中。未使用原生元素時,請使用 role="dialog" 或 role="alertdialog",並搭配 aria-modal="true" 和指向標題的 aria-labelledby。
  • 響應性: 覆蓋層絕不能導致水平滾動。內部的內容必須具有回應性。
  • 層級結構: 覆蓋層的 H1/標題必須是容器內最突出的元素。

常見失敗模式

  • 覆蓋混亂: 在多個模態框上層層堆疊。
  • 上下文遺失: 使用模態框覆蓋了使用者完成任務所需的確切資訊。
  • 「隱形關閉」: 隱藏關閉按鈕,或使其太小而無法觸控(最小 44x44px)。
  • 滾動衝突: 允許背景頁面在覆蓋層開啟時滾動(導致迷失方向)。
  • 操作不一致: 在不同覆蓋層之間交換「取消」和「確認」按鈕的位置。

驗證標準

  • 所選模式(模態框/抽屜/彈出面板)與任務的中斷層級匹配。
  • 內部層級結構清晰,具有明確的標題和主要操作。
  • 已為行動裝置定義響應式適應(例如彈出面板轉為抽屜)。
  • 「點擊外部關閉」邏輯適合資料風險。
  • 已指定焦點管理和鍵盤可存取性要求。
  • 高程(陰影/背景遮罩)將圖層與基礎頁面區分開來。
  • 每當開啟模態框或抽屜時,背景內容都會設為 inert(或使用原生 <dialog> 元素)。

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.

相關技能