Button

Docs draft

Component story Figma component set ↗React component ↗DSDS entity ↗

When to use it

useTriggering an action in the current view: start playback, submit a form, confirm a dialog.

avoidNavigating to another page. That is a Link, even when it looks prominent. link

avoidMore than one primary button per view. Primary is the single main action; everything else steps down a weight. button Outline/ghost.

Anatomy

container — Pill (radius.full), 44px tall. Hugs its content horizontally.

leading icon — Optional, 20px. Waits on the Icon set; placeholder swap target until then.

label — Sentence case. The component never transforms case.

trailing icon — Optional, mirrors leading icon.

spinner — Replaces the label in the loading state; label stays in the accessibility tree.

Variants

variant · primary / secondary / outline / ghost / brand-outline / brand-ghost — primary = filled accent pill; secondary = inverse fill; outline/ghost = quiet neutrals; brand-outline/brand-ghost = orange text roles on quiet surfaces. One size (44px), per the reference — a size axis is added only when a rebuilt component demands one.

States

rest — At rest with no interaction.

hover — Pointer is over the control.

pressed — Actively pressed by pointer or key.

focused — Holds keyboard focus and shows the focus ring.

disabled — Not interactive; rendered with the lifted disabled tokens so it stays perceivable.

loading — Waiting on content; shows the loading treatment.

Guidelines

mustPrimary buttons carry ink text (color.accent.on-accent) on every accent fill state, never white. — White on brand orange is 2.9:1; ink holds 8.4:1 on hover and 4.9:1 on pressed. The gate contracts all three fills.

mustBrand-variant text uses color.accent.text and color.accent.text-pressed, never raw brand orange or the hover-lift orange. — The old DS-update reference put orange.450 text on the tint wash at 2.2:1; the contract color.accent.text on color.accent.wash replaces it at 5.7:1.

must-notDo not transform label case in content; the component renders labels exactly as written, sentence case. — Ruled with the pill shape from the DS-update reference; the earlier uppercase treatment is dead.

shouldWrite labels as verbs describing the action: Start watching, Add to Crunchylist. — Buttons act; links navigate.

must-notButton labels never wrap: the pill is single-line (white-space: nowrap in the component). A container too narrow for its buttons reflows or truncates around them; it does not bend the pill into two lines. — The 44px pill height assumes one line — a wrapped label overflows the anatomy and breaks the icon/label baseline. Caught 2026-09-01 in the HeroCarousel CTA pair, where flex squeeze wrapped both labels.

API

Prop	Type	Description
`variant`	`enum`	Visual style of the button.
`leadingIcon`	`ReactNode`	Rendered aria-hidden at 1.25em.
`trailingIcon`	`ReactNode`	Icon rendered after the label.
`loading`	`boolean`	Implies disabled + aria-busy; label moves to a visually hidden span.
`...rest`	`ButtonHTMLAttributes`	Forwarded to the native button.

Design specifications

radius	radius.full
height	space.44
padding-x	space.20
gap	space.4
label	type.label-lg
fill-primary-rest	color.accent.base
fill-primary-hover	color.accent.hover
fill-primary-pressed	color.accent.pressed
text-primary	color.accent.on-accent
fill-secondary	color.bg.inverse
text-secondary	color.text.on-inverse
border-outline	color.border.subtle
wash-hover	color.bg.secondary
wash-pressed	color.bg.pressed
border-brand	color.accent.base
text-brand	color.accent.text
text-brand-pressed	color.accent.text-pressed
wash-brand	color.accent.wash
border-disabled	color.border.subtle
text-disabled	color.text.disabled

Accessibility

Enter / Space — Activates the button.

Tab — Moves focus; focus-visible draws a 2px ring offset 3px in color.text.primary.

color.accent.on-accent on color.accent.base — Contracted at ≥ 4.5:1 by the build gate.

color.accent.on-accent on color.accent.hover — Contracted at ≥ 4.5:1 by the build gate.

color.accent.on-accent on color.accent.pressed — Contracted at ≥ 4.5:1 by the build gate.

color.text.on-inverse on color.bg.inverse — Contracted at ≥ 4.5:1 by the build gate.

color.accent.text on color.accent.wash — Contracted at ≥ 4.5:1 by the build gate.

The focus ring deliberately deviates from the reference's brand-orange ring: orange on cream is 2.7:1, below the 3:1 focus-appearance floor, so the ring binds color.text.primary in both themes. Loading announces via aria-busy with the label preserved in a visually hidden span. Disabled buttons stay visible at the declared muted contrast; the reference's #BBBBBB (1.7:1) was replaced by the lifted disabled token.