Component selection

Most on-system mistakes are selection mistakes — the right tokens applied to the wrong component. These decision guides resolve the common forks. They are written so you can paste them to an assistant, or follow them yourself.

Showing rows of data

• Read and sort only → Table.
• Filter, save views, pin columns, select rows, edit in place → DataGrid.
• A handful of key/value facts, not rows → a Card, not a table.

A button

• The one primary action on the view → Button variant="accent".
• A secondary action → variant="neutral" or quiet.
• Confirm / caution / destructive → variant="positive" | "notice" | "negative", and only for real meaning.
• Icon with no visible label → IconButton (it requires an accessible label).

Telling the user something

• Inline, contextual, tied to a region → Alert.
• Transient confirmation of an action → Toast.
• Blocking, needs a decision → Dialog.
• A whole region has nothing to show → EmptyState.

Progress and process

• A task the user works through → MultiStepForm with a Stepper.
• A record moving through stages it doesn't control → StatusPipeline.
• A determinate or indeterminate wait → ProgressBar or Spinner.

Choosing one of several

• 2–4 short, visible options → a segmented ToggleButtonGroup.
• A longer list → Select; filterable → ComboBox.
• Mutually exclusive, all visible, explanatory → RadioGroup.

Restricting access

• Gated/premium content → LockedOverlay.
• View cannot be edited → ReadOnlyBanner.
• No access at all → RestrictedState.

When in doubt, prefer the simpler component and add behaviour only when the user genuinely needs it.