Variants
Most components in the library don't invent their own vocabulary for color, style, or size. Instead, they reuse one of a handful of shared choices that mean the same thing everywhere they appear. Once "critical" or "outline" makes sense on one component, it makes sense on every other one that offers it too, so this page walks through each choice on its own, separately from any single component's page.
Action color
An interactive element, one you click to do something, picks a color
that signals what kind of action it is: primary for the main choice
in a section, secondary for a supporting or cancel action next to it,
critical for something destructive, success for a positive
confirmation, and warning for something that deserves a second look
before continuing.
Used by
Field style
A text field picks how its own boundary is drawn, independent of
color: outline (the default) draws a bordered box, fill swaps the
border for a tinted background, and underline keeps only a line
beneath the field, the lightest-weight of the three.
Used by
Both this and Action color share the same attribute name, variant, but mean two unrelated things: one is a color, the other a shape. Which one applies to a given component depends on whether it's an action or a field, never both at once.
Severity
Where action color says "this button does something risky", severity
says "this message matters in a particular way": info for a neutral
notice, success for a confirmation, warning for something that
deserves caution, critical for a real problem, and neutral for a
message with no particular urgency at all.
A neutral notice, nothing urgent.
Something completed the way it should.
Worth a second look before continuing.
Something went wrong and needs attention.
Used by
Appearance
Appearance changes how solid or subtle a surface looks, independent of
its color: fill is a solid, opaque background; default is a pale
tinted wash; outline keeps just a border; flat is a muted,
low-emphasis surface meant to stay in the background; raised adds a
drop shadow; and ghost, reserved for actions, stays invisible until
hovered or focused. No component uses all six: each picks whichever
subset actually fits what it is.
Used by
Color
Separate from severity, color is a plain, non-semantic palette pick,
for something like a category label or a plan tier that carries no
status of its own: primary and secondary follow the active theme's
brand colors, while light, medium, and dark are a plain neutral
scale of increasing weight.
Used by
Size
A shared five-step scale, from xs (extra small) to xl (extra large),
with m as the middle, default step. Small, compact components only
ever offer the three or four sizes that actually read as different at
that scale, rather than the full five.
Used by
Guidance
- Reuse the value that already matches what you mean: a destructive action and a critical alert should both be
critical, not onecriticaland the other a custom red - Pick action color and severity by what actually happened, not by which one looks nicest in the layout
- Reach for
color/tone only when nothing is being confirmed, warned about, or gone wrong, just a label with no status
- Overriding a variant's color with an inline style instead of picking the right variant, or a theme token if none fits (see
Theming ) - Mixing severities and action colors as if they were interchangeable: an
infobutton and aneutralbutton don't exist, since neither describes an action's own consequence
See also
Types : importing each of these as a real TypeScript union instead of retyping the words by handFoundations: Semantic states : the actual color tokens behind severity and action colorTheming : changing what each of these colors renders as, project-wide