Floating UI tooltip

Floating UI tooltip 表示 tooltip/气泡说明已经被当成正式交互层来维护，而不是临时 title 文本。这里默认采用 @floating-ui/react 一类定位中间件，处理视口避让、箭头、滚动更新和交互稳定性，而不是手写定位魔法。

它通常会和 Responsive web UI、Embedded admin UI、Ops tool 一起出现，但不替代这些 Topic：Floating UI tooltip 解释的是小型浮层交互契约，其他 Topic 解释页面布局、控制台交付或产品定位（projects/dockrev.md）。

当 UI 里有重要 tooltip/浮层说明，需要跨滚动、窄屏、边缘位置和状态切换保持可读可点击时使用。若只是静态提示文本、对位置稳定性没有要求，则不必提升为 Topic。

如果一个改动会影响 tooltip 定位中间件、箭头渲染、auto update、hover/focus 语义、窄屏避让或与按钮/状态说明的交互链路，就应该命中本 Topic。

• 交互默认组合：offset + flip + shift + arrow，并开启 autoUpdate 以覆盖滚动/尺寸变化。证据：projects/dockrev.md（对应实现 web/src/ui.tsx）
• 对可点击按钮气泡，优先“可见性与稳定性”：气泡文本可读、箭头存在、不得超出视口。证据：projects/dockrev.md（样式与渲染在 web/src/App.css）
• 用自动化回归兜底 tooltip 语义（如 active 态 hint 文案与交互链路），避免后续样式改动回退。证据：projects/dockrev.md（测试在 web/scripts/test-storybook.mjs）
• 浮层文本在这里不是装饰，而是操作语义的一部分。对运维控制台，tooltip 常常承载“为什么按钮不可用/当前状态代表什么”之类关键解释。
• 回答此 Topic 时，应把 hover/focus/键盘与窄屏行为一起考虑，而不是只关心一个视觉位置。
• 若 tooltip 已成为状态说明面，就应纳入 Storybook 或自动化回归，不应在每次样式调整后靠人工猜测是否仍可用。

• projects/dockrev.md：直接样本。它适合说明在密集运维控制台里，tooltip 不是“加点说明”，而是需要经得起视口变化和状态切换的正式交互层。

• 把普通静态提示误写成 Floating UI tooltip，会让 Topic 过宽。
• 把 Floating UI tooltip 当成整个仓库的总括标签，忽略 Responsive web UI、Embedded admin UI、Ops tool 等相邻 Topic，会让后续 Agent 无法判断真正该看的是浮层交互、页面布局还是产品上下文。
• 手写定位或只测桌面视口，常常会让 tooltip 在滚动、窄屏或边缘位置直接失效。
• 不把 tooltip 语义纳入回归，也会让“说明性 UI”在重构后悄悄变成不可用装饰。

• projects/dockrev.md
• skills/style-playbook/references/data/topics/floating-ui-tooltip.json