Communitygithub.com

coastdigitalgroup/coastai-skills

设计并构建多步骤引导式产品导览和入门教程的系统化框架,管理锚点定位、遮罩层、交互层级和响应式适配。

coastai-skills 是什么?

该技能提供了一套完整的设计方法论,用于构建结构清晰、样式一致、协调有序的多步骤引导式产品导览。其核心目标是降低用户在新功能首次使用或重大版本更新时的认知负荷,通过视觉隔离关键界面元素、提供顺序化且高度相关的上下文信息,引导用户快速进入可操作的成功状态。该技能避免了混乱、侵入性强的导览,通过建立可预测、可访问且由用户控制节奏的体验来提升用户满意度。它支持主流的开发平台和设计系统,涵盖了从信息架构输入到最终可访问性验证的全流程,包括定义步骤序列、设计遮罩蒙版、构建弹出卡片、编写无障碍代码以及制定移动端适配策略。该技能还提供了详细的决策规则和约束条件,帮助开发者在各种复杂场景中做出正确选择,并避免常见的失败模式,如导览步骤过多、焦点冲突、移动端气泡挤压等问题。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

引导式导览系统

目的

本引导式导览系统技能提供了一套完整的设计方法,用于结构化、样式化并协调多步骤引导式产品导览。其目的是在用户首次使用或重大功能发布时,通过视觉隔离关键界面元素、提供顺序化且高度相关的上下文信息,引导用户进入活跃的成功状态,从而降低认知负荷。该系统通过建立可预测、可访问且由用户控制节奏的体验,避免混乱、侵入性强的导览。

使用场景

  • 首次用户入门: 引导新注册用户完成复杂SaaS应用的核心工作流,从而驱动激活。
  • 新功能推广: 向现有用户高亮并解释新发布的高价值工具或界面元素。
  • UI重新设计熟悉化: 帮助老用户在进行重大界面调整或重组后,快速找到熟悉的工具。
  • 复杂分步数据录入导览: 在用户进行初始设置(例如设置第一条自动化规则)时,引导其完成多面板仪表盘的操作。

不适用场景

  • 自解释性界面: 如果任务可以通过更清晰的布局、更好的标签或直观的图标简化,应首先改进核心UI,而不是通过导览来掩盖不佳的UX。
  • 高度重复的微任务: 避免用弹出窗口打断频繁的工作流。对于常规帮助,请使用工具提示与提示系统或内联帮助文本。
  • 仅限移动设备或低分辨率界面: 多步骤锚定式气泡导览会占用大量屏幕空间,在移动设备上极易发生裁剪或重叠。请改用全屏卡片或可关闭的内联步骤。
  • 关键错误或事务性反馈: 对于即时系统反馈或错误信息,请使用横幅与警告系统或提示与Snackbar系统。

输入

  1. 信息架构与上下文: 导览将运行的特定页面布局、仪表盘分区或UI坐标。
  2. 锚定元素清单: 需要在每一步中高亮的特定目标按钮、输入框、表格或导航链接。
  3. 入门里程碑("为什么"): 完成入门并确保激活所需的最少关键操作。
  4. 设备断点: 导览必须渲染的响应式目标视口,遵循响应式网格系统的指南。

输出

  1. 背景遮罩与蒙版规范: 视觉隔离目标元素,同时使界面其余部分变暗,以集中用户注意力。
  2. 气泡(导览卡片)组件规范: 导览气泡的详细结构蓝图(箭头、正文、步骤指示器、跳过/下一步/返回按钮、关闭控件)。
  3. 序列与流程逻辑: 分步路径映射、进度模型(严格线性 vs. 用户驱动)以及会话持久化。
  4. 响应式策略与移动端降级方案: 针对无法安全放置浮动锚定气泡的小屏幕的适配规则。
  5. 无障碍地标与交互规范: 完整的ARIA规范、键盘导航图以及焦点捕获行为。

工作流

1. 定义步骤序列(最佳路径)

  • 将导览序列限制在3至5步(米勒定律)。超过此长度会导致高放弃率。
  • 每一步都要关注活跃的益处,而不仅仅是标签。(例如,不要写“这是设置菜单”,而要写“在此处自定义您的工作区以匹配团队的工作流程”)。
  • 确保最后一步有一个清晰、可操作的行动号召(CTA),使用户处于活跃、高效的状态。

2. 设计背景遮罩与隔离(焦点)

  • 使用深色半透明背景覆盖层(通常为#000000,透明度50-70%)来淡化背景噪音并聚焦视线。
  • 在活跃的锚定元素周围创建“隔离蒙版”(使用SVG路径剪裁或CSS clip-path / box-shadow)。
  • 在被高亮锚点周围保持4px至8px的内边距缓冲,以防止蒙版过度紧贴元素边框。

3. 构建气泡(导览卡片)层级结构

  • 锚定对齐: 动态地将气泡位置设置在高亮元素旁边。使用一个小的方向性箭头/指针将卡片与锚点视觉连接。
  • 组件结构:
    • 头部: 包含标准的关闭按钮('X')和进度指示器(例如“第2步,共4步”)。
    • 正文: 使用简洁、有力的标题,最多2句话的描述文本。
    • 操作栏: 左侧对齐“跳过”链接,右侧对齐导航按钮。确保“下一步”(或“知道了”)使用主CTA样式,而“返回”使用低对比度的三级样式。

4. 编写可访问性代码(键盘与屏幕阅读器一致性)

  • 焦点捕获: 当导览步骤激活时,键盘焦点(Tab键)必须限制在导览气泡内,以防止键盘用户导航到背景元素。
  • ARIA关联: 确保气泡容器使用role="dialog"或role="alertdialog",并设置aria-modal="false"(这样辅助技术就能知道背景元素仍然存在)。使用aria-labelledby将气泡标题与内容关联,使用aria-describedby将描述与内容关联。
  • 键盘快捷键: 支持键盘导航:Escape键关闭/跳过导览,ArrowRight键用于“下一步”,ArrowLeft键用于“返回”。

5. 制定移动端适配策略

  • 如果视口宽度小于768px(平板/手机),则从浮动锚定气泡切换为底部抽屉面板或居中、非锚定的模态框。这样可以防止卡片被推出屏幕或覆盖关键元素。
  • 在移动设备上禁用或简化背景蒙版,以防止由移动端滚动引起的裁剪错误。

决策规则

  • 线性导览 vs. 用户驱动任务列表:
    • 如果步骤A必须严格在步骤B之前完成,则使用线性导览进行严格的首次设置序列。
    • 如果任务可以按任意顺序完成,则使用交互式进度小部件(任务列表),允许用户按自己的节奏选择任务。
  • 触发条件:
    • 仅在首次运行或明确更新后自动触发。
    • 永远不要在标准访问中为返回用户自动触发导览。
  • 锚定位置覆盖:
    • 默认: 将气泡放置在锚点元素的“底部居中”或“右侧居中”。
    • 碰撞规则: 如果锚点靠近屏幕边缘,则翻转气泡放置方向以防止裁剪(例如,从“右侧”翻转为“左侧”)。如果锚点被隐藏(在折叠面板内),则先以编程方式展开面板,然后再渲染气泡。
  • “跳过”功能:
    • 始终在每个步骤中提供可见的“跳过导览”或“关闭”操作。强迫用户完成导览而不提供退出选项会引发挫败感。

约束条件

  • 可访问性(WCAG 2.2):
    • 导览卡片内的文本对比度必须满足WCAG AA标准(至少4.5:1)。
    • 交互式按钮上必须存在高对比度的视觉焦点环(outline)。
    • 下一步/返回按钮的触摸目标必须至少44x44px(推荐)或满足24x24px最小值(WCAG 2.2 SC 2.5.8)。
    • 背景剪裁区域内的交互式锚点必须可以获得焦点。
  • 布局偏移管理:
    • 背景、剪裁蒙版和气泡的显示不得移动现有布局元素。使用相对于文档视口的position: absolute或position: fixed。
  • Z-index对齐:
    • 背景和导览卡片必须位于顶层实用程序警告(如Toast消息)之下(例如,背景z-index为900,气泡z-index为910),以确保高优先级系统警报仍能穿透显示。

常见失败模式

  • “无限导览”陷阱: 导览步骤超过5步,导致用户立即放弃。
  • “双重焦点”冲突: 在已有活动模态框的页面上自动启动导览,造成叠加覆盖层和输入控件被阻塞。
  • 盲目高亮锚点: 高亮了一个已滚动出屏幕或已折叠的元素,箭头指向空白区域。
  • 不可操作的背景元素: 要求用户在遮挡元素中输入才能继续,但背景蒙版阻止了他们的输入或鼠标点击。
  • 移动端气泡挤压: 锚定气泡在移动设备上缩小到不可读的宽度,导致单词断行不自然。

验证标准

  • 导览严格限制在3-5步。
  • 每一步都有清晰标注、可见的“跳过”或关闭选项。
  • 在活动步骤期间,键盘Tab焦点被限制在气泡内。
  • 当按下“下一步”时,焦点平滑移动到下一个导览卡片(或新高亮的元素)。
  • 正确配置ARIA属性(role="dialog"、aria-modal、aria-describedby)。
  • 定义了气泡碰撞处理规则(靠近屏幕边缘时自动翻转位置)。
  • 移动端视口优雅地从锚定气泡过渡为居中模态框或持久底部抽屉面板。
  • 在被隔离的锚点周围保持4-8px的内边距缓冲,以避免裁剪边框。
  • 所有按钮的活跃和悬停状态满足WCAG AA标准(4.5:1对比度)。

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.

相关技能