Usage guidance

When to use what — choosing the right component, severity, variant, and icon by use-case and viewport. Severity is intent, variant is emphasis, and every overlay reflows between desktop and mobile.

§1

Severity — which one?

Severity is intent, driven by the action's archetype. Never pick by colour preference.

Intent / archetype	Example	Icon
Main action that starts or advances a flow (Proceed archetype)	Create project, Continue, primary CTA	`Plus \| ArrowRight`
Brand-defined alternate action	secondary CTA	`contextual`
Action completes a POSITIVE outcome (Affirm)	Approve, Publish, Mark complete	`Check \| Upload`
Informational / learn-more (Inform)	Learn more, info callout action	`Info`
Reversible caution (Warn) — Label MUST be dark ink (text-primary-950), never white — fails AA on amber.	Archive, Unpublish, Disable	`AlertTriangle \| Archive`
Destroy / irreversible (Destroy/Alert) — Never commit inline — route through ConfirmDialog.	Delete, Remove permanently	`Trash`
Hint / help / tips	Show hint, help tooltips	`HelpCircle`
Support / secondary / cancel / dismiss	Cancel, Close, secondary action	`X \| none`

Tie-breaker for positive actions

If the click COMPLETES a positive outcome -> success; if it INITIATES/advances -> primary. Save = primary + Save icon; Save-and-approve = success.

§2

Variant — which emphasis?

One solid per action group; step down the ladder for companions and low-emphasis actions.

Emphasis ladder (high → low)

default(solid)softoutlineghostlink

Variant	Use when
	The single most important action in a group
	Tinted affordance / filter chip / status callout
	Standard companion to a solid primary (e.g. Cancel)
	Low-emphasis toolbar / row / dismiss action
	Inline in prose / tertiary navigation

Don't

Constraints

At most ONE solid (default) button per action group.
link + status severity (success/warning/danger) is almost always wrong.
Solid neutral is discouraged; use primary on inverse surface or outline+neutral.

§3

Single vs combination

Pairing, order, and destructive placement inside an action group.

Pair a solid <intent> with an outline neutral Cancel; never two competing solids.
LTR order: primary on the RIGHT in a footer row (justify-end).
Mobile stacked full-width: primary on TOP.
Destructive actions outside the mobile thumb zone; ConfirmDialog focuses Cancel first.

§4

Icon vs non-icon

Lead with an icon when it speeds archetype recognition — never decoration.

Add a leading icon when it speeds archetype recognition (Plus/ArrowRight/Check/Trash/Save/Info).
Trailing icon (ArrowRight/ChevronRight) for continue/next.
Destructive actions always include the Trash icon.
Never an icon on Cancel.
Icon-only (IconButton) requires aria-label; use only when meaning is unambiguous.
Don't stack leading + trailing icons unless both carry meaning.

§5

Component A vs B — by use-case + viewport

Choose by interruption level and surface, then reflow by viewport. The two viewport columns show how each surface adapts from desktop to mobile.

Component	Use when	Don't use when	Desktop	Mobile	Alternatives
`Dialog`	Blocks the flow and requires a decision	A success acknowledgment (use Toast) A non-blocking notice (use Banner/Alert)	centered modal, max-width	full-screen sheet from bottom	`Sheet` — Supplementary task that shouldn't fully block `Popover` — Lightweight anchored options
`ConfirmDialog`	Confirm a consequential/destructive action	Non-destructive quick toggles	centered	full-screen sheet	`Toast (with Undo)` — Reversible action like Archive — act immediately, offer Undo
`Sheet`	Supplementary task/selector alongside the current context	A blocking decision (use Dialog)	side panel	bottom sheet	`Drawer` — Persistent navigation drawer
`Drawer`	Slide-in panel (nav/aside) triggered from a toolbar	Modal decisions	aside as 30% sticky column	drawer from toolbar button	—
`Popover`	Rich contextual surface anchored to a trigger	A simple choice list (use DropdownMenu) Essential-only info (use inline)	anchored popover	anchored or bottom sheet	`DropdownMenu` — A menu of choices/commands `Tooltip` — Brief non-essential hint
`DropdownMenu`	A list of choices or commands from a button	Rich/interactive content (use Popover)	anchored menu	anchored / bottom sheet	`CommandMenu` — Searchable global command palette (Cmd+K)
`Tooltip`	Brief supplementary hint on hover/focus	Essential information (never hide it in a tooltip)	hover	long-press (or omit)	`HelpTip` — Persistent inline help affordance
`Toast`	Transient acknowledgment of a completed action	A persistent notice (use Banner) A required decision (use Dialog)	top-right	bottom-center	`Alert` — Attention needed inside the current view, non-transient
`Alert`	Draw attention inside the current view (inline banner)	Transient success (use Toast) Page-level system notice (use Banner)	inline	inline	—
`Banner`	Persistent page/system-level notice (account, billing, maintenance)	Transient feedback (use Toast)	top-full	top-full	—
`Badge / StatusBadge / StatusDot`	Label an ongoing status	An action (use Button)	inline	inline	—
`EmptyState`	A view has no content yet	A load failure (use ErrorState)	centered	centered	`ErrorState` — Content failed to load
`ErrorState`	Content failed to load / an operation errored	No content yet (use EmptyState)	centered with retry	centered with retry	—

§6

Density

Density scales the whole surface via data-density. Components stay theme- and mode-aware automatically.

compact

dense ops consoles / data tables

regular

default apps

spacious

consumer / marketing