- Home
- Design system
- Styles
- Visual states
Visual states
Compare all four visual states across buttons, tags, notices, cards, form controls, and other SDS components.
Overview
Visual states communicate meaning, not just color. SDS provides four state modifiers that can be applied to supported components:
| State | Modifier | Use for |
|---|---|---|
| Alert | --alert |
Errors, failed operations, or destructive actions. |
| Warning | --warning |
Conditions that need attention, such as approaching a usage limit. |
| Success | --success |
Successful operations, valid input, or a healthy status. |
| Info | --info |
Helpful context, instructions, or informational updates. |
Choose the state that matches the message. Do not use --alert merely to make something red; use component colors for decorative color choices.
Applying a state
Add one visual-state modifier to the component root, alongside its other supported modifiers. For example, ds-button --primary --warning combines the primary button style with a warning state. For checkboxes, radio buttons, and switches, the component root is the wrapping label, not the native input.
The live-code examples below show alert, warning, success, and info, in that order. Each live-code example includes all four states so you can compare their treatment across components. Use the live editor to try other combinations and the site theme control to compare light and dark appearances.
States and behavior
WCAG text contrast
The results below use the normal-text threshold of 4.5:1 for AA.
Standard large tags
Outline large tags
Status labels and text
Tags
Use tags for compact statuses. Include the status in the label rather than relying on the background color alone.
The same states work with the outline variant.
Text
Apply the state to text when the message itself needs emphasis, without adding a surrounding panel.
Icons with labels
Icons can reinforce a status. These icons are decorative because the adjacent text conveys the same information. An icon used without visible explanatory text needs an accessible name instead.
Buttons
Buttons support visual states in default, primary, and plain styles. Keep the label in a child span. These examples use type="button" so they do not submit a surrounding form.
Default buttons
Primary buttons
Plain buttons
Messages and containers
Notices
Notices provide an inline explanation of a status. Use actionable wording for alerts and warnings.
Combine the state with --strong for a more prominent notice.
Banners
Use a banner for a status that applies to a page or section. The heading and supporting text make the meaning explicit.
Cards
Apply the state to the card root when it describes the whole card. Let the card supply its content colors rather than repeating the state on every child.
Form controls
Keep a visible label for each control and explain what the state means. The field container groups labels, controls, and helper text; apply the visual state to the supported control or message inside it, not to ds-field itself.
Text inputs
These inputs pair state styling with helper text. Only the alert example is marked invalid; warnings and informational messages do not necessarily indicate invalid input.
Textareas
Multiline inputs use the same ds-input component and state modifiers.
Selects
Selects can show the status of a selection without changing their native interaction.
Checkboxes
Put the state on the checkbox wrapper. These controls start checked so their state accents are visible; toggle them to compare checked and unchecked appearances.
Radio buttons
Each radio pair has its own name, so selecting an alternative in one state does not change the other examples.
Switches
Switches use the state on their wrapping label too. These examples represent notification preferences; toggle them to compare on and off appearances.