{
  "id": "onboarding-tour",
  "type": "patterns",
  "status": "published",
  "name": {
    "zh": "新手引导",
    "en": "Onboarding Tour"
  },
  "aliases": [
    "新手引导",
    "功能引导",
    "引导蒙层",
    "步骤引导",
    "高亮引导",
    "首次使用引导"
  ],
  "category": [
    "Navigation",
    "Guidance"
  ],
  "description": {
    "zh": "用\"蒙层 + 聚光高亮 + 分步气泡\"的方式带用户认识界面：每一步只露出一个关键区域并就地解释， 上一步/下一步与步骤指示器控制节奏，可随时跳过。它把功能说明放在功能发生的位置， 而不是让用户去文档里自己找。",
    "en": "Introduces an interface with an overlay, a spotlight cutout and step bubbles: each step reveals one key area and explains it in place, paced by prev/next controls and a step indicator, always skippable. The explanation lives where the feature happens instead of making users hunt for docs."
  },
  "use_when": [
    {
      "zh": "界面有 3～5 个核心功能值得主动介绍",
      "en": "There are 3–5 core features worth introducing proactively"
    },
    {
      "zh": "新版本上线，重要入口的位置或含义变了",
      "en": "A release moved or re-meaning of key entry points"
    },
    {
      "zh": "目标用户多为首次访问，且功能不易自行发现",
      "en": "Most visitors are first-timers and features are hard to discover alone"
    }
  ],
  "avoid_when": [
    {
      "zh": "界面足够简单，用户自己探索更快",
      "en": "The UI is simple enough to explore faster without a tour"
    },
    {
      "zh": "步骤太多太长，用户会连点跳过等于白做",
      "en": "Long tours get button-mashed through and teach nothing"
    },
    {
      "zh": "每次进入都强制播放，应只在首次出现且可重看",
      "en": "Forcing it on every visit — show once, keep a replay entry"
    }
  ],
  "tags": [
    "onboarding",
    "tour",
    "guidance",
    "overlay"
  ],
  "variants": [
    {
      "id": "spotlight",
      "name": {
        "zh": "聚光引导",
        "en": "Spotlight"
      },
      "note": {
        "zh": "蒙层挖洞高亮目标区域，注意力最聚焦",
        "en": "The overlay cuts a hole around the target, tightest focus"
      }
    },
    {
      "id": "tooltip-sequence",
      "name": {
        "zh": "气泡序列",
        "en": "Tooltip sequence"
      },
      "note": {
        "zh": "依次弹出说明气泡，不打断整页",
        "en": "Sequential bubbles that never block the whole page"
      }
    },
    {
      "id": "checklist",
      "name": {
        "zh": "任务清单",
        "en": "Checklist"
      },
      "note": {
        "zh": "侧边清单列出待办引导，用户自选节奏",
        "en": "A side checklist users complete at their own pace"
      }
    }
  ],
  "anatomy": [
    "半透明蒙层（Overlay）",
    "高亮目标区（Spotlight target）",
    "说明气泡（Explanation bubble）",
    "步骤指示与跳过（Step indicator & skip）"
  ],
  "applicable_styles": [
    "minimalism",
    "bento-grid"
  ],
  "applicable_components": [
    "tooltip",
    "popover"
  ],
  "applicable_pages": [
    "dashboard",
    "settings"
  ],
  "related": [
    {
      "id": "tooltip",
      "relation": "used_with"
    },
    {
      "id": "popover",
      "relation": "used_with"
    },
    {
      "id": "modal",
      "relation": "used_with"
    },
    {
      "id": "progressive-disclosure",
      "relation": "similar_to"
    },
    {
      "id": "empty-state",
      "relation": "similar_to"
    }
  ],
  "demo": {
    "component": "onboarding-tour",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "implementation": {
    "css": [
      "position: absolute",
      "box-shadow",
      "z-index",
      "transition"
    ],
    "notes": {
      "zh": "蒙层常用巨大 box-shadow（目标元素套 ring/box-shadow 实现挖洞感）或四块遮罩拼出洞口； 气泡按目标元素 getBoundingClientRect 定位到上下左右。步骤状态用 useState 索引驱动， 支持 Esc 关闭与点击蒙层跳过。过渡尊重 prefers-reduced-motion，直接切换无动画。",
      "en": "Build the overlay with a huge box-shadow on the target (or four mask blocks) to fake the cutout; position the bubble via the target's getBoundingClientRect. Drive steps with a useState index, support Esc and overlay-click to dismiss. Transitions respect prefers-reduced-motion by jumping without animation."
    }
  },
  "sources": [
    {
      "name": "Nielsen Norman Group — Onboarding",
      "url": "https://www.nngroup.com/articles/first-two-days-onboarding/"
    },
    {
      "name": "Material Design — Feature discovery",
      "url": "https://m3.material.io/foundations/interactive-patterns/feature-discovery/overview"
    }
  ],
  "prompts": {
    "basic": {
      "zh": "创建一个新手引导（Onboarding Tour）演示，分步高亮界面关键区域并配说明气泡。",
      "en": "Create an onboarding tour demo that highlights key UI areas step by step with explanation bubbles."
    },
    "design": {
      "zh": "创建新手引导演示。要求：模拟界面含 3 个关键区域，蒙层聚光当前步骤目标，气泡就近解释功能； 提供上一步/下一步、步骤圆点与\"跳过引导\"按钮；结束后可点\"重播引导\"再次演示。",
      "en": "Create an onboarding tour demo. Requirements: a mock UI with 3 key areas, an overlay spotlighting the current step's target, a nearby bubble explaining the feature; prev/next buttons, step dots and a skip; a \"replay tour\" entry after finishing."
    },
    "implementation": {
      "zh": "用 React 实现 Onboarding Tour：步骤数组保存目标选择器与文案，useState 记录当前步； 目标元素加高亮 ring 与放大 box-shadow 模拟挖洞，气泡绝对定位在目标旁。支持 Esc 跳过， 结束后提供重播按钮。动画尊重 prefers-reduced-motion。",
      "en": "Implement Onboarding Tour in React: a step array of target selectors and copy, a useState index; highlight targets with a ring and an oversized box-shadow to fake the cutout, with the bubble absolutely positioned nearby. Support Esc to skip and a replay button after finishing. Respect prefers-reduced-motion."
    },
    "agent": {
      "zh": "在当前项目中实现新手引导（Onboarding Tour）。\n\n先检查现有 tooltip/popover 组件，气泡样式优先复用。\n用途：工作台首次访问的功能介绍。\n要求：\n- 3～5 步，每步聚光一个关键区域并就地解释\n- 支持上一步/下一步、步骤指示、随时跳过\n- 只在首次访问自动出现，提供重播入口\n- 不新增依赖\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement an onboarding tour in the current project.\n\nInspect existing tooltip/popover components first; reuse bubble styling.\nUsage: introducing workspace features on first visit.\nRequirements:\n- 3–5 steps, each spotlighting one key area with in-place explanation\n- Prev/next controls, step indicator, skippable at any time\n- Auto-show on first visit only, with a replay entry\n- No new dependencies\nRun existing project checks when done and list the modified files."
    }
  }
}