Communitygithub.com

coastdigitalgroup/coastai-skills

设计一套系统化的非持久性UI层级(模态框、抽屉、弹出面板)框架,平衡用户焦点、上下文与打断级别。

coastai-skills 是什么?

该技能提供了一套系统化方法来管理临时内容层面,确保用户任务被打断的程度与其当前工作流相匹配,同时尽可能保留上下文信息。它适用于模态框(高打断)、抽屉(中打断)和弹出面板(低打断)三种模式,支持桌面和移动端的自适应转换。技能详细定义了内容量、打断级别、触发上下文和平台视口四个输入维度,输出模式选择、解剖结构规范、行为规范和可访问性要求。它强调使用原生 `<dialog>` 元素以获得更好的栈管理和焦点锁定,并提供了关键决策规则(如模态vs抽屉、拇指法则、两步法则)和常见失败模式清单。

兼容平台~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 的新对话。

文档

覆盖层与对话框系统

目的

覆盖层与对话框系统技能提供了一种管理位于主界面之上的临时内容层的方法论。它确保用户任务的打断程度是成比例的,在可能的情况下保留上下文,并且在使用模态框、抽屉或弹出面板时,界面保持可访问和响应迅速。

使用场景

  • 为破坏性操作设计确认流程(模态框)。
  • 创建二级工作区以编辑复杂细节,同时不丢失页面上下文(抽屉)。
  • 为特定 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 键关闭。
  • 背景板(遮罩): 用于模态框和抽屉,以调暗背景并吸引注意力。定义点击背景板是否关闭覆盖层。使用 <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.

相关技能