Button

The button family is three components for three semantic needs. Pick the right one before you reach for variants — the wrong shell semantically can't be fixed with styling.

<Button>Save</Button>

<LinkButton href="/docs">…</LinkButton>

<IconButton icon={…} label="Close" />

Use it for

• Submitting a form
• Confirming or cancelling a destructive operation
• Opening a sheet, dialog, or popover
• Triggering an immediate, synchronous action

Import

import { Button, LinkButton, IconButton } from '@brikdesigns/bds';

Anatomy

Variants

Twelve variants. Pick by action emphasis and destructive intent, not by aesthetics.

Standard ladder

Destructive

negative is the destructive action — confirm dialogs, delete-and-go flows.

The danger / danger-outline / danger-ghost trio that used to sit below it was retired in #1957: it carried the brand accent-red rather than the system negative, and had zero call sites across every consumer repo. The retired spellings still resolve to negative for one minor and warn once in the console.

Lower-emphasis destructive (an outline or ghost button that is also negative) is not expressible today, because variant carries form and valence on one axis. Tracked in #1983.

State variants

positive confirms a completed action. inverse and on-color are for placement on dark or branded surfaces. To mark the active option in a group, pass the boolean selected prop on top of any variant — it is a state modifier, not a variant value.

Sizes

Five sizes. md is the default. Use sm only inside dense surfaces (table rows, popovers); use lg/xl for primary CTAs on landing pages.

Icons

Use iconBefore and iconAfter props. Icons should use 1em sizing to scale with the button's font size.

<Button iconBefore={<PlusIcon />}>Add item</Button>
<Button iconAfter={<ArrowRightIcon />}>Continue</Button>
<Button iconBefore={<DownloadIcon />} variant="outline">
  Export CSV
</Button>

Loading

The loading prop replaces button content with a spinner while preserving button width. The button is automatically disabled during loading.

<Button loading variant="primary">
  Saving...
</Button>

LinkButton

An <a> element styled as a button. Use when the action navigates to a URL. The href prop is required.

// Preferred — unified Button API
<Button href="/docs" variant="outline">
  Read docs
</Button>

<Button
  href="https://github.com/brikdesigns/brik-bds"
  target="_blank"
  rel="noopener"
  iconAfter={<ExternalLinkIcon />}
>
  GitHub
</Button>

// Deprecated — thin wrapper, same result
<LinkButton href="/docs" variant="outline">Read docs</LinkButton>

IconButton

An icon-only button with a required label prop for accessibility. The label becomes the button's aria-label.

// Preferred — unified Button API
<Button icon={<CloseIcon />} label="Close dialog" variant="ghost" />
<Button icon={<TrashIcon />} label="Delete item" variant="negative" />

// Deprecated — thin wrapper, same result
<IconButton icon={<CloseIcon />} label="Close dialog" variant="ghost" />

When not to use

• Don't use ghost for the only action on a page. Ghost is the lowest emphasis tier — it should appear alongside a higher-emphasis sibling.
• Don't stack two primary buttons next to each other. Only one primary action per surface.
• Don't use a plain Button for navigation. If clicking takes the user to a new URL, pass href so Button renders as an <a> and right-click + keyboard navigation work correctly.

Accessibility

• Renders a real <button> element. Keyboard navigation, focus ring, and Enter / Space activation come from the platform.
• Accessible name comes from the visible label. For IconButton, label becomes aria-label.
• Disabled state uses the disabled attribute, which removes it from the tab order. For "blocked but explainable" actions, prefer keeping it focusable and showing a tooltip.
• Loading state announces via aria-busy and disables interaction without removing focus.

API

The full prop reference (with auto-extracted TypeScript types and live controls) lives in Storybook → Components/Action/Button. Summary below.

Button

LinkButton

IconButton

Type unions

type ButtonVariant =
  | 'primary' | 'outline' | 'secondary' | 'ghost'
  | 'inverse' | 'on-color'
  | 'danger' | 'danger-outline' | 'danger-ghost' | 'destructive'
  | 'positive';

type ButtonSize = 'tiny' | 'sm' | 'md' | 'lg' | 'xl';

CSS Override API

Component-scoped CSS variables exposed on .bds-button. Set these on a wrapping element or directly on the button to override without touching BDS internals.

/* Example: flatten press effect in a toolbar context */
.my-toolbar {
  --button-active-translate-y: 0;
  --button-focus-outline-width: 3px;
}

Related

• Storybook playground — every variant × size × state, live controls
• Forms pattern — Save/Cancel placement, submit-state handling
• Components index — full component catalog