- Job
- Modal task
- Requirement
- must specify if any overlay
- States / rules
- role, trap, Escape, restore
- Specified means
- Operable
- Hardest context
- Tab cycle
Nav overlay
z-50 div
Baseline vs product decision
Building Blocks baseline supplies
- Accessible dialog semantics and naming.
- Focus entry, containment, Escape, and return focus.
- Overlay/stacking relationship.
- Responsive fallback when the same modal shape is not appropriate at sm.
The consuming product still decides
- Why a modal interruption is justified.
- Content, action hierarchy, and consequence language.
- Whether a sheet/full-screen treatment is better in specific contexts.
- Product-local Catalog status and implemented variants.
Anatomy
This is documentation anatomy, not a public API shape.
The user can identify what opened the dialog.
The bounded modal context with an accessible name.
Explains the task or consequence without relying on background context.
Provide explicit completion and cancellation paths.
Initial focus, Tab containment while open, Escape behavior, and return focus are intentional.
Preview
Preview — not a published component API.
This will update the live version.
Usage
Job: Modal task.
Operable
When not to use
Do not use a modal for information that can remain in the page flow. Do not trap people without Escape/close/return-focus behavior.
Variants
The checklist row does not authorize this page to invent a final component API. Where the source rule names a variant, preserve it; otherwise keep the implemented variant set minimal and job-driven.
States & behavior
role, trap, Escape, restore
Default, Hover, Focus, Active/Pressed, and Disabled apply to interactive controls. Error, Loading, Empty, and Success apply where the component takes or reports data.
Hardest-context test
Building Blocks baseline recommendation: Exercise keyboard-only open → interact → cancel/complete → return focus, including long content and 375px layouts.
Accessibility
- Use native semantics whenever they match the job.
- Keep keyboard focus visible and distinct from hover.
- Do not rely on color alone for state.
- Maintain touch-operable targets and no hover-only actions.
- For composite/overlay controls, document focus movement, Escape, and return focus as applicable.
Responsive behavior
At sm, a dialog may need to become a near-full-screen task surface. Keyboard and return-focus rules still apply.
Theme comparison
The component job and interaction contract stay stable while product expression changes.
This will update the live version.
This will update the live version.
This will update the live version.
Tokens
Bind the implementation to semantic roles for surface, text, border, focus, spacing, shape, and motion as needed. Actual token names must come from the implemented Foundation; this demo deliberately does not mint package-level token names.
Code / Storybook
When this component exists in code, this section should link to its source and Storybook stories for executable states, Controls, viewport, accessibility checks, and interaction tests. The documentation page remains responsible for job, guidance, source contract, product decisions, themes, and Catalog lineage.