Button

Install and import

Button is in @dovetail-ds/react. Install it with React, if you haven't:

Guidelines

The system's action control. Use exactly one primary button per view. If two things are equally important, neither is.

Use it when

• The user performs an action: save, delete, add, continue.

Don't use it when

• It navigates somewhere. Use Link, or Button as="a" only when a navigation genuinely needs button prominence (a hero CTA).
• It toggles a setting instantly. Use Switch.

Example

<Inline gap="xs" justify="flex-end">
  <Button variant="secondary">Cancel</Button>
  <Button loading={saving}>Save changes</Button>
</Inline>

Variants

Sizes sm / md / lg. In marketing context md is already 48px, so lg is rarely needed.

On a brand tint

Inside a Section toned brand-muted, primary takes the brand colour and secondary the secondary brand colour, each with text that passes on it. Inside secondary-muted the two swap: primary takes the secondary brand colour and secondary the primary one. The band decides; the buttons in it need no prop. The colours come from --dt-surface-action-brand* and --dt-surface-action-brand-secondary*, the same steps the Configure panel checks for contrast.

<Section tone="brand-muted">
  <Inline gap="sm">
    <Button>Start free</Button>                 {/* the brand colour */}
    <Button variant="secondary">See plans</Button> {/* the secondary brand colour */}
  </Inline>
</Section>

Pass variant="brand" or variant="brand-secondary" to use those colours anywhere else.

Product vs marketing

The same component. Context tokens change its height, padding, and font size: dt-context-product gives a 40px/14px toolbar button, dt-context-marketing a 48px/16px CTA. Do not hand-size buttons per surface.

Tokens

Reads --dt-button-* (Tier 3), which resolve to --dt-surface-action* and --dt-text-on-action*. The brand variants read --dt-button-brand-* and --dt-button-brand-secondary-*, which resolve to --dt-surface-action-brand*, --dt-surface-action-brand-secondary* and their --dt-text-on-action-brand* pairs. Override the Tier 3 tokens to restyle Button alone; override the semantic tokens to move every action surface together.

As a link

as="a" with an href makes a real link that looks like a button. Button sets text-decoration: none, so the system's global link underline does not reach it; Link is the component that keeps the underline.

Accessibility

loading sets aria-busy and blocks clicks while keeping the label readable. Disabled buttons set both disabled and aria-disabled. Focus ring comes from the system.

Content

Verb-first, one to three words, sentence case. "Save changes", not "Submit" or "Click here". Never change the label to "Loading…"; the spinner says that already.

Props

The typed contract, from Button.d.ts.

import * as React from "react";

/**
 * The system's primary action control.
 */
export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  /** primary is the single main action in a view; everything else is secondary, ghost, or danger. brand and brand-secondary fill the button with the primary or secondary brand colour, with text that passes contrast on it. Inside a Section toned brand-muted or secondary-muted, primary and secondary take the brand colours on their own. @default "primary" */
  variant?: "primary" | "secondary" | "ghost" | "danger" | "brand" | "brand-secondary";
  /** @default "md" */
  size?: "sm" | "md" | "lg";
  disabled?: boolean;
  /** Shows a spinner and blocks interaction. Keep the label — never swap it for "Loading…". */
  loading?: boolean;
  fullWidth?: boolean;
  /** Icon before the label. 16px, currentColor. */
  iconStart?: React.ReactNode;
  /** Icon after the label. Reserve for external links and disclosure. */
  iconEnd?: React.ReactNode;
  /** Render as another element, e.g. "a" for a link that looks like a button. @default "button" */
  as?: keyof React.JSX.IntrinsicElements;
  children?: React.ReactNode;
}

export declare function Button(props: ButtonProps): React.JSX.Element;

Tokens it reads

Every custom property Button.jsx resolves, read from the source: 48 component, 1 semantic. Component tier first, because that is the one to reach for.

Open the graph

• component Its own tier. Override one of these and only this component moves.
• semantic Shared roles. Override one and everything using that role moves with it.

Source

React only, no dependencies, every value a token.

import React from "react";

const V = {
  primary: { bg: "--dt-button-primary-bg", hover: "--dt-button-primary-bg-hover", active: "--dt-button-primary-bg-active", fg: "--dt-button-primary-fg", border: "--dt-button-primary-border" },
  secondary: { bg: "--dt-button-secondary-bg", hover: "--dt-button-secondary-bg-hover", active: "--dt-button-secondary-bg-active", fg: "--dt-button-secondary-fg", border: "--dt-button-secondary-border" },
  ghost: { bg: "--dt-button-ghost-bg", hover: "--dt-button-ghost-bg-hover", active: "--dt-button-ghost-bg-active", fg: "--dt-button-ghost-fg", border: "--dt-button-ghost-border" },
  danger: { bg: "--dt-button-danger-bg", hover: "--dt-button-danger-bg-hover", active: "--dt-button-danger-bg-active", fg: "--dt-button-danger-fg", border: "--dt-button-danger-border" },
  brand: { bg: "--dt-button-brand-bg", hover: "--dt-button-brand-bg-hover", active: "--dt-button-brand-bg-active", fg: "--dt-button-brand-fg", border: "--dt-button-brand-border" },
  "brand-secondary": { bg: "--dt-button-brand-secondary-bg", hover: "--dt-button-brand-secondary-bg-hover", active: "--dt-button-brand-secondary-bg-active", fg: "--dt-button-brand-secondary-fg", border: "--dt-button-brand-secondary-border" },
};

export function Button({ variant = "primary", size = "md", disabled = false, loading = false, fullWidth = false, iconStart, iconEnd, as: Tag = "button", children, style, ...rest }) {
  const [state, setState] = React.useState("idle");
  const v = V[variant] || V.primary;
  const isOff = disabled || loading;
  const bg = isOff ? "var(--dt-button-disabled-bg)" : `var(${state === "active" ? v.active : state === "hover" ? v.hover : v.bg})`;
  const fg = isOff ? "var(--dt-button-disabled-fg)" : `var(${v.fg})`;
  const bd = isOff ? "var(--dt-button-disabled-border)" : `var(${v.border})`;

  return (
    <Tag
      disabled={Tag === "button" ? isOff : undefined}
      aria-disabled={isOff || undefined}
      aria-busy={loading || undefined}
      onMouseEnter={() => !isOff && setState("hover")}
      onMouseLeave={() => setState("idle")}
      onMouseDown={() => !isOff && setState("active")}
      onMouseUp={() => !isOff && setState("hover")}
      style={{
        display: "inline-flex", alignItems: "center", justifyContent: "center",
        gap: "var(--dt-button-gap)",
        height: `var(--dt-button-height-${size})`,
        padding: `0 var(--dt-button-padding-${size})`,
        fontFamily: "var(--dt-button-font-family)",
        fontSize: `var(--dt-button-font-size-${size})`,
        fontWeight: "var(--dt-button-font-weight)",
        lineHeight: 1,
        color: fg,
        background: bg,
        border: `var(--dt-button-border-width) solid ${bd}`,
        borderRadius: "var(--dt-button-radius)",
        cursor: isOff ? "not-allowed" : "pointer",
        textDecoration: "none",
        transition: "background var(--dt-button-transition), border-color var(--dt-button-transition)",
        width: fullWidth ? "100%" : undefined,
        whiteSpace: "nowrap",
        ...style,
      }}
      {...rest}
    >
      {loading ? <Spinner /> : iconStart}
      {children}
      {iconEnd}
    </Tag>
  );
}

function Spinner() {
  return (
    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" aria-hidden="true" style={{ width: "var(--dt-size-icon-sm)", height: "var(--dt-size-icon-sm)", animation: "dt-spin 700ms linear infinite" }}>
      <path d="M21 12a9 9 0 1 1-6.219-8.56" />
    </svg>
  );
}

In context

Button also appears on the actions reference cards, alongside the rest of its family.

• ActionsDetail