Dialtone

Guidelines

Modals are used to present a short-term task the user needs to perform without losing the context of the underlying page. Users won't be able to interact with the page until they close the modal.

Although highly versatile, this doesn't mean modal dialogs are fit for all purposes. Modals are purposefully disruptive and should be used thoughtfully and sparingly, specifically in moments where focus is required or an action must be taken.

Don't use for	Use for
Confirming an action took place (instead: use a Toast)	Confirming a destructive action that is about to happen
Revealing more information (instead: place content inline)	Entering the name and description of a new Call Center
Displaying complex forms or large amounts of information (instead: place content inline)	Ask for a user’s consent for an action
Displaying content unrelated to current task (instead: place content inline as link or banner)

Best practices

Limit the number of interactions in a modal. Remove anything that does not support the task.
Avoid multiple steps that require navigation within the modal dialog.
Avoid complex decision making that requires additional sources of information unavailable in the modal.
Label links and buttons with a verb that indicates what happens when it’s selected.
The primary button should reflect the modal title.
Don’t surprise users by popping up a modal. Let a user’s action, such as a button click, trigger the modal. Uninvited modals may surprise the user and result in a quick dismissal of the window.

Classes

At minimum, modals contain a title and one button. They could also contain body text, brand illustrations, product wireframes, or multiple buttons.

Class	Applies to	Description
.d-modal	N/A	Parent modal container
.d-modal__dialog	Child of .d-modal	Base dialog container for modal content.
.d-modal__header	Child of .d-modal__dialog	Adds proper styling for the modal's header.
.d-modal__content	Child of .d-modal__dialog	Adds proper styling for the modal's content area.
.d-modal__footer	Child of .d-modal__dialog	Adds proper styling for the modal's footer.
.d-modal__close	Child of .d-modal__dialog	Adds proper styling for the modal's dismiss button.
.d-modal--full	.d-modal	Makes .d-modal__dialog take up as much of the screen as possible.
.d-modal--danger	.d-modal	Adds styling for destructive actions.

Accessibility

When opened modals “trap focus,” meaning keyboard navigation controls are constrained to elements within the modal. Focus doesn't return to the underlying page until the user explicitly dismisses the modal.

To ensure maximum compatibility, all a tags must have an hrefattribute. Also any elements which you don't want to be focusable (but might be focusable by default) must have their tabindex set to -1.

Attribute	Applies to	Description
aria-describedby=[id]	.d-modal	Provide the modal's copy ID here. Assistive technologies, such as screen readers, use this to associate text with a widget, elements groups, headings, definitions, etc. (Source)
aria-hidden=[state]	.d-modal	Informs assistive technologies, such as screen readers, if they should ignore the element. This should not be confused with the HTML hidden attribute which tells the browser to not display an element. (Source)
aria-label=[text]	.d-modal__close	Labels the close element for assistive technologies (Source)
aria-labelledby=[id]	.d-modal	Supply the modal's title ID here. Assistive technologies, such as screen readers, use this attribute to catalog the document objects correctly. (Source)
role="dialog"	.d-modal	Identifies the modal as a dialong element for assistive technologies (Source)
role="document"	.d-modal__dialog	Helps assistive technologies to switch their reading mode from the larger document to a focused dialog window (Source)

Examples

Default

Close

<aside class="d-modal" id="modal-base" tabindex="-1" role="dialog" aria-labelledby="modal-title" aria-describedby="modal-description" aria-hidden="true">
    <div class="d-modal__dialog" role="document">
        <h1 class="d-modal__header" id="modal-title">…</h1>
        <p class="d-modal__content" id="modal-description">…</p>
        <footer class="d-modal__footer">
            <button class="d-btn--primary" type="button">…</button>
            <button class="d-btn" type="button">…</button>
        </footer>
    </div>
    <a href="#" class="d-modal__close d-btn--circle" aria-label="Close"><IconClose \></a>
</aside>

Danger

A modal style for destructive or irreversible actions.

Close

<aside class="d-modal d-modal--danger" id="modal-base" tabindex="-1" role="dialog" aria-labelledby="modal-title" aria-describedby="modal-description" aria-hidden="true">
    <div class="d-modal__dialog" role="document">
        <h1 class="d-modal__header" id="modal-title">…</h1>
        <p class="d-modal__content" id="modal-description">…</p>
        <footer class="d-modal__footer">
            <button class="d-btn--danger--primary" type="button">…</button>
            <button class="d-btn--danger" type="button">…</button>
        </footer>
    </div>
    <a href="#" class="d-modal__close d-btn--circle" aria-label="Close"><IconClose \></a>
</aside>

With Inline Banner

Since modals are a small form factor, our inline banners are anchored to the top of the modal to save space.

Close

<aside class="d-modal" id="modal-base" tabindex="-1" role="dialog" aria-labelledby="modal-title" aria-describedby="modal-description" aria-hidden="true">
    <div class="d-modal__banner d-d-none js-example-modal-banner-full">…</div>
    <div class="d-modal__dialog" role="document">
        <h1 class="d-modal__header" id="modal-title">…</h1>
        <p class="d-modal__content" id="modal-description">…</p>
        <footer class="d-modal__footer">
            <button class="d-btn--primary" type="button">…</button>
            <button class="d-btn" type="button">…</button>
        </footer>
    </div>
    <a href="#" class="d-modal__close d-btn--circle" aria-label="Close"><IconClose \></a>
</aside>