Overlays

Dialog

A ready-made animated modal dialog for a short focused task or decision.

DialogDialogPropsDialogSize

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

'use client';

import { useState } from 'react';
import { Button, Dialog } from '@ai-created/ui';

export function Example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open dialog</Button>
      <Dialog
        open={open}
        onClose={() => setOpen(false)}
        title={"Rename project"}
      >
        <p>Dialog content belongs here.</p>
      </Dialog>
    </>
  );
}

Import

tsx

import { Dialog } from '@ai-created/ui';

Client boundary

Add 'use client' to the file that owns this interactive state.

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Backdrop

Required

Full-viewport overlay separating the dialog from page content.

Dialog panel

Required

Centered bounded content surface.

Header

Optional

Optional title, description, and close button.

Close action

Optional

44 × 44px labelled dismiss button.

button

Body

Required

Consumer task content.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Overlays/Dialog

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish size variants with open state, title, description, and nested body content.

Auto layout

Direction: vertical
Gap: 0px between framed regions
Padding: 16px viewport inset; 20px mobile / 24px desktop header inset; 12px header block padding; close target pinned 6px from the top and logical end
Alignment: Stretch
Wrap: Content wraps

Resizing

Width: fill
Height: hug
Minimum width: 280px
Maximum width: sm 384px; md 512px; lg 672px; xl 896px
Minimum height: Content controlled
Maximum height: Viewport minus 32px
Overflow: auto

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
OpenRequired	boolean	false	open	No additional constraint
Size	variant	md	size	sm, md, lg, xl
Title	text	None	title	No additional constraint
Description	text	None	description	No additional constraint
ContentRequired	slot	None	children	No additional constraint

Nested assets and slots

Backdrop

primitive / required

Full viewport modal overlay.

Internal fixed overlay

Panel

primitive / required

Focused dialog surface.

Headless UI DialogPanel

Header

subcomponent

Title, description, and close action.

Internal header

Body

slot / required

Focused task content.

children

Content limits

Title

One line preferred, maximum two lines

Overflow: Wrap; do not truncate.

Users need a concise task name.

Description

Maximum three lines

Overflow: Move long instructions into the body.

Header copy should orient, not explain the whole task.

Task scope

One focused task or decision

Overflow: Move complex multi-section work to a page.

Dialogs interrupt the underlying workflow.

Localization and RTL

Translatable: Title, Description, Body, Action labels

Close action stays at logical end.
Content follows locale direction.
Test twice-length titles.
Test at 200% zoom with keyboard-only dismissal.

Responsive behavior

Width is capped by size and inset 16px from the viewport.

No internal breakpoint

Panel shrinks to viewport width.
Body must remain reachable when content exceeds viewport height.

Authoring limits

Figma overlays cannot validate focus trapping, restoration, Escape, or scroll lock.
Always provide an accessible title through title or a correctly associated custom heading.

Accountable owner

Design systems overlay primitive owner

Canonical source: src/components/Dialog.tsx

Dismissal, focus, or size changes require overlay accessibility review.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Viewport padding

16px

Panel max width

384 / 512 / 672 / 896px

sm / md / lg / xl.

Radius

6px

Header padding

20px horizontal mobile / 24px md; 12px vertical

Body padding

24px horizontal / 20px vertical

Close target

44 × 44px

Close glyph

24 × 24px

Close glyph inset

16px from top and logical end

The target is positioned independently so it does not make a title-only header taller.

Rules

Keep the title visible and specific.
Use the shared overlay header and close-control pattern.
Hover strengthens the icon without drawing a border; keyboard focus retains the standard outline.
Use one scroll strategy; Dialog itself does not constrain body height.
Keep primary and dismissal actions inside the panel.

Responsive behavior

Panel width is fluid up to its size max-width and viewport padding.
Consider Modal for long or structurally rich content.

Token dependencies

--color-overlay

Backdrop.

--color-surface

Panel.

--color-border

Panel and header divider.

--color-text / --color-text2 / --color-text3

Title, description, and close icon.

--color-focus

Close focus outline.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

closed

Trigger: open is false.
Visual response: Backdrop and panel are absent after transition.
Behavior: Page remains interactive.

open

Trigger: open is true.
Visual response: Backdrop and centered panel are visible.
Behavior: Focus is trapped and background interaction is inert.

entering

Trigger: Opening transition.
Visual response: Backdrop fades; panel fades and scales from 95% over 200ms.
Behavior: Dialog becomes the active focus scope.

leaving

Trigger: Closing transition.
Visual response: Backdrop and panel fade; panel scales to 95% over 150ms.
Behavior: Focus returns after dismissal.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Headless UI dialog with optional DialogTitle and Description associations.
Accessible name: title supplies the accessible name when provided; otherwise body content must provide an accessible label.

Prefer always providing a title.
Provide at least one obvious dismissal method.
Do not put another modal dialog inside Dialog.
Restore focus to a meaningful trigger through the managed open state.

Keyboard behavior

Escape: Requests close through onClose.
Tab / Shift+Tab: Cycles focus within the open dialog.
Enter / Space: Activates the focused dialog control.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { Dialog } from '@ai-created/ui';

Client Component required

Headless UI manages focus trap, Escape, outside dismissal, inert background, and restoration.
Dialog stays in the tree while Transition controls visibility.
className applies to the panel.

tsx

<Dialog open={open} onClose={() => setOpen(false)} title="Rename project">...</Dialog>

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
open	boolean	required	Whether the dialog is shown.
onClose	() => void	required	Called on dismissal.
title	string	undefined	Optional accessible title.
description	string	undefined	Optional description.
size	DialogSize	md	sm, md, lg, or xl.
children	ReactNode	required	Dialog content.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use for one short task with a clear completion path.
Write titles that describe the task, not generic “Dialog”.

Do not

Do not use for persistent workspace content.
Do not put large multi-step flows into the panel.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Maps sizes and optional header content.
Calls onClose from close button and managed dismissal.

Interaction

Opening focus, focus trap, Escape, close button, backdrop, and restoration work.

Accessibility

Dialog has a name/description and background is inert while open.

Visual

Capture all sizes, header combinations, entering/open states, long content, and themes.

Related specifications

modal confirm-dialog button