tour-guide-supademo

tour-guide-supademo — Supademo 风格的 tour

从 Supademo 播放器（supademo.com，2026-06）提炼而来。其文档未公布精确的十六进制颜色值和像素值——以下是将设计语言转化为可直接使用的配方。基础组件取自 tour-guide skill；此 skill 是叠加在基础组件上的样式层。

原则：品牌色只用一个令牌（--tour-brand），所有内容都依赖它。

WHAT

用途和背景

• 用途： 为 tour-guide skill 的 tour 组件叠加 Supademo 风格的样式（闪烁热点、提示卡片、控制栏、进度条／计时条、过渡效果、主题令牌），提供可直接复制使用的 Tailwind/CSS 配方，并依赖唯一的品牌令牌。
• 触发条件（何时使用）：“/tour-guide-supademo”、“Supademo 风格的 tour”、“Supademo 样式”、“闪烁热点”；已使用或即将使用 tour-guide 组件，并希望采用 Supademo 风格的界面时。
• 非目标： 不包含 UX 机制（测量／滚动／步骤、分支、计时器机制——这些属于 tour-guide skill）；不硬编码 Supademo 的原始品牌十六进制颜色值；其他产品的样式应作为独立 skill tour-guide-<名称>。

心智模型

--tour-brand（1 个令牌）→ 闪烁热点 · 提示卡片 · 控制栏 · 进度条 · 自动播放计时条 · 过渡效果 · 每个热点的背景遮罩 → 映射到 tour-guide 的 TOUR_THEME。此 skill = 样式层；tour-guide = 基础组件 + 机制。

输入和输出契约

	字段	必填？	含义
In	来自 tour-guide skill 的 tour 组件	是	用于叠加样式的基础
In	品牌色	是	赋值给 --tour-brand
In	theme light/dark、showProgress、showNav、showStepCount	否	主题令牌，映射到 TOUR_THEME
Out	按配方编写的 tour CSS/Tailwind	是	闪烁热点 + 卡片 + 控制栏 + 各类条 + 过渡效果
Out	“跳过菜单步骤”复选框行为 + 自动打开关闭	是	来自实战经验

规则和能力

• RULE-01（MUST）：原则：品牌色只用一个令牌（--tour-brand），所有内容都依赖它。
• RULE-02（MUST）：提示框字体固定为 1rem——不要把提示框文字做得像提示信息一样小；提供 S/M/L 三种宽度，标签较长时不要根据文字自动调整宽度。
• RULE-03（MUST）：除非收到明确要求，否则页面加载时不要自动打开 tour（自动打开：默认关闭）。
• RULE-04（MUST）：复选框用于“跳过框架步骤”——不是“以后都不显示 tour”；使用 localStorage + window.name 两层持久化，并用 try/catch 包裹。
• RULE-05（MUST）：扩展约定——其他产品的样式应按此文件的格式提炼为独立 skill tour-guide-<名称>；UX 机制交由 tour-guide skill。
• 能力：向目标项目写入 CSS/Tailwind/TSX；读取 tour-guide 组件。不联网。

失败边界

• 项目中还没有 tour-guide 组件 → 阻塞：先用 tour-guide skill 搭建基础组件。
• 需求属于 UX 机制（步骤模式、分支、计时器）→ 超出范围，转交 tour-guide。
• 需求是其他产品的样式（Intercom、Driver.js 等）→ 不要加到这里；创建 tour-guide-<名称>。
• Supademo 精确的十六进制颜色值／像素值 → 无法提供（其文档未公布）；使用换算后的配方，并明确说明是估算值。

HOW

主要工作流

Step	类型	输入	操作	输出／退出	失败／后续
W01	判断	需求	确认已有 tour-guide 组件，且当前任务是样式调整	继续	缺少基础组件 → 先处理 tour-guide
W02	效果	品牌色	设置 --tour-brand，将主题令牌映射到 TOUR_THEME	令牌	—
W03	效果	配方	应用闪烁热点、提示卡片、控制栏（含复选框）、进度条 + 自动播放计时条、过渡效果、每个热点的背景遮罩	为 tour 添加 Supademo 风格	控制栏溢出 → 将复选框移至单独一行
W04	判断	正在运行的 tour	检查：自动打开已关闭、复选框立即生效、Esc 可关闭、字体为 1rem	达标	不符合 → 修改并重复 W04

各步骤详情（W01–W04 的权威来源）：见“参考——Supademo 设计配方”部分。

分支

ID	类型	条件	行为	跳过 / 失败	汇合点
B01	user_optional	spot 只需要 ring + blinker，不需要 dim	在 TourSpot 上添加 flag noDim?: boolean	默认 dim	W04
B02	user_optional	明确要求首次自动打开	在 delay 前后都检查 guard !overlay	默认关闭	W04
B03	user_optional	label 较长，demo 风格	为 label 添加打字机效果	默认不添加	W04
B04	conditional_required	勾选框已勾选时，页面没有独立 step	关闭 tour	—	结束

验证和停止

需要人工检查：card 宽 280px 时不溢出、字体为 1rem、blinker 正好位于 target 中心。可确定性检查：勾选框在重新加载后仍保留状态（localStorage/window.name）、Esc 关闭、点击背景进入下一步。W04 达成后停止。

示例

• 正向：“Supademo 风格的紫色 dashboard tour” → --tour-brand = 紫色，blinker 在按钮中心使用 animate-ping，card M ≈ 280px，rounded-xl，control bar 为 4 / 9 + [返回] [继续]，overlay 顶部边缘显示 2–3px progress bar。
• **边界/失败：**在 280px 的 card 中，让 control bar 把勾选框 + counter + 2 个按钮塞进同一行 → 溢出；将勾选框移到单独一行，并添加 white-space:nowrap。用户想要“Intercom 风格的 tour” → 不修改此文件，提炼 skill tour-guide-intercom。

参考 — Supademo 设计配方

Blinker 热点（标志性外观）

约 12px 的品牌色圆点，加上向外扩散的 ripple 圈 animate-ping，放在需要点击的 element 中心。外圈透明度约为 25–30%。

<span className="absolute flex h-3 w-3" style={{ top: cy, left: cx }}>
  <span className="absolute inline-flex h-full w-full animate-ping rounded-full opacity-30"
    style={{ background: "var(--tour-brand)" }} />
  <span className="relative inline-flex h-3 w-3 rounded-full"
    style={{ background: "var(--tour-brand)" }} />
</span>

适合 step mode：blinker 指向需要点击的位置，tooltip 在旁边进行说明。

Tooltip card

• 白色背景；dark theme：bg-slate-900 text-white。
• 圆角 rounded-xl（约 12px），柔和阴影 shadow-[0_4px_16px_rgba(0,0,0,0.12)]，内边距 px-3.5 py-2.5。
• 字体固定为 1rem —— Supademo 刻意不提供字号调整；不要把 tooltip 文字缩小得像提示信息一样。
• 小箭头指向 target。
• 3 种宽度：S ≈ 200px / M ≈ 280px / L ≈ 360px —— label 较长时不要按文字自动调整宽度。

Control bar（所有步骤共用）

Tooltip card 底部一行，布局固定：[退出方式] · i/n ……… [返回] [继续/完成]

• 左侧：counter 4 / 9，使用较小的灰色文字（text-xs text-slate-400）；下方单独一行：勾选框 “下次跳过菜单部分”（见下文）。勾选框单独一行并设置 white-space:nowrap —— 280px 的 card 无法在一行中容纳勾选框 + counter + 2 个按钮（会溢出）。
• 右侧：Back（ghost）+ Next（品牌色背景，rounded-lg px-3 py-1.5）。
• 按钮 label 可以自定义（“继续”“完成”），不必始终使用 Next/Previous。
• Esc 始终关闭；点击背景 = 下一步（最后一步 = 关闭）。

“跳过重复 step”勾选框（实战经验）

多页面 tour 总有两类 step：通用部分（菜单/sidebar/header——每个页面都相同）和页面专属部分。User 看过一次通用部分就够了——每次打开 tour 都得重新看，是最令人恼火的问题。

• 勾选框 = [ ] 跳过菜单部分（label 简短——user 反馈：不要冗长地写“下次……”）——不是“以后不再显示 tour”。勾选 → flag 持久保存；measure() 过滤掉通用 spots 组，只保留当前 active view 的 data-tour-* spots。测量/滚动/step 机制由 skill tour-guide 负责。
• 勾选后立即生效：重新测量并跳到第一个内容 step（steps=measure(); idx=0; render()），不要让 user 把通用部分走完。页面没有专属 step → 关闭 tour。
• 取消勾选（重新打开 tour 时会看到已勾选的框）→ 删除 flag，菜单重新出现在列表中。
• 两层持久化：localStorage + window.name（使用 file:// 时浏览器可能会阻止 storage——window.name 会在同一 tab 重新加载后保留）。用 try/catch 包裹。
• 在 overlay 上使用 change delegation 监听（每一步都会通过 innerHTML 重新渲染，不要给 input 绑定 listener）。

自动打开：默认关闭

除非有明确要求，否则加载时不要自动打开导览。经验：自动打开 + 旧缓存／多源（file:// 与 localhost 对应两个不同的 localStorage）会让人觉得“关了还是会出现”，导致用户不再信任切换开关。通过触发按钮（?）打开导览就足够了；如果确实需要首次自动打开，请在延迟前后都检查 !overlay，避免切换关闭用户刚刚自行打开的导览。

进度条

覆盖层顶部边缘显示一条 2–3px 的纤细品牌色横条，width = (step+1)/total*100%，可切换显示。

自动播放计时条

工具提示卡片顶部边缘显示一条 2px 的品牌色横条（不同于屏幕边缘的总进度条）：在自动播放时长内线性地从 0 填充到 100%（默认每步 2.5s——实际测试发现 1.75s 太赶，来不及阅读），然后自动进入下一步。卡片需要设置 overflow:hidden，让横条贴合圆角。悬停在卡片上 → 横条暂停（animationPlayState:paused）；鼠标移开 → 横条和计时器从头开始运行。计时器机制放在 tour-guide skill 中。

过渡效果

• 工具提示进入：淡入 + 轻微滑入（transition-all duration-200，translate-y 4px → 0）。
• 步骤之间：位置不要做动画（直接跳转），仅淡化内容。
• 标签的打字机效果为可选项——只有标签较长、需要演示风格时才值得使用。

按焦点显示背景遮罩

Supademo 的“Default”样式只在元素周围显示描边环，不会调暗屏幕 → 可映射到 TourSpot 上的 noDim?: boolean 标记，让焦点位置只显示描边环 + 闪烁提示。

主题令牌

Supademo 工作区级别可调整以下内容——映射到 tour-guide 的 TOUR_THEME 后，功能相当：

token	含义
brand	主色（闪烁提示、Next、进度条）
theme	工具提示卡片的 "light" | "dark" 主题
showProgress	开启／关闭进度条
showNav	开启／关闭 Back／Next
showStepCount	开启／关闭计数器“i / n”

扩展约定

如果要采用其他产品（Intercom、Driver.js、Stripe 等）的样式 → 按照本文件的格式提炼为独立的 tour-guide-<名称> skill：仅使用一个品牌色令牌，提供可直接复制的 Tailwind／CSS 配方（不做空泛描述），不硬编码原始品牌的十六进制颜色，并在文件末尾注明来源 + 最后提炼日期。UX 机制（步骤模式、分支等）则归入 tour-guide skill，不要放在样式 skill 中。

来源

Hotspot 文档 · HTML hotspots · 工作区主题 — 提炼于 2026-06-10