# Dialog

> Stops the work to ask one question or collect a small form. Use rarely.

Source: https://kwark.space/designSystem/components/dialog

## Usage

### What it is
A window over the work for one decision or one short form. Kwark has one dialog component (`Modal`) with two looks.

| Look | Where | Head |
|---|---|---|
| Default | *Project settings*, *Sign in*, *New project* | 28px 32px padding, a 40px icon tile, the title in Poppins 700–900 at 20px, a 44px close |
| Story (`appearance="story"`) | Characters, Research, the production office (*Change a date*), *Copy for AI* | 24px 26px 20px padding, Raleway 400 title, a 12px description, a 30px close, ground `--k-bg` |

New dialogs use the story look; the default look is being moved over (its upper-case confirm variant especially). On a phone, small and medium dialogs become bottom sheets and large ones go full screen (`Modal` does this from `useBreakpoint`).

### When to use
- A decision with consequences for other people: *Issue call sheet?*
- A short form that creates or changes one thing: *Change a date*.

### When not to use
- To confirm something undoable. Do it, then offer **Undo** in a [Toast](https://kwark.space/designSystem/components/toast.md).
- To show information. Put it on the page.

### Writing
The title says what the dialog is for (*Change a date*, *Project settings*) or asks the question (*Move to trash?*). The primary repeats its verb. A destructive action in a form sits at the far left, apart from Save.

## Style

### Anatomy

1. **Backdrop**: `color-mix(--k-bg 82%, transparent)`, flat (the app adds a 6px blur on story dialogs; the system does not).
2. **Panel**: 512px (`max-w-lg`) for medium, 14px corners, 1px `--k-line`, at most 90vh, scrolling in the body only.
3. **Head**: see the table; 1px `--k-line` under it.
4. **Body**: 32px (26px story) padding, 14px text in `--k-text-2`.
5. **Actions**: 24px 32px (18px 26px story), 1px line above, right-aligned, 12px apart, primary last.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-bg` | #f8fafc | #191919 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-radius-sheet` | 14px |  |
| `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) |
| `--k-fs-head` | 20px |  |
| `--k-fs-display` | 28px |  |
| `--k-font-display` | 'Raleway', 'Poppins', system-ui, sans-serif |  |

## Code

### React

In the Kwark app: `import Modal from '@/components/ui/Modal'`.

```tsx
<Modal isOpen={open} onClose={close} title="Issue call sheet?"
  footer={<><Button variant="ghost" onClick={close}>Cancel</Button><Button onClick={issue}>Issue call sheet</Button></>}>
  Review the crew list before issuing revision 3.
</Modal>
```

| Prop | Type | Notes |
|---|---|---|
| `isOpen` | `boolean` |  |
| `onClose` | `() => void` | Escape and backdrop call it |
| `title` | `string` |  |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` |  |
| `priority` | `'base' \| 'high' \| 'critical'` | z-index layer |
| `footer` | `ReactNode` |  |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div data-modal-example>
<button class="kw-button" type="button" data-open-example>Open Project settings</button>
<dialog class="kw-dialog" aria-labelledby="settings-title">
  <div class="kw-dialog__head"><span class="kw-dialog__icon" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 13c0 5-3.5 7.5-7.7 9a1 1 0 0 1-.7 0C7.5 20.5 4 18 4 13V6a1 1 0 0 1 1-1c2 0 4.5-1.2 6.2-2.7a1.2 1.2 0 0 1 1.5 0C14.5 3.8 17 5 19 5a1 1 0 0 1 1 1z"/><path d="m9 12 2 2 4-4"/></svg></span><div><h2 id="settings-title">Project settings</h2></div><form method="dialog"><button class="kw-dialog__close" type="submit" value="cancel" aria-label="Close dialog"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></form></div>
  <div class="kw-dialog__body"><p>You, and the people you share it with. Sharing is in the project menu.</p></div>
  <form method="dialog" class="kw-dialog__actions"><button type="submit" class="kw-button kw-button--quiet" value="cancel">Cancel</button><button type="submit" class="kw-button kw-button--primary" value="preview">Save changes</button></form>
</dialog>
<p class="kw-hint" data-example-result role="status"></p>
</div>
<div class="kw-dialog kw-dialog--story" style="box-shadow:none;width:min(480px,100%)">
  <div class="kw-dialog__head"><div><h2>Change a date</h2><p class="kw-dialog__desc">Costume fitting, Meera · Day 3 of prep</p></div><button class="kw-dialog__close" type="button" aria-label="Close dialog"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
  <div class="kw-dialog__actions"><button class="kw-button kw-button--story" type="button" style="margin-right:auto"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 6h18M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2"/></svg> Delete</button><button class="kw-button kw-button--story" type="button">Cancel</button><button class="kw-button kw-button--story kw-button--primary" type="button">Save</button></div>
</div>
```

## Accessibility

- Use `<dialog>` with `showModal()` or the shared `Modal`: focus moves in, is trapped, and returns to the trigger.
- `aria-labelledby` points at the title.
- Escape closes unless closing would lose typed work; then ask.

## For agents

### Rules

- **Never** use a dialog to confirm an action that can be undone; offer Undo instead.
- **Must** title the dialog with the question and label the primary with the same verb.
- **Must** return focus to the trigger on close.

### AI readiness test

**Task:** Confirm deleting a project that two other people have access to.

**Give the agent:** Dialog, Destructive actions pattern, Sharing and roles.

**Constraint:** Deleting a project cannot be undone after 30 days.

**A reliable answer:**
- Title names the project
- Body says who loses access and that it stays in Trash for 30 days
- Danger button "Delete project"
- Cancel is quiet
