From 7d27f5d6c4d992319265989e36b15e7dcc8a51ca Mon Sep 17 00:00:00 2001
From: yyh <yuanyouhuilyz@gmail.com>
Date: Sat, 9 May 2026 12:25:33 +0800
Subject: [PATCH] docs(web): align tooltip migration guidance

---
 packages/dify-ui/README.md    | 7 +++++++
 web/docs/overlay-migration.md | 8 ++++++++
 web/eslint.constants.mjs      | 3 ++-
 3 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/packages/dify-ui/README.md b/packages/dify-ui/README.md
index 2915fe5db7..fd75042d76 100644
--- a/packages/dify-ui/README.md
+++ b/packages/dify-ui/README.md
@@ -99,6 +99,13 @@ See `[web/docs/overlay-migration.md](../../web/docs/overlay-migration.md)` for t
 - Never create an extra manual portal on top of our primitives — use the exported content / portal parts such as `DialogContent`, `PopoverContent`, and `DrawerPortal`. Base UI handles focus management, scroll-locking, and dismissal.
 - When a primitive needs additional presentation chrome (e.g. a custom backdrop), add it **inside** the exported component, not at call sites.
 
+### Tooltip, infotip, and popover semantics
+
+- Use `Tooltip` only for short, non-interactive visual labels. The trigger must already have visible text or an `aria-label`; the tooltip is not the accessible name and must not contain links, buttons, forms, or structured prose.
+- Use `Popover` for explanatory content, long text, rich layout, or anything users may need to reach on touch or with assistive technology. In `web/`, the `Infotip` wrapper is the preferred pattern for a `?` help glyph backed by `Popover`.
+- Do not copy legacy tooltip offsets into migrated call sites. Pick a `placement` and let the primitive own spacing.
+- When passing a Base UI trigger `render` prop, render a real `<button type="button">` for button-like triggers. If a Popover trigger must render a `div`, `span`, or another non-button element, pass `nativeButton={false}`.
+
 ## Development
 
 - `pnpm -C packages/dify-ui test` — Vitest unit tests for primitives.
diff --git a/web/docs/overlay-migration.md b/web/docs/overlay-migration.md
index b849159867..807bc2fc68 100644
--- a/web/docs/overlay-migration.md
+++ b/web/docs/overlay-migration.md
@@ -8,6 +8,7 @@ This document tracks the Dify-web migration away from legacy overlay APIs.
 
 - Deprecated imports:
   - `@/app/components/base/tooltip`
+  - `@/app/components/base/tooltip/content`
   - `@/app/components/base/modal`
   - `@/app/components/base/dialog`
   - `@/app/components/base/drawer`
@@ -36,6 +37,8 @@ This document tracks the Dify-web migration away from legacy overlay APIs.
 1. Business/UI features outside `app/components/base/**`
    - Migrate old calls to semantic primitives from `@langgenius/dify-ui/*`.
    - Keep deprecated imports out of newly touched files.
+   - Use `@langgenius/dify-ui/tooltip` only for short, non-interactive labels where the trigger already has its own accessible name.
+   - Use `@langgenius/dify-ui/popover` or the web `Infotip` wrapper for explanatory, long-form, structured, or interactive content.
 1. Legacy base components
    - Migrate legacy base callers gradually.
    - Keep deprecated imports out of newly touched files.
@@ -75,6 +78,11 @@ back to `z-9999`.
   parent legacy overlay should be migrated instead.
 - When migrating a legacy overlay that has a high z-index, remove the z-index
   entirely — the new primitive's default `z-1002` handles it.
+- Do not preserve legacy tooltip offsets at call sites. Choose the nearest
+  `placement`/side alignment and let the primitive own its default spacing.
+- When using Base UI trigger `render`, render a real `button` for button-like
+  triggers. If the trigger must render a non-button element, the primitive must
+  explicitly opt out of the native button behavior where that API is available.
 
 ### Post-migration cleanup
 
diff --git a/web/eslint.constants.mjs b/web/eslint.constants.mjs
index f74c5c9115..16a4b4a7a8 100644
--- a/web/eslint.constants.mjs
+++ b/web/eslint.constants.mjs
@@ -49,8 +49,9 @@ export const OVERLAY_RESTRICTED_IMPORT_PATTERNS = [
     group: [
       '**/base/tooltip',
       '**/base/tooltip/index',
+      '**/base/tooltip/content',
     ],
-    message: 'Deprecated: use @langgenius/dify-ui/tooltip instead. See issue #32767.',
+    message: 'Deprecated: use @langgenius/dify-ui/tooltip for short labels; use Popover/Infotip for rich or explanatory content. See issue #32767.',
   },
   {
     group: [