States visually modify a UI element to convey specific information about its behavior or contents.

1. Component states: shows the availability of the element, such as disabled or read-only.
2. Focus states: shows whether the element is in focus or not. Focused elements respond to keyboard interactions.
3. Interaction states: shows the element’s relation to the pointer, such as hover or down.
4. Selection states: shows whether the user has selected or toggled the element.
5. Value states: shows the intended semantic meaning of the element, such as positive, negative, warning, or information.

Combinations: States can be combined across categories (e.g. an element in negative state can be hovered), but cannot be mixed within categories (e.g. an element cannot have positive and negative state at the same time).

Consistency: The visual modifications for various states can be different for different components (e.g. the hover state of a button and a text input), but some of these visual modifications are shared (e.g. disabled state generally looks the same across elements.)

Component States

Shows the element’s availability for interaction.
Default: Enabled State.

Disabled State

Shows that the user is not allowed to interact with an otherwise interactive element. Disabled elements cannot be focused, and have no hover or down states. Disabled form items are not submitted in forms.

General visual changes:

• Opacity: 40%
• Cursor: not-allowed

Disabled tooltip: we recommend adding a tooltip that explains to the user why the element is disabled.

Read-only State

Shows that the user cannot change the value of an otherwise editable element. Read-only elements can still be focused, and have hover and down states. Read-only form items are submitted like a regular form item.

General visual changes:

• Dashed underline or border.

Read-only vs static text: If the element can never be edited, make it static text instead.

Focus States

Shows whether the element is marked to receive keyboard input.
Default: Unfocused State.

Focused State

Shows that the element will receive keyboard input, e.g. hitting the spacebar while a button is focused will activate the button. Typically the element receives focus when the user clicks on it, or uses the tab key to select it in the focus chain.

General visual changes:

• Focus ring: an inner ring with a thick border.

Contextual Focus Ring: The focus ring is only shown when it's relevant for the user to see it, typically when they navigate using the keyboard. Elements like buttons only get the focus ring when they're focused via the keyboard, not by pressing them using a mouse. The browser can decide this for native elements using the :focus-visible pseudo-class, and custom DS components should follow this practice.

Interaction States

Shows the element’s relation to the cursor or other pointer device.
Default: Regular State.

Hover State

Shows that the user has moved the cursor in the element’s interactive area.
The hover state is especially useful on "borderless" elements like toolbar buttons, where the interactive area is not visually apparent to the user.

General visual changes:

• Changes in background color and border color.
• Cursor: pointer

Down State

Shows that the user is pressing down the mouse button over the element.
Also known as “Active” or “Mouse Down” state.

General visual changes:

• Changes in background color and border color.

Selection States

Shows whether the element is marked for selection.
Default: Unselected State.

Selected State

Shows that the element is selected, activated, or toggled. The exact meaning depends on the component and the context.

General visual changes:

• Highlighted background and border color.

Indeterminate State

Shows that the element corresponds to a list of selectable items, where there’s a mix of selected and unselected items.
Typically used in checkbox lists, where the parent item has an unselected state when no children are selected, a selected state when all children are selected, and an indeterminate state when only some children are selected.

Value States

Shows the semantic meaning for the element.
Default: Neutral State.

Negative State

This state is used for elements that carry negative meaning, such as error messages, failed validations, or bad metrics. May prevent users from continuing their work.
Also known as “error state”.

General visual changes:

• Red tint for background and border.

Destructive Buttons: Buttons which lead to destructive actions (e.g. deleting data) have negative state.

Warning State

This state warns the user about a minor problem they should take into consideration. Does not prevent users from continuing their work, but they might run into an error later.

General visual changes:

• Yellow tint for background and border.

Positive State

This state is used for elements that carry positive meaning, such as success messages, passed validations, or good metrics.
Also known as “success state”.

General visual changes:

• Green tint for background and border.

Information State

Visually emphasize elements to draw the users attention towards them. Used for important information that the user should read, or highlighted actions such as Submit buttons.
Also known as “highlight” or “important”.

General visual changes:

• Blue tint for background and border.