Button

Button styled by a tone × emphasis grammar: tone sets the semantic colour (neutral / brand / danger) and emphasis sets the visual weight (solid / soft / outline / ghost / transparent / link). Any pairing is valid - there is no fixed "primary/secondary" list; those looks are expressed as tone × emphasis pairs. An icon-only button (an icon-* size, or icon with no children) requires an aria-label; a dev-only console warning fires when it is missing. With render, styling and icon/dot decorations are applied to the element you pass in.

Usage

@instruments/materia-ui/components/button

<Flex align="center" gap="sm" justify="space-between" wrap="wrap">
  <Group gap="sm" wrap>
    <Button icon={Package} tone="brand">
      Request sample
    </Button>
    <Button emphasis="outline" icon={Heart} tone="neutral">
      Save to palette
    </Button>
    <Button
      aria-label="Share"
      emphasis="ghost"
      icon={Share2}
      tone="neutral"
    />
  </Group>
  <Button emphasis="ghost" icon={Trash2} tone="danger">
    Remove
  </Button>
</Flex>

Best practices

Express weight with tone×emphasis, not a variant prop - there is no "primary/secondary"; e.g. the destructive confirm is tone="danger".
Icon-only buttons MUST have an aria-label (a dev warning fires otherwise).
Use render to render a link element (e.g. render={<Link href="…" />}) rather than nesting a button inside an anchor.
loading keeps the button focusable while it blocks presses, so focus stays put across a submit; a plain disabled button leaves the tab order.
Reach for emphasis="ghost"/"link" in toolbars/headers - they carry data-edge-comp so containers can pull them flush to the edge.

Props

Prop	Type	Default	Description
tone	`"neutral" \| "brand" \| "danger" \| null \| undefined`
radius	`"rounded" \| "square" \| "full" \| null \| undefined`
square	`boolean \| null \| undefined`
emphasis	`"link" \| "outline" \| "solid" \| "ghost" \| "soft" \| "transparent" \| null \| undefined`
asInput	`boolean \| null \| undefined`
align	`"center" \| "end" \| "start" \| null \| undefined`
pressed	`boolean \| null \| undefined`
size	`ButtonSizeProp`	`"base"`	Size token; `icon-*` variants produce a square icon-only button. Also accepts a responsive object keyed by viewport breakpoints and/or `@`-prefixed container queries - e.g. `{ base: "sm", md: "base", "@sm": "lg" }`.
render	`useRender.RenderProp<Record<string, unknown>> \| undefined`		Replace the rendered `<button>` with another element or component (e.g. `<Link href="…" />`); styling, decorations and props are applied to it.
loading	`boolean \| undefined`	`false`	Show a spinner and block presses. The button stays focusable (it is `aria-disabled`, not natively disabled) so keyboard focus is kept.
loadingLabel	`string \| undefined`		Label shown in place of `children` while `loading`.
icon	`IconComponent \| undefined`		Leading icon (Lucide or SVG component); with no children it becomes an icon-only button.
iconClassName	`string \| undefined`		Extra classes for the leading icon.
suffixIcon	`IconComponent \| undefined`		Trailing icon (Lucide or SVG component) rendered at the end.
suffixIconClassName	`string \| undefined`		Extra classes for the trailing icon.
dot	`string \| undefined`		CSS colour for a status dot; empty/undefined renders no dot.
dotPlacement	`"end" \| "start" \| undefined`	`"start"`	Dot position relative to content.
expandable	`boolean \| undefined`	`false`	Icon-only at rest; expands on hover/focus-visible to reveal the label to the right of the icon. Collapsed geometry equals the matching icon-* size, expanded equals the text button of that size - so pass a text size (`sm`/`base`/`lg`) OR its icon twin (`icon-sm` …); both resolve identically. Requires both `icon` and children; ignored with `square`. The label stays in the DOM in both states (stable accessible name).
focused	`boolean \| undefined`		Force the focus ring on - for documentation/testing only.
hovered	`boolean \| undefined`		Force the hover state on - for documentation/testing only.
testId	`string`

Also exports

constBUTTON_EMPHASES
constBUTTON_TONES
typeButtonEmphasis
typeButtonProps
typeButtonSize
typeButtonTone
constbuttonVariants