Overlays

Overlays cover anchored popovers, menu panels, transient labels, modal dialogs, edge sheets, and blocking confirmations. Popover, HoverCard, DropdownMenu, and ContextMenu share one floating surface: bg-popover fill, a DPR-aware overlay-hairline edge, --vueda-control-radius corners, and --vueda-shadow-popover elevation. Dialog and AlertDialog use the modal radius plus overlay-hairline-elevated; Sheet uses directional border-*-hairline edges with the same overlay elevation. Tooltip deliberately inverts the surface (bg-foreground / text-background) so it reads as a transient label rather than an actionable panel.

This page is the visual contract for Popover, HoverCard, Dialog, Sheet, AlertDialog, DropdownMenu, ContextMenu, and Tooltip. Menubar and NavigationMenu also open overlay surfaces, but their triggers are navigation primitives, so their visual coverage lives on Navigation. The Combobox and Select list panels use the same floating surface; their triggers and open states are documented on Selection + Command.

For how to change any of this, see Customize VUEDA Appearance. Values belong in CSS tokens; compositions belong in theme keys.

Popover

Popover is the anchored action panel. Width and padding are caller-supplied, not part of the theme key: the theme key governs only the surface (background, border, radius, shadow) and internal typography rhythm. Typical sizes are w-72 p-4 for forms, w-60 p-3 for compact info panels, and w-80 p-4 for wide destructive-action confirmations.

Theme key: PopoverContent. Token surface: Color palette: light tokens.css-token:popover, Color palette: light tokens.css-token:popover-foreground, Color palette: light tokens.css-token:border, Semantic radius tokens.css-token:vueda-control-radius, Semantic shadow tokens.css-token:vueda-shadow-popover.

HoverCard

HoverCard is a glance-weight summary popover, lighter than Popover. The content panel is w-64 (256 px) with Semantic radius tokens.css-token:vueda-control-radius, deliberately tighter than the actionable Popover surface. Use it for read-only summaries: a profile by hovering a username, or a record summary by hovering an ID.

Theme key: HoverCardContent. Token surface: Color palette: light tokens.css-token:popover, Color palette: light tokens.css-token:popover-foreground, Color palette: light tokens.css-token:border, Semantic radius tokens.css-token:vueda-control-radius, and Semantic shadow tokens.css-token:vueda-shadow-popover.

DropdownMenu

DropdownMenu and ContextMenu share the same panel and item components — a design change to one must be mirrored in the other. The highlight recipe is bg-accent text-accent-foreground. Destructive items tint only the foreground at rest; on focus they add bg-destructive/10. Menu icons sit at --muted-foreground at rest and inherit --accent-foreground on highlight so the row reads as a unit.

Theme keys: DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator. Token surface: Color palette: light tokens.css-token:popover, Color palette: light tokens.css-token:popover-foreground, Color palette: light tokens.css-token:accent, Color palette: light tokens.css-token:destructive.

ContextMenu

ContextMenu uses the same panel and item primitives as DropdownMenu; the only difference is the trigger (right-click on a region rather than a button click). Any theme change to ContextMenuContent or ContextMenuItem must be mirrored in the DropdownMenu keys to keep both surfaces visually identical.

Dialog

Dialog is the centered modal surface for focused work that needs a blocking context but is not inherently destructive. Standard content uses the modal radius with overlay-hairline overlay-hairline-elevated; the scroll content variant preserves the same surface while letting the overlay own vertical scroll.

Theme keys: DialogContent, DialogScrollContent, DialogHeader, DialogTitle, DialogDescription, and DialogFooter. Token surface: Color palette: light tokens.css-token:background, Color palette: light tokens.css-token:foreground, Color palette: light tokens.css-token:overlay, Semantic radius tokens.css-token:vueda-modal-radius, and Semantic shadow tokens.css-token:vueda-shadow-overlay.

Sheet

Sheet is the edge-attached modal surface for focused side work. The surface is owned by SheetContent; the side prop selects the matching slide motion, edge side, and directional hairline: left sheets paint a right edge, right sheets paint a left edge, top sheets paint a bottom edge, and bottom sheets paint a top edge.

Theme keys: SheetContent, SheetHeader, SheetTitle, SheetDescription, and SheetFooter. Token surface: Color palette: light tokens.css-token:background, Color palette: light tokens.css-token:foreground, Color palette: light tokens.css-token:border, Color palette: light tokens.css-token:overlay, and Semantic shadow tokens.css-token:vueda-shadow-overlay.

AlertDialog

AlertDialog is the blocking confirmation surface for consequential choices. It uses the same centered modal geometry as Dialog, but the title, description, and actions are optimized for confirmation flows where escape, cancel, and the primary action must stay visually clear.

Theme keys: AlertDialogContent, AlertDialogHeader, AlertDialogTitle, AlertDialogDescription, AlertDialogFooter, AlertDialogCancel, and AlertDialogAction.

Tooltip

Tooltip inverts the shared overlay surface: bg-foreground / text-background with the same --vueda-control-radius and an arrow sitting behind the panel edge. The inversion is a canonical choice: in dense operator screens, the contrast flip is what makes a tooltip register at a glance as a passing label rather than a panel.

Theme key: TooltipContent. Token surface: Color palette: light tokens.css-token:foreground, Color palette: light tokens.css-token:background, Semantic radius tokens.css-token:vueda-control-radius.

Customization Surface

The shared floating surface (--popover, --popover-foreground, --border, --vueda-shadow-popover) is the single dial that shifts Popover, HoverCard, DropdownMenu, ContextMenu, Menubar content, NavigationMenu viewports, Select lists, Combobox lists, and normal Sonner toasts together. Dialog, AlertDialog, and Sheet use --background, --foreground, --overlay, and --vueda-shadow-overlay instead. Tooltip's inverted surface uses --foreground and --background directly and does not reference --popover, so a popover re-tone does not affect tooltips.

The highest-value theme keys for structural customization are:

• PopoverContent: root (surface, padding defaults).
• HoverCardContent: root (summary popover surface).
• DialogContent and DialogScrollContent: root (modal surface), overlay on scroll content.
• SheetContent: root (edge-attached surface and side-specific hairline).
• AlertDialogContent: root and overlay (blocking confirmation surface).
• DropdownMenuContent and ContextMenuContent: root (surface), each must remain visually identical.
• DropdownMenuItem and ContextMenuItem: root (base), highlighted (hover/focus recipe), destructive (color-only variant at rest).
• TooltipContent: root (inverted surface, arrow, radius).