overlay — wyrd.component.dialog

Dialog

Overlay surface with canonical open state, dismissal policy, focus management, and reduced-motion behavior.

Install @wyrd-company/react or the Flutter package and use it directly — your DESIGN.md does the styling.

catalog/contracts/dialog.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: Dialog  tag: wyrd-dialog  package: wyrd.component.dialog  title: Dialog  summary: Overlay surface with canonical open state, dismissal policy, focus management, and reduced-motion behavior.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: overlay  composition: overlay  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: is-open      type:        kind: boolean      required: false      default: false      controlled: true      reflects: true      serializable: true      summary: Controlled open state.    - name: default-open      type:        kind: boolean      required: false      default: false      serializable: true      summary: Initial uncontrolled open state.    - name: is-modal      type:        kind: boolean      required: false      default: true      reflects: true      serializable: true      summary: Makes background content inert while the dialog is open.    - name: dismissible      type:        kind: boolean      required: false      default: true      reflects: true      serializable: true      summary: Allows Escape, backdrop (dialog variant only), and platform back navigation to request dismissal.    - name: variant      type:        kind: enum        values:          - dialog          - alertdialog      required: false      default: dialog      reflects: true      serializable: true      summary: Selects ordinary dialog semantics or urgent alertdialog semantics.  slots:    - name: title      required: true      cardinality: exactly-one      accepts:        - text        - node      summary: Dialog title and accessible-name source.    - name: body      content: true      required: true      cardinality: one-or-many      accepts:        - content        - node      summary: Dialog body content.    - name: actions      required: false      cardinality: zero-or-many      accepts:        - action        - component      summary: Dialog action area.  events:    - name: open-change      payload:        is-open:          kind: boolean        reason:          kind: enum          values:            - trigger            - escape            - backdrop            - platform-back            - action            - programmatic      bubbles: true      composed: true      cancelable: false      summary: Canonical open-state change event.    - name: dismiss      payload:        reason:          kind: enum          values:            - escape            - backdrop            - platform-back            - action      bubbles: true      composed: true      cancelable: true      summary: Dismissal request emitted before a dismissible dialog closes.  states:    - name: closed      source: behavior-runtime      summary: Dialog is absent from the active overlay surface.    - name: opening      source: behavior-runtime      summary: Dialog is entering and focus is moving into the surface.    - name: open      source: behavior-runtime      summary: Dialog is visible and owns modal focus semantics.    - name: dismissing      source: behavior-runtime      summary: Dialog is exiting and focus is restoring.  parts:    - name: backdrop      summary: Modal backdrop.    - name: surface      summary: Dialog surface container.      slots:        - title        - body        - actions    - name: title      summary: Title region.      slots:        - title    - name: body      summary: Body region.      slots:        - body    - name: actions      summary: Action region.      slots:        - actions  tokens:    panel:      background: color.surface-container      foreground: color.on-surface      border-color: color.outline    scrim:      color: color.on-background      opacity: opacity.muted    border-width: 1px    radius: rounded.lg    padding-x: spacing.lg    padding-y: spacing.lg    gap: spacing.mdmessages: []obligations:  accessibility:    role: Dialog variant uses dialog; alertdialog variant uses alertdialog.    name: Title slot provides the accessible name.    description: Alertdialog requires the body content to provide its accessible description; ordinary dialog body content may provide the description when declared by the target projection.    keyboard:      - Escape requests dismissal when dismissible is true.      - Tab and Shift+Tab cycle inside a modal dialog.    semantics:      - Modal dialog makes background content inert on web targets.      - Focus moves into the dialog on open and restores to trigger or return target on close.      - Alertdialog wires its accessible description to the body content.  behavior:    model: behavior-runtime    runtimeBlueprint: behavior/dialog-open-close    interactions:      - Escape, platform back, and action dismissal request close when dismissible is true.      - Backdrop dismissal requests close only when dismissible is true and variant is dialog.      - Reduced motion collapses transform tracks while preserving state transitions and completion events.    hostEffects:      - Apply inert background.      - Trap focus while modal.      - Restore focus after close.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - text-expansion    - safe-area  sdui:    status: partial    serializableProperties:      - is-open      - default-open      - is-modal      - dismissible      - variant    serializableSlots:      - title      - body      - actions    eventBindings:      - open-change      - dismiss    notes: Open-state data is serializable; overlay host coordination, focus trap, inert background, and platform back behavior require host effects.examples:  - name: usage    state: closed    properties:      is-open: false      is-modal: true    slots:      title: Confirm changes      body: Review the changes before continuing.      actions: Cancel | Continue  - name: closed    state: closed    properties:      is-open: false    slots:      title: Confirm changes      body: Review the changes before continuing.  - name: open    state: open    properties:      default-open: true      is-modal: true    slots:      title: Confirm changes      body: Review the changes before continuing.      actions: Cancel | Continue  - name: alertdialog    state: open    properties:      default-open: true      is-modal: true      variant: alertdialog    slots:      title: Delete project?      body: This action permanently deletes the project and cannot be undone.      actions: Cancel | Delete

Examples

Generated from the contract's examples block. Previews are the published @wyrd-company/react component, themed by the brand's role tokens — flip the site's light/dark toggle and they follow.

Code target React Flutter Applies to every example on component pages.

usage state: closed

Closed by contract

Usage

import { useState } from "react";
import { WyrdButton, WyrdDialog } from "@wyrd-company/react";

export function DialogInteractionExample() {
  const [open, setOpen] = useState(false);
  const close = () => setOpen(false);
  return <>
    <WyrdButton onPress={() => setOpen(true)}>Review changes</WyrdButton>
    <WyrdDialog isOpen={open} isModal title="Confirm changes" onOpenChange={(event) => !event.isOpen && close()}
      actions={<><WyrdButton variant="ghost" onPress={close}>Cancel</WyrdButton><WyrdButton onPress={close}>Continue</WyrdButton></>}>
      Review the changes before continuing.
    </WyrdDialog>
  </>;
}

import 'package:flutter/widgets.dart';
import 'package:wyrd_flutter/wyrd_flutter.dart';

class DialogInteractionExample extends StatefulWidget {
  const DialogInteractionExample({super.key});
  @override State<DialogInteractionExample> createState() => _DialogInteractionExampleState();
}
class _DialogInteractionExampleState extends State<DialogInteractionExample> {
  bool open = false;
  @override Widget build(BuildContext context) => Stack(children: [
    WyrdButton(onPressed: (_) => setState(() => open = true), child: const Text('Review changes')),
    WyrdDialog(isOpen: open, title: const Text('Confirm changes'), child: const [Text('Review the changes before continuing.')],
      actions: [WyrdButton(variant: WyrdButtonVariant.ghost, onPressed: (_) => setState(() => open = false), child: const Text('Cancel')), WyrdButton(onPressed: (_) => setState(() => open = false), child: const Text('Continue'))],
      onOpenChanged: (event) { if (!event.isOpen) setState(() => open = false); }),
  ]);
}

closed state: closed

Closed by contract

Usage

import { WyrdDialog } from "@wyrd-company/react";

<WyrdDialog isOpen={false} title="Confirm changes">
  Review the changes before continuing.
</WyrdDialog>

// events: onOpenChange, onDismiss

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdDialog(
  isOpen: false,
  title: Text('Confirm changes'),
  child: Text('Review the changes before continuing.'),
)

// events: onOpenChanged, onDismiss

open state: open

Usage

import { WyrdDialog } from "@wyrd-company/react";

<WyrdDialog defaultOpen isModal title="Confirm changes" actions="Cancel | Continue">
  Review the changes before continuing.
</WyrdDialog>

// events: onOpenChange, onDismiss

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdDialog(
  defaultOpen: true,
  isModal: true,
  title: Text('Confirm changes'),
  child: Text('Review the changes before continuing.'),
  actions: Text('Cancel | Continue'),
)

// events: onOpenChanged, onDismiss

alertdialog state: open

Usage

import { WyrdDialog } from "@wyrd-company/react";

<WyrdDialog defaultOpen isModal variant="alertdialog" title="Delete project?" actions="Cancel | Delete">
  This action permanently deletes the project and cannot be undone.
</WyrdDialog>

// events: onOpenChange, onDismiss

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdDialog(
  defaultOpen: true,
  isModal: true,
  variant: 'alertdialog',
  title: Text('Delete project?'),
  child: Text('This action permanently deletes the project and cannot be undone.'),
  actions: Text('Cancel | Delete'),
)

// events: onOpenChanged, onDismiss

Host contract fixture explicit native top layer

Anatomy

The specimen is the same published React component and contract example used above. Indexed markers identify only regions the contract can ground; the typed ledger keeps parts, slots, states, and semantic token bindings distinct.

ANATOMY · LIVE SPECIMEN Dialog open example · contract-derived

Part surface Dialog surface container.
The visible overlay surface.
Part title Title region.
The visible title region.
Slot body Dialog body content.
The example's body content region.
Slot actions Dialog action area.
The example's action region.
Token panel.background color.surface-container
The semantic panel background token applied to the surface.

Parts

backdropModal backdrop.
surfaceDialog surface container.
titleTitle region.
bodyBody region.
actionsAction region.

Slots

titleRequired · exactly-one
bodyRequired · one-or-many
actionsOptional · zero-or-many

States

closedDialog is absent from the active overlay surface.
openingDialog is entering and focus is moving into the surface.
openDialog is visible and owns modal focus semantics.
dismissingDialog is exiting and focus is restoring.

Tokens

panel.backgroundcolor.surface-container
panel.foregroundcolor.on-surface
panel.border-colorcolor.outline
scrim.colorcolor.on-background
scrim.opacityopacity.muted
border-width1px
radiusrounded.lg
padding-xspacing.lg
padding-yspacing.lg
gapspacing.md

FIG. 1 parts: backdrop · surface · title · body · actions TOL. ±0

Properties

Name	Type	Default	Summary
`is-open`	`boolean`	`false`	Controlled open state.
`default-open`	`boolean`	`false`	Initial uncontrolled open state.
`is-modal`	`boolean`	`true`	Makes background content inert while the dialog is open.
`dismissible`	`boolean`	`true`	Allows Escape, backdrop (dialog variant only), and platform back navigation to request dismissal.
`variant`	`dialog \| alertdialog`	`dialog`	Selects ordinary dialog semantics or urgent alertdialog semantics.

Slots & events

Slot	Cardinality	Accepts	Summary
`title`	exactly-one	`text, node`	Dialog title and accessible-name source.
`body`	one-or-many	`content, node`	Dialog body content.
`actions`	zero-or-many	`action, component`	Dialog action area.

Event	Payload	Summary
`open-change`	`is-open, reason`	Canonical open-state change event.
`dismiss`	`reason`	Dismissal request emitted before a dismissible dialog closes.

Tokens

The contract's token bindings. Open the shared contextual sidebar from any example; primary swatches reflect the color you pick there. Error swatches show the active preset's values; editing any knob switches to custom and resets error to TWW · Ink.

Binding	Token
`panel.background`	`color.surface-container`
`panel.foreground`	`color.on-surface`
`panel.border-color`	`color.outline`
`scrim.color`	`color.on-background`
`scrim.opacity`	`opacity.muted`
`border-width`	`1px`
`radius`	`rounded.lg`
`padding-x`	`spacing.lg`
`padding-y`	`spacing.lg`
`gap`	`spacing.md`

States

State	Source	Summary
`closed`	behavior-runtime	Dialog is absent from the active overlay surface.
`opening`	behavior-runtime	Dialog is entering and focus is moving into the surface.
`open`	behavior-runtime	Dialog is visible and owns modal focus semantics.
`dismissing`	behavior-runtime	Dialog is exiting and focus is restoring.

SDUI

Status: partial. Open-state data is serializable; overlay host coordination, focus trap, inert background, and platform back behavior require host effects.

Serializable	Members
Properties	`is-open, default-open, is-modal, dismissible, variant`
Slots	`title, body, actions`
Events	`open-change, dismiss`

  The Wyrding Way — a contract-first design system. © Wyrd Company 
   Pipeline demo
 Choose an example to inspect its pipeline context.
 Explore the shape of a brand's pipeline input: presets and knobs regenerate the illustrative excerpt below — not a compilable DESIGN.md (see the format reference). Primary swatches update live; accent, shape, density, and ground are excerpt-only; error swatches are preset-derived until any edit switches to custom (TWW · Ink errors). Component previews use the published brand package and the site's light/dark toggle.
 
  Start from
       
 * homages — shown for range, not affiliation.
 
  Tokens
 Primary updates live swatches. Accent, shape, density, and ground appear in the excerpt only. Error swatches follow the preset until you edit a knob — then they reset to TWW · Ink.
  color.primary   #26221A    color.accent   #9C7C14    rounded.md   2px    density   1.0×    ground     
 
   DESIGN.md excerpt illustrative

Examples

Anatomy

Parts

Slots

States

Tokens

Properties

Slots & events

Tokens

States

Accessibility

SDUI