import { Dialog } from "@elabs-ai/components-ui";npm install @elabs-ai/components-tokens @elabs-ai/components-uiPaste it into Claude Code, Cursor, Codex or any other coding agent. Text in [brackets] is yours to fill in.
Add the brand-ui Dialog component (from @elabs-ai/components-ui) to this project. 1. Read https://elabs-ai.com/llms.txt first: it maps every package and the rules. If you can use MCP servers, connect https://elabs-ai.com/mcp and use its search, docs and tokens tools. If not, run the same lookups in the terminal: `npx -y @elabs-ai/components-cli search "<what you need>"` and `npx -y @elabs-ai/components-cli docs <Component>`. 2. Look Dialog up before writing code: `npx -y @elabs-ai/components-cli docs Dialog` prints its real props, variants, what it pairs with and what to avoid. 3. If @elabs-ai/components-ui is not installed yet: `pnpm add @elabs-ai/components-tokens @elabs-ai/components-ui` (or `npm install @elabs-ai/components-tokens @elabs-ai/components-ui`). If this is the first brand-ui package in the project, wire it once: import `@elabs-ai/components-tokens/styles.css` plus the `themes/light.css` and `themes/dark.css` stylesheets in the CSS entry, add one Tailwind `@source` line per installed @elabs-ai package (Tailwind does not scan node_modules, so without it everything renders unstyled), and wrap the app root in `ThemeProvider` from `@elabs-ai/components-tokens`. 4. Use it here: [the screen or file, and what it should show] 5. Rules: use only @elabs-ai/components-* components and the semantic tokens — no raw colours, no raw font sizes, no arbitrary Tailwind values. Look up each component's real props with the docs tool before you use it; never guess a prop. 6. Done means: the typecheck passes, `npx -y @elabs-ai/components-cli audit src --strict` reports nothing, and you have opened the app and looked at every screen you touched in the light and the dark theme.
Avoid
- Dialog without a DialogTitle — screen readers announce no name (use sr-only if visually hidden).
- Nesting a Dialog inside a Dialog — use a single flow or a Sheet/Drawer for the secondary surface.
- Confirming a destructive action in a plain Dialog — use AlertDialog (it traps focus on the safe action).
Works with
Examples
Long unbreakable text keeps the dialog width
Overflow guard (regression): a `max-w-md` dialog holding a long, unbreakable path inside a `truncate` row. The `minmax(0,1fr)` grid column lets the row shrink and truncate, so the dialog must stay at `max-w-md` and never scroll horizontally. Before the fix the implicit `auto` column blew past `max-w-md`.
Hidden First Control
Opening focus, when the body's first selector match cannot actually take it. A `hidden` file input matches `input:not([disabled])` but swallows `.focus()`, so a redirect that trusted the selector would suppress Radix's own autofocus and leave the keyboard on the TRIGGER — outside the modal. jsdom cannot show this (it does no layout and focuses hidden inputs happily), so the lock lives here, in a real browser.
Focus Ring Clearance
Regression lock for #425 — `DialogBody` clipping a flush child's outward focus ring. The body is a scroll container with no padding of its own, so its padding box IS its content box; a full-width child's border box then coincides with the scrollport edge, leaving no room for a `box-shadow` ring (ink overflow — never part of the scrollable region, so it is simply cut). `input` is the FIRST child with no label above it — the top/left/right worst case (identical to the true sole-child case for those three edges, since clipping is a property of the scrollport, not of what else shares the column). `button` below it exercises the library's widest outward paint (`ring-2 ring-offset-2` = 4px). The filler forces a real scrollbar, and scrolling to the very end before focusing `lastButton` exercises the BOTTOM edge at the opposite extreme of the scroll range. The `3.5` threshold: `comfortable` density yields exactly 4px of gutter (`p-1` = `calc(var(--spacing) * 1)`, `--spacing: 0.25rem`); `compact` density yields 3.55px (`--spacing: 0.222rem`, `density.css:97`) — a known, accepted sub-pixel shortfall on the outermost edge of a 2px stroke. The library's widest outward focus paint is `ring-2 ring-offset-2` = 4px, so 3.5 clears both densities with margin while still failing hard against the unfixed 0px baseline. Verified CO-RESIDENT with `DirtyGuard` below, on purpose: a prior attempt to isolate this story in its own file (on a since-refuted suspicion that it destabilized `DirtyGuard`) did not hold up under a clean re-test — 4/4 consecutive runs green, `DirtyGuard` included. See `.claude/rules/component-api.md` ("Regression locks with observable side effects must be verified co-resident"), which this story now satisfies.
Wide With Sections
The fixed-header/footer proof. Opens a deliberately long form, scrolls the `DialogBody` to the bottom and asserts that the header and footer have not moved — the primary action stays reachable without scrolling it out of view. It also compares the RENDERED font sizes of the three type rungs, so a section heading can never silently collapse onto the field-label rung.
Short Viewport
The same dialog at a phone-height viewport, simulated deterministically by capping the content box — the runner's window size then cannot flatter the result. Header and footer must still hold their ground.
Form Recipe
A short form: no internal scroll, and Enter submits because the body is a real `<form>`.
Workbench Shell
`size="full"` with the body owning a split pane — the editor + result shape.
Unsaved changes confirm before closing
Escape with unsaved changes raises a discard confirmation; a programmatic close after a successful save does not. The dirty guard is a hook, not a prop, because the component must not own app state (D5).
API
DialogBody
DialogContent
DialogDescription
DialogOverlay
DialogSection
| Prop | Type | Description |
|---|---|---|
titlerequired | ReactNode | The section heading. States what the group of fields is for. |
description | ReactNode | One line of supporting context under the heading. |
level | 3 | 4 | Semantic heading level. `DialogTitle` renders an `<h2>`, so a section is an `<h3>` by default and an `<h4>` when nested a rung deeper. |
actions | ReactNode | Section-scoped actions, aligned to the inline end of the heading row. |
DialogTitle
Theming
The tokens each state resolves to. Change the token and every theme follows.
| State | Token |
|---|---|
| overlay | DialogOverlay: bg-overlay + backdrop-blur-overlay (a semantic token — never a raw black) |
| surface | DialogContent: bg-card text-card-foreground + shadow-ring-lg (ADR 0020 — a floating surface bakes its hairline into the shadow; it carries NO border) |
| focus | focus-ring — the compound indicator: a ring-2 in --ring plus a 1px --ring-contour outline (#67), on the close button |