Soracom

Design System
  1. Home
  2. Design system
  3. Styles
  4. 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

  • Include meaningful text or a recognizable, labelled icon; color should not be the only indication of status.
  • Visual-state classes do not validate forms or announce updates. For an invalid field, also set aria-invalid="true" and associate its error message using aria-describedby. Application code must update these attributes and messages when validation changes.
  • These are styling demonstrations. Buttons do not perform the named actions, and editing a control does not automatically change its visual-state class.

WCAG text contrast

The results below use the normal-text threshold of 4.5:1 for AA.

Standard large tags

Alert
Warning
Success
Info

Outline large tags

Alert
Warning
Success
Info

Status labels and text

Tags

Use tags for compact statuses. Include the status in the label rather than relying on the background color alone.

Tags in all four visual states

html
Copy

The same states work with the outline variant.

Outline tags in all four visual states

html
Copy

Text

Apply the state to text when the message itself needs emphasis, without adding a surrounding panel.

Text in all four visual states

html
Copy

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.

Labelled icons in all four visual states

html
Copy

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

Default buttons in all four visual states

html
Copy

Primary buttons

Primary buttons in all four visual states

html
Copy

Plain buttons

Plain buttons in all four visual states

html
Copy

Messages and containers

Notices

Notices provide an inline explanation of a status. Use actionable wording for alerts and warnings.

Notices in all four visual states

html
Copy

Combine the state with --strong for a more prominent notice.

Strong notices in all four visual states

html
Copy

Banners

Use a banner for a status that applies to a page or section. The heading and supporting text make the meaning explicit.

Banners in all four visual states

html
Copy

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.

Cards in all four visual states

html
Copy

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.

Text inputs and helper messages in all four visual states

html
Copy

Textareas

Multiline inputs use the same ds-input component and state modifiers.

Textareas in all four visual states

html
Copy

Selects

Selects can show the status of a selection without changing their native interaction.

Selects in all four visual states

html
Copy

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.

Checkboxes in all four visual states

html
Copy

Radio buttons

Each radio pair has its own name, so selecting an alternative in one state does not change the other examples.

Radio groups in all four visual states

html
Copy

Switches

Switches use the state on their wrapping label too. These examples represent notification preferences; toggle them to compare on and off appearances.

Switches in all four visual states

html
Copy