# Overlay Best Practices

Use `@langgenius/dify-ui/*` primitives for overlays in new and modified web
code. Do not import raw Base UI overlays or legacy web overlays from
`@/app/components/base/modal`, `@/app/components/base/dialog`, or
`@/app/components/base/drawer`.

## Primitive choice

- Use `@langgenius/dify-ui/dialog` for modal surfaces that need focus
  management, scroll locking, escape handling, and outside-press dismissal.
- Use `@langgenius/dify-ui/alert-dialog` only for destructive or must-confirm
  decisions.
- Use `@langgenius/dify-ui/drawer` for side panels, setup panels, and nested
  editor panels that must behave like a drawer. Do not add separate web drawer
  wrappers.
- Use `@langgenius/dify-ui/popover` or the web `Infotip` wrapper for
  explanatory content, long help text, rich layout, or interactive content.
- Use `@langgenius/dify-ui/tooltip` only for short, non-interactive labels where
  the trigger already has its own accessible name.

## Preferences

- Prefer the most specific semantic primitive over styling a generic `Dialog`.
- Prefer controlled `open` / `onOpenChange` when business state, analytics, or
  cleanup must react to open state changes.
- Prefer the primitive-owned portal or content component. Do not create manual
  portals around overlay primitives.
- Prefer native button trigger semantics. When passing a Base UI trigger
  `render` prop, render a real `<button type="button">` for button-like
  triggers; use `nativeButton={false}` only for intentional non-button triggers.
- Use `Infotip` for visible `?` help triggers. Give icon-only triggers an
  accessible name.
- Keep overlay chrome inside the shared primitive or business wrapper instead of
  repeating backdrop, z-index, and portal styles at call sites.

## Layering

All body-portalled Dify UI overlays use `z-50`. Toast uses `z-60`. The app root
must keep an isolated stacking context.

Do not add call-site z-index overrides such as `z-9999`. If an overlay is
clipped or hidden, fix the parent overlay structure instead of raising the
child primitive.