# Overlay

The one mount above z-float: modal (460/640px) or bare. Focus trap, Esc, scroll lock, stage shadow, scale-in. Overlays never stack two deep.

Install: `npx candlelight-ds add overlay`

Category: primitive · Grammar: G1

## Use when

The user must address something before continuing on this surface — a blocking decision.

## Don't use when

Editing an object adjacent to a list (Sheet) or a whole workflow (a route). Modal is the last resort, not the first thought.

## States

- closed
- open sm (460px)
- open lg (640px)
- bare
- locked (typed-confirm)

## Keyboard

- `Esc` — closes (unless locked)
- `Tab` — cycles inside the trap

## Acceptance tests

- Overlays never stack two deep — a modal needing a picker uses an inline combobox.
- Scrim is stage/80 with 2px blur; the panel wears shadow-stage.

## Files

- components/ui/Overlay.tsx

npm dependencies: @candlelight-ds/tokens, @radix-ui/react-dialog, lucide-react, clsx, tailwind-merge

Rendered twin: https://candlelight-docs.vercel.app/components/overlay · Full spec: https://candlelight-docs.vercel.app/spec.md