diff --git a/web/app/components/base/ui/alert-dialog/index.tsx b/web/app/components/base/ui/alert-dialog/index.tsx
index 8d48c5b998..6c76e5ad12 100644
--- a/web/app/components/base/ui/alert-dialog/index.tsx
+++ b/web/app/components/base/ui/alert-dialog/index.tsx
@@ -6,13 +6,6 @@ import * as React from 'react'
 import Button from '@/app/components/base/button'
 import { cn } from '@/utils/classnames'
 
-// z-index strategy (relies on root `isolation: isolate` in layout.tsx):
-//   All overlay primitives (Tooltip / Popover / Dropdown / Select / Dialog / AlertDialog) — z-50
-//   Overlays share the same z-index; DOM order handles stacking when multiple are open.
-//   This ensures overlays inside an AlertDialog (e.g. a Tooltip on a dialog button) render
-//   above the dialog backdrop instead of being clipped by it.
-//   Toast — z-[99], always on top (defined in toast component)
-
 export const AlertDialog = BaseAlertDialog.Root
 export const AlertDialogTrigger = BaseAlertDialog.Trigger
 export const AlertDialogTitle = BaseAlertDialog.Title
@@ -39,7 +32,7 @@ export function AlertDialogContent({
       <BaseAlertDialog.Backdrop
         {...backdropProps}
         className={cn(
-          'fixed inset-0 z-50 bg-background-overlay',
+          'fixed inset-0 z-[1002] bg-background-overlay',
           'transition-opacity duration-150 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
           overlayClassName,
         )}
@@ -47,7 +40,7 @@ export function AlertDialogContent({
       <BaseAlertDialog.Popup
         {...popupProps}
         className={cn(
-          'fixed left-1/2 top-1/2 z-50 max-h-[calc(100vh-2rem)] w-[480px] max-w-[calc(100vw-2rem)] -translate-x-1/2 -translate-y-1/2 overflow-y-auto overscroll-contain rounded-2xl border-[0.5px] border-components-panel-border bg-components-panel-bg shadow-lg',
+          'fixed left-1/2 top-1/2 z-[1002] max-h-[calc(100vh-2rem)] w-[480px] max-w-[calc(100vw-2rem)] -translate-x-1/2 -translate-y-1/2 overflow-y-auto overscroll-contain rounded-2xl border-[0.5px] border-components-panel-border bg-components-panel-bg shadow-lg',
           'transition-[transform,scale,opacity] duration-150 data-[ending-style]:scale-95 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
           className,
         )}
diff --git a/web/app/components/base/ui/context-menu/index.tsx b/web/app/components/base/ui/context-menu/index.tsx
index 1a130549ca..029181421a 100644
--- a/web/app/components/base/ui/context-menu/index.tsx
+++ b/web/app/components/base/ui/context-menu/index.tsx
@@ -74,7 +74,7 @@ function renderContextMenuPopup({
         align={align}
         sideOffset={sideOffset}
         alignOffset={alignOffset}
-        className={cn('z-50 outline-none', className)}
+        className={cn('z-[1002] outline-none', className)}
         {...positionerProps}
       >
         <BaseContextMenu.Popup
diff --git a/web/app/components/base/ui/dialog/index.tsx b/web/app/components/base/ui/dialog/index.tsx
index b86f94c46f..7ca4f92c43 100644
--- a/web/app/components/base/ui/dialog/index.tsx
+++ b/web/app/components/base/ui/dialog/index.tsx
@@ -1,11 +1,14 @@
 'use client'
 
-// z-index strategy (relies on root `isolation: isolate` in layout.tsx):
-//   All overlay primitives (Tooltip / Popover / Dropdown / Select / Dialog) — z-50
+//   z-index strategy (relies on root `isolation: isolate` in layout.tsx):
+//   All base/ui/* overlay primitives — z-[1002]
 //   Overlays share the same z-index; DOM order handles stacking when multiple are open.
 //   This ensures overlays inside a Dialog (e.g. a Tooltip on a dialog button) render
 //   above the dialog backdrop instead of being clipped by it.
-//   Toast — z-[99], always on top (defined in toast component)
+//   During migration, z-[1002] is chosen to sit above all legacy overlays
+//   (Modal z-[60], PortalToFollowElem callers up to z-[1001]).
+//   Once all legacy overlays are migrated, this can be reduced back to z-50.
+//   Toast — z-[9999], always on top (defined in toast component)
 
 import { Dialog as BaseDialog } from '@base-ui/react/dialog'
 import * as React from 'react'
@@ -54,14 +57,14 @@ export function DialogContent({
     <DialogPortal>
       <BaseDialog.Backdrop
         className={cn(
-          'fixed inset-0 z-50 bg-background-overlay',
+          'fixed inset-0 z-[1002] bg-background-overlay',
           'transition-opacity duration-150 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
           overlayClassName,
         )}
       />
       <BaseDialog.Popup
         className={cn(
-          'fixed left-1/2 top-1/2 z-50 max-h-[80dvh] w-[480px] max-w-[calc(100vw-2rem)] -translate-x-1/2 -translate-y-1/2 overflow-y-auto overscroll-contain rounded-2xl border-[0.5px] border-components-panel-border bg-components-panel-bg p-6 shadow-xl',
+          'fixed left-1/2 top-1/2 z-[1002] max-h-[80dvh] w-[480px] max-w-[calc(100vw-2rem)] -translate-x-1/2 -translate-y-1/2 overflow-y-auto overscroll-contain rounded-2xl border-[0.5px] border-components-panel-border bg-components-panel-bg p-6 shadow-xl',
           'transition-[transform,scale,opacity] duration-150 data-[ending-style]:scale-95 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none',
           className,
         )}
diff --git a/web/app/components/base/ui/dropdown-menu/index.tsx b/web/app/components/base/ui/dropdown-menu/index.tsx
index 4c49ab2b58..3f4bf9b34c 100644
--- a/web/app/components/base/ui/dropdown-menu/index.tsx
+++ b/web/app/components/base/ui/dropdown-menu/index.tsx
@@ -131,7 +131,7 @@ function renderDropdownMenuPopup({
         align={align}
         sideOffset={sideOffset}
         alignOffset={alignOffset}
-        className={cn('z-50 outline-none', className)}
+        className={cn('z-[1002] outline-none', className)}
         {...positionerProps}
       >
         <Menu.Popup
diff --git a/web/app/components/base/ui/menu-shared.ts b/web/app/components/base/ui/menu-shared.ts
index a72147f29d..fbd2f9bfeb 100644
--- a/web/app/components/base/ui/menu-shared.ts
+++ b/web/app/components/base/ui/menu-shared.ts
@@ -4,4 +4,4 @@ export const menuGroupLabelClassName = 'px-3 pb-0.5 pt-1 text-text-tertiary syst
 export const menuSeparatorClassName = 'my-1 h-px bg-divider-subtle'
 export const menuPopupBaseClassName = 'max-h-[var(--available-height)] overflow-y-auto overflow-x-hidden rounded-xl border-[0.5px] border-components-panel-border bg-components-panel-bg-blur py-1 text-sm text-text-secondary shadow-lg outline-none focus:outline-none focus-visible:outline-none backdrop-blur-[5px]'
 export const menuPopupAnimationClassName = 'origin-[var(--transform-origin)] transition-[transform,scale,opacity] data-[ending-style]:scale-95 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none'
-export const menuBackdropClassName = 'fixed inset-0 z-50 bg-transparent transition-opacity duration-150 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none'
+export const menuBackdropClassName = 'fixed inset-0 z-[1002] bg-transparent transition-opacity duration-150 data-[ending-style]:opacity-0 data-[starting-style]:opacity-0 motion-reduce:transition-none'
diff --git a/web/app/components/base/ui/popover/index.tsx b/web/app/components/base/ui/popover/index.tsx
index 8c806cd9da..05222a2e4e 100644
--- a/web/app/components/base/ui/popover/index.tsx
+++ b/web/app/components/base/ui/popover/index.tsx
@@ -48,7 +48,7 @@ export function PopoverContent({
         align={align}
         sideOffset={sideOffset}
         alignOffset={alignOffset}
-        className={cn('z-50 outline-none', className)}
+        className={cn('z-[1002] outline-none', className)}
         {...positionerProps}
       >
         <BasePopover.Popup
diff --git a/web/app/components/base/ui/select/index.tsx b/web/app/components/base/ui/select/index.tsx
index c7e51e0939..04de5efaaf 100644
--- a/web/app/components/base/ui/select/index.tsx
+++ b/web/app/components/base/ui/select/index.tsx
@@ -115,7 +115,7 @@ export function SelectContent({
         sideOffset={sideOffset}
         alignOffset={alignOffset}
         alignItemWithTrigger={false}
-        className={cn('z-50 outline-none', className)}
+        className={cn('z-[1002] outline-none', className)}
         {...positionerProps}
       >
         <BaseSelect.Popup
diff --git a/web/app/components/base/ui/tooltip/index.tsx b/web/app/components/base/ui/tooltip/index.tsx
index 1a41cc0f56..84241bb3bb 100644
--- a/web/app/components/base/ui/tooltip/index.tsx
+++ b/web/app/components/base/ui/tooltip/index.tsx
@@ -37,7 +37,7 @@ export function TooltipContent({
         align={align}
         sideOffset={sideOffset}
         alignOffset={alignOffset}
-        className={cn('z-50 outline-none', className)}
+        className={cn('z-[1002] outline-none', className)}
       >
         <BaseTooltip.Popup
           className={cn(
diff --git a/web/app/components/workflow-app/components/workflow-onboarding-modal/index.tsx b/web/app/components/workflow-app/components/workflow-onboarding-modal/index.tsx
index 8db281bda0..072287dda6 100644
--- a/web/app/components/workflow-app/components/workflow-onboarding-modal/index.tsx
+++ b/web/app/components/workflow-app/components/workflow-onboarding-modal/index.tsx
@@ -45,8 +45,9 @@ const WorkflowOnboardingModal: FC<WorkflowOnboardingModalProps> = ({
         </div>
       </DialogContent>
 
+      {/* TODO: reduce z-[1002] to match base/ui primitives after legacy overlay migration completes */}
       <DialogPortal>
-        <div className="pointer-events-none fixed left-1/2 top-1/2 z-50 flex -translate-x-1/2 translate-y-[165px] items-center gap-1 text-text-quaternary body-xs-regular">
+        <div className="pointer-events-none fixed left-1/2 top-1/2 z-[1002] flex -translate-x-1/2 translate-y-[165px] items-center gap-1 text-text-quaternary body-xs-regular">
           <span>{t('onboarding.escTip.press', { ns: 'workflow' })}</span>
           <ShortcutsName keys={[t('onboarding.escTip.key', { ns: 'workflow' })]} textColor="secondary" />
           <span>{t('onboarding.escTip.toDismiss', { ns: 'workflow' })}</span>
diff --git a/web/docs/overlay-migration.md b/web/docs/overlay-migration.md
index 3c9da4f3fb..b3b1bd5738 100644
--- a/web/docs/overlay-migration.md
+++ b/web/docs/overlay-migration.md
@@ -53,6 +53,47 @@ pnpm -C web lint:fix --prune-suppressions <changed-files>
 - If a migrated file was in the allowlist, remove it from `web/eslint.constants.mjs` in the same PR.
 - Never increase allowlist scope to bypass new code.
 
+## z-index strategy
+
+All new overlay primitives in `base/ui/` share a single z-index value: **`z-[1002]`**.
+
+### Why z-[1002]?
+
+During the migration period, legacy and new overlays coexist. Legacy overlays
+portal to `document.body` with explicit z-index values:
+
+| Layer | z-index | Components |
+|-------|---------|------------|
+| Legacy Drawer | `z-[30]` | `base/drawer` |
+| Legacy Modal | `z-[60]` | `base/modal` (default) |
+| Legacy PortalToFollowElem callers | up to `z-[1001]` | various business components |
+| **New UI primitives** | **`z-[1002]`** | `base/ui/*` (Popover, Dialog, Tooltip, etc.) |
+| Legacy Modal (highPriority) | `z-[1100]` | `base/modal` (`highPriority={true}`) |
+| Toast | `z-[9999]` | `base/toast` |
+
+`z-[1002]` sits above all common legacy overlays, so new primitives always
+render on top without needing per-call-site z-index hacks. Among themselves,
+new primitives share the same z-index and rely on **DOM order** for stacking
+(later portal = on top).
+
+### Rules
+
+- **Do NOT add z-index overrides** (e.g. `className="z-[1003]"`) on new
+  `base/ui/*` components. If you find yourself needing one, the 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.
+- `portalToFollowElemContentClassName` with z-index values (e.g. `z-[1000]`)
+  should be deleted when the surrounding legacy container is migrated.
+
+### Post-migration cleanup
+
+Once all legacy overlays are removed:
+
+1. Reduce `z-[1002]` back to `z-50` across all `base/ui/` primitives.
+1. Reduce Toast from `z-[9999]` to `z-[99]`.
+1. Remove this section from the migration guide.
+
 ## React Refresh policy for base UI primitives
 
 - We keep primitive aliases (for example `DropdownMenu = Menu.Root`) in the same module.