HandbookDraftStarts an action. Six variants, four sizes; one primary per group.
import { … } from "@brdgapp/ui/components/button"Button starts an action: save, send, sync, delete. It is Bridge's one button — every button-shaped control should be this component, not a hand-made <button> with pill classes. Its look comes only from variant and size. The usual mistake is restyling it with className (a font size, a color, a hover effect); className is for layout only.
primary for the main action of a group, such as Save or Make intro.secondary for a neutral action beside it, such as Settings, Copy link or Edit.ghost for a quiet, tertiary action, such as Cancel or Decline.link for an inline text action, such as Load more, Retry or View all.destructive for a confirmed dangerous action, such as Delete or Stop sharing.danger-ghost for a dangerous action inside a menu or list, such as Sign out or Remove.render for a button that navigates, so it stays a real link.One of each
Bridge has one button, one label, one menu, one tooltip, one confirm dialog and one table. Before building a control, look for it here. Never hand-make a second version (a <button> with pill classes, a <span> chip, a new kebab), even if it looks the same today: copies drift.
The look comes from props
A component's appearance comes only from its own options (variant, size, color). className on a package component is for layout (mt-4, shrink-0, w-full), never for font size, color, padding, radius or hover. If the look needs a className, the component or the chosen option is wrong: fix that instead.
Fix the system first
If the system can't express something a screen genuinely needs, extend the component (a new size, a new option) and document it in the same change, then use it. Never work around a gap at the call site. A 1–2px change from the old design is the expected cost of joining the system, not a reason to stay hand-made.
Fill with -solid
Anything with white text on a colored fill uses --primary-solid or --danger-solid. The brand --primary and --error are for text, icons and focus rings; as fills they fail contrast (white on --error is 4.41:1).
Reserve the space
Nothing that arrives later may push content down. A skeleton has the same height and shape as what it stands for, measured, not guessed. A visible jump after the first paint is a bug.
Sentence case
Buttons, titles, headings, tabs, labels and statuses use sentence case: only the first word and names get a capital. "Make intro", "Intro forwarded", "Stop sharing".
Say what happens
Buttons start with a verb and name the object: "Stop sharing", not "OK" or "Submit". A confirm dialog asks a question about the specific thing and its button repeats the verb. Errors say what happened and what to do next.
Container. A pill (rounded-full) with a fixed height per size. The link variant has no pill, height or padding.
Leading icon. Optional, from the icon prop. Sized by the button (14px at xs, 16px at sm/md, 18px at lg) and hidden from screen readers.
Label. SemiBold with 0.4px letter spacing. Its size comes from size: 12, 14, 14 or 16px.
Spinner. Replaces the icon while loading.
Focus ring. A 2px ring with a 2px offset, shown only for keyboard focus. Red for the danger variants, blue for the rest.
Six looks, from the main action to a danger link.
xs is the floor; sm is the default.
Pass a bare Lucide icon; the button sizes it.
loading for an action in progress; ButtonSkeleton before the data arrives.
| Rest | Hover | Focus | Pressed | Disabled | Loading | |
|---|---|---|---|---|---|---|
| Primary | ||||||
| Secondary | ||||||
| Ghost | ||||||
| Destructive | ||||||
| Danger ghost | ||||||
| Link |
| State | What happens |
|---|---|
| Rest | The variant's fill. Bordered variants sit on a solid raised surface, never transparent. |
| Hover | Fills darken (--primary-solid-hover, --danger-solid-hover); secondary gets a darker border; ghost gets a light fill; link underlines. |
| Focus visible | The focus ring. Mouse focus draws nothing. |
| Pressed | Pills scale to 98% while held. Primary deepens to --primary-active. |
| Disabled | 30% opacity and no pointer events. |
| Loading | Spinner in place of the icon, disabled, and aria-busy set, so it can't be pressed twice. |
| Not ready | Before the data a button needs has loaded, show ButtonSkeleton at the same size, so nothing shifts when the real button arrives. |
<button> through Base UI, so Enter and Space press it and a disabled button leaves the tab order.type="button", so a Button inside a form never submits it by accident. Pass type="submit" on the one that should.render={<Link href="…" />} draws a link with the button's look. It stays a link: screen readers announce it as one and ⌘-click opens a new tab. In this mode the link owns its content, so icon and loading don't apply.size-* class keeps it.fullWidth stretches every variant except link, which always reads as text.Do
Choose the look withvariant and size only.Don't
PassclassName="text-[13px]" or a color or hover class. If the look needs a className, the variant or size is wrong.Do
When moving an old control over, snap it to the nearest size: 13px becomessm, 10px becomes xs.Don't
Keep the old pixel value. A 1–2px change is the expected cost of joining the system.Do
Drop one-off flourishes when migrating. A text arrow (→) is fine.Don't
Graft on an animated arrow, a custom transition or a one-off accent color.Do
If the system truly can't express a button, extendbutton.tsx and document it here in the same change.Don't
Work around the gap with a className at the call site.--primary-solid and --danger-solid, dark enough for white text in both themes. The brand --primary and --error fail as fills (#E13535 with white text is 4.0:1), so never fill a button with them.danger-ghost text uses --danger-text, readable on both themes.xs (28px tall) is the smallest size; it clears the 24px minimum target.aria-label.link and danger-ghost don't rely on color alone: the label says what happens.| Keys | Action |
|---|---|
| Tab | Moves focus to the button. Disabled buttons are skipped unless `focusableWhenDisabled` is set. |
| Enter | Presses the button. |
| Space | Presses the button. |
Button
The button, built on Base UI Button. Extends Base UI Button (native <button> attributes).
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "primary" | "secondary" | "ghost" | "link" | "destructive" | "danger-ghost" | "primary" | The look. See When to use. |
size | "xs" | "sm" | "md" | "lg" | "sm" | Height 28, 32, 40 or 48px; label 12, 14, 14 or 16px. md matches a text field, so the two line up in a row. |
icon | ReactNode | — | A leading icon. Pass a bare Lucide icon. Ignored while loading and with render. |
loading | boolean | false | Shows a spinner, disables the button and sets aria-busy. |
fullWidth | boolean | false | Stretches to the container width (not for link). |
render | ReactElement | (props, state) => ReactElement | — | Draw another element with the button's look, such as a Next Link. It keeps its own semantics. |
disabled | boolean | false | Dims to 30% and blocks interaction. |
focusableWhenDisabled | boolean | false | Keeps a disabled button in the tab order, so a tooltip can explain why. |
className | string | — | Layout only (shrink-0, mt-4, self-start). Merged last. |
ButtonSkeleton
A placeholder pill for a button whose data hasn't loaded. Same height as the real button.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "sm" | Match the size of the button it stands in for. |
width | number | string | "7rem" | Roughly the real button's width. |
className | string | — | Layout only. |
buttonVariants
The class recipe behind Button, for the rare element that must look like a button but can't be one.
| Prop | Type | Default | Description |
|---|
What it's built from and where it's used, read from the code. When you change it, check these too.
Where the code still differs from the system. Follow the system, not the gap.
docs/BUTTON-AUDIT.md). Not yet swept: dashboard and marketing pages, admin, layout chrome, login, service-detail-modal, app-detail-content.asChild; this package uses render. Call sites change when Bridge OS moves to the package: <Button asChild><Link …/></Button> becomes <Button render={<Link …/>} />.cn is plain clsx, so a className can't reliably override a Button class there. The package's cn resolves clashes.components.md → Button / ButtonSkeleton, migration contract, button-system family (2026-10-29).src/components/ui/button.tsx (commit 5d9b382).useButton (default type="button"), checked in the installed source.