Contents Purpose Anatomy Variants States Tokens Used Accessibility Behavior Platform Notes Component: modal Purpose Focus attention on a task or message by overlaying the page. Anatomy modal — backdrop overlay modal-dialog — the dialog container modal-header — optional, title + close button modal-body — required, content modal-footer — optional, action buttons Variants Class Visual Usage modal Backdrop + centered dialog Standard dialog modal-narrow Max-width ~400px on modal-dialog Confirmations, simple forms modal-wide Max-width ~640px on modal-dialog Complex forms, detail views Default modal-dialog max-width: 480px. States Closed (default): display: none on .modal Open (is-active): display: flex, backdrop + dialog visible Entrance: opacity + translateY fade-in, --duration-slow Tokens Used --space-4, --space-6 --color-neutral-950 (at 40% opacity, backdrop) --color-surface-primary --color-border-default --shadow-float --z-overlay --duration-slow --breakpoint-narrow Accessibility Use <dialog> or role="dialog" with aria-modal="true" aria-labelledby pointing to the modal title Focus trap: first focusable element receives focus on open (JS responsibility) Escape key dismisses the modal (JS responsibility) Return focus to triggering element on close (JS responsibility) Behavior Backdrop: --color-neutral-950 at 40% opacity, z-index: var(--z-overlay) Dialog: surface-primary bg (new page-level context, not nested surface), border-default border, --shadow-float Click backdrop or press Escape to dismiss (JS responsibility, CSS provides visual container) Focus trap is JS responsibility modal-header has a close button (.modal-close, styled like btn-ghost) Below --breakpoint-narrow (640px): dialog goes full-width with space-4 margin Platform Notes Web: CSS in @layer components. One file: modal.css. JS handles open/close, focus trap, escape key. macOS: Map to NSPanel or SwiftUI .sheet modifier.