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 ladder

Three flavors of destructive map onto the same ladder.

State variants

positive confirms a completed action. selected indicates the active option in a group. inverse and on-color are for placement on dark or branded surfaces.

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.

import { LinkButton } from '@brikdesigns/bds';

<LinkButton href="/docs" variant="outline">
  Read docs
</LinkButton>

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

IconButton

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

import { IconButton } from '@brikdesigns/bds';

<IconButton icon={<CloseIcon />} label="Close dialog" variant="ghost" />
<IconButton icon={<TrashIcon />} label="Delete item" variant="danger-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 Button for navigation. If clicking takes the user to a new URL, use LinkButton so 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' | 'selected';

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