Modal

The modal is a centered dialog over a themed backdrop. It is built for agent settings, confirmations, and tall scrollable panels (for example Skills). It is themed through the global --ds-* tokens; set data-theme="dark" on an ancestor (commonly <html>) for dark mode. Form controls inside a modal inherit theme-aware colors automatically.

In production, .cmp-modal is position: fixed and covers the viewport. The previews below scope the overlay to the example frame so multiple variants can appear on one doc page.

Portable HTML

Copy the HTML from the code blocks below, include the design system stylesheet (base.css), and wire open/close behavior in your host (React, vanilla JS, etc.).

Small dialog

Default width (~32rem). Use cmp-modal__dialog--sm explicitly or omit a size modifier (sm is the default max-width on __dialog).

<div class="cmp-modal" role="presentation">
  <div
    class="cmp-modal__dialog cmp-modal__dialog--sm"
    role="dialog"
    aria-modal="true"
    aria-labelledby="doc-modal-sm-title"
  >
    <header class="cmp-modal__header">
      <h2 id="doc-modal-sm-title" class="cmp-heading-6 cmp-modal__title">
        <p>Settings</p>
      </h2>
    </header>
    <div class="cmp-modal__body">
      <label class="cmp-form-label" for="doc-modal-api-key">
        <p>API key</p>
      </label>
      <input
        id="doc-modal-api-key"
        class="cmp-input"
        type="password"
        placeholder="Your API key"
      />
    </div>
    <footer class="cmp-modal__footer">
      <button
        type="button"
        class="cmp-button cmp-button--white cmp-button--narrow"
      >
        <p>Cancel</p>
      </button>
      <button
        type="button"
        class="cmp-button cmp-button--red cmp-button--narrow"
      >
        <p>Save</p>
      </button>
    </footer>
  </div>
</div>

Large column layout

For tall content (Skills-style), add cmp-modal__dialog--lg and cmp-modal__dialog--column so the body scrolls inside a capped-height panel.

<div class="cmp-modal" role="presentation">
  <div
    class="cmp-modal__dialog cmp-modal__dialog--lg cmp-modal__dialog--column"
    role="dialog"
    aria-modal="true"
    aria-labelledby="doc-modal-lg-title"
  >
    <header class="cmp-modal__header">
      <h2 id="doc-modal-lg-title" class="cmp-heading-4 cmp-modal__title">
        <p>Skills</p>
      </h2>
      <button
        type="button"
        class="cmp-button cmp-button--white cmp-button--narrow"
      >
        <p>Close</p>
      </button>
    </header>
    <div class="cmp-modal__body">
      <p class="cmp-paragraph" style="margin-top: 0"></p>
      <p>
        Skills provide specialized instructions the assistant can activate on
        demand.
      </p>
    </div>
  </div>
</div>

Dark variant

Set data-theme="dark" on an ancestor (not on .cmp-modal itself) so tokens apply to the dialog and its form controls.

<div data-theme="dark" style="position: absolute; inset: 0">
  <div class="cmp-modal" role="presentation">
    <div
      class="cmp-modal__dialog cmp-modal__dialog--sm"
      role="dialog"
      aria-modal="true"
      aria-labelledby="doc-modal-dark-title"
    >
      <header class="cmp-modal__header">
        <h2 id="doc-modal-dark-title" class="cmp-heading-6 cmp-modal__title">
          <p>Delete configuration</p>
        </h2>
      </header>
      <div class="cmp-modal__body">
        <p class="cmp-paragraph">Remove this config from the manifest?</p>
      </div>
      <footer class="cmp-modal__footer">
        <button
          type="button"
          class="cmp-button cmp-button--white cmp-button--narrow"
        >
          <p>Cancel</p>
        </button>
        <button
          type="button"
          class="cmp-button cmp-button--red cmp-button--narrow"
        >
          <p>Delete</p>
        </button>
      </footer>
    </div>
  </div>
</div>

Classes

Class	Element	Purpose
`cmp-modal`	div	Fixed overlay and backdrop
`cmp-modal__dialog`	div	Centered panel
`cmp-modal__dialog--sm`	div	~32rem max width (default)
`cmp-modal__dialog--md`	div	~40rem max width
`cmp-modal__dialog--lg`	div	~56rem max width
`cmp-modal__dialog--column`	div	Flex column; scrollable body
`cmp-modal__header`	header	Title row and actions
`cmp-modal__title`	h1–h6	Title slot
`cmp-modal__body`	div	Main content
`cmp-modal__footer`	footer	Action row

Accessibility Guidelines

Set role="dialog" and aria-modal="true" on the panel; tie the title with aria-labelledby.
Use role="presentation" on the backdrop if it is not interactive, or handle overlay click and Escape in script.
Trap focus and return focus to the trigger when the dialog closes in production UIs.

Theming

Uses --ds-overlay, --ds-surface, --ds-fg, --ds-border, --ds-shadow, and form tokens inside the dialog. Set data-theme="dark" on an ancestor to switch themes.