Over the page

Rules

• The native popover attribute, opened by a button with popovertarget: a click outside or Escape closes it, and the browser tells screen readers that the button's popover is open.
• It sits in the top layer, so opening it moves nothing.
• Where anchor positioning works it opens under its button; elsewhere, in the middle of the window.
• Short: a few lines, a short list or a small form. A long explanation or a decision is a dialog.
• It carries the one shadow, for things that float; panels have none.

Variants and states

States: closed and open.

Accessibility

Anatomy

Right after the button that opens it.

Roles it uses

Rules

• The WAI-ARIA menu button on the native popover attribute: a button with popovertarget and aria-haspopup="menu", and a role="menu" of role="menuitem" buttons. A click outside or Escape closes it.
• Load /v2/menu.js: opening it puts focus on its first item; the arrow keys, Home and End move; choosing an item, Escape or Tab closes it, and focus goes back to its button.
• Items are verbs or what they act on, in sentence case; a <hr> separates groups.
• An item shows hover and focus with a ground, never a change of size.
• A menu is for doing something; choosing a value is a select, and switching views is tabs.

Variants and states

States: closed and open.

Accessibility

Anatomy

Right after the button that opens it.

Roles it uses

Rules

• Load /v2/tooltip.js: it shows on hover and on keyboard focus, stays while the pointer moves onto it, and hides on Escape (WCAG 1.4.13).
• Its text is always in the page, named by the control's aria-labelledby (the tooltip is its name) or aria-describedby (it adds to the name), so a screen reader has it whether it shows or not.
• Never the title attribute, which a keyboard never sees.
• A few words: a name or a value. Anything longer, or anything to act on, is a popover.
• Nothing hovers on a phone: an icon button there still needs an icon people know.
• It opens in the top layer, above its control and inside the window, so it moves nothing.
• Corners signal function: this is something you read, so it stays square (--ds-radius-read).

Variants and states

States: hidden and shown.

Accessibility

Anatomy

On icon buttons in the top bar's tools; on a chart's points.

Roles it uses

Rules

• The native <dialog> opened with showModal(): focus moves in and stays, Escape closes it, and focus returns to what opened it. Load /v2/dialog.js and give the opening button data-ds-opens="<the dialog's id>", or call showModal() yourself.
• A <form method="dialog"> closes it: the value of the button pressed says which, with no script.
• A confirmation is role="alertdialog": its title asks the question and its text names what will happen ("Its 12 answers are deleted").
• The primary action first, named for what it does (Clear the run, not OK); focus starts on the safe choice (autofocus).
• Never the browser's own alert() or confirm().
• It sits in the top layer, so opening it moves nothing.

Variants and states

States: closed and open.

Accessibility

Anatomy

Opened by a button with data-ds-opens; the dialog itself may sit anywhere in the page.

Roles it uses

Rules

• A native <dialog> opened with showModal(), as a dialog is: focus moves in and stays, Escape closes it and focus returns. Load /v2/dialog.js and open it from a button with data-ds-opens.
• closedby="any" closes it on a click outside, where the browser knows the attribute; Escape and its Close button work everywhere.
• Its head holds its title and a Close button (a word; v2 has no close icon) in a <form method="dialog">.
• An inspector that stays open on a wide screen is a column of the page's layout, not a drawer; the drawer is for when there is no room for one.
• It sits in the top layer, so opening it moves nothing.
• Corners signal function: this is something you read, so it stays square (--ds-radius-read).

Variants and states

States: closed and open.

Accessibility

Anatomy

Opened by a button with data-ds-opens, often in the top bar's tools.

Roles it uses

Rules

• Load /v2/toast.js: it makes the page's .ds-toasts live region when the page loads, so the first toast is read; dsToast(text, { kind, word }) adds one, and so does a button with data-ds-toast.
• A toast is a notice: its first word says the kind (Saved, Added, Error), and the color only repeats it.
• It stays six seconds, and longer while the pointer or focus is on it; an error stays until it is dismissed. Each has a Dismiss button.
• Only for word from elsewhere on the page. What happens here, where someone is looking, is a notice in its own place.
• Never the only record of an error: say it where it happened too, in a field's note or a notice.
• Fixed at the window's foot, so it moves nothing.

Variants and states

States: shown, paused and gone.

Accessibility

Anatomy

At the window's foot; newer toasts below older ones.

Roles it uses