Button

Anatomy

Five parts. Padding and gap come from spacing tokens; radius from --radius-lg2 (12px); height from --control-h-*.

When to use

• Triggering a primary action ("Place trade", "Confirm withdrawal", "Send")
• Triggering a destructive action ("Cancel order", "Delete account") — always with the --danger variant
• Submitting a form

When NOT to use

• For navigation — use a link (<a>) styled like a button if it changes the URL. Buttons are for actions, not navigation.
• For toggling state — use a switch or checkbox instead.
• As a tab trigger — use the .fam-tab primitive inside a .fam-tablist.

Variants

Four variants, each rendered identically across all 3 brands but tinted with that brand's primary color.

Sizes

5 sizes mapping to --control-h-* tokens.

States

Hover/active states are brand-specific via the motion vocabulary. Hover the buttons below to feel the difference.

Code

Pick your framework. HTML works today; React/Angular wrappers ship in v0.5.

<!-- Wrap any subtree in [data-brand] to set brand colors -->
<div data-brand="upsideonly">
  <button class="fam-btn fam-btn--primary fam-btn--xl">
    Submit Trade
  </button>

  <button class="fam-btn fam-btn--ghost fam-btn--md">
    Cancel
  </button>

  <!-- Icon-only: always include aria-label -->
  <button class="fam-btn fam-btn--primary fam-btn--icon"
          aria-label="Settings">
    <svg.../>
  </button>
</div>

// Import once at the entry of your app's CSS
@use "@perpetuals/design-tokens";

// Use the .fam-btn classes directly in markup, OR extend
// in your own classes if you need to add brand-specific variants
.my-trade-button {
  @extend .fam-btn;
  @extend .fam-btn--primary;
  @extend .fam-btn--xl;
}

// If you're on Tailwind, the family tokens are exported as a preset.
// Coming in v0.4 — for now, use the CSS classes directly:
<button className="fam-btn fam-btn--primary fam-btn--xl">
  Submit Trade
</button>

// OR equivalent inline Tailwind utilities (loses brand-tinting):
<button className="h-12 px-4 rounded-xl bg-green-500 text-black font-semibold">
  Submit Trade
</button>

// Coming in v0.5 — @perpetuals/ui-react package
import { Button } from '@perpetuals/ui-react';

function TradePanel() {
  return (
    <div data-brand="upsideonly">
      <Button variant="primary" size="xl">
        Submit Trade
      </Button>
      <Button variant="ghost" size="md">
        Cancel
      </Button>
    </div>
  );
}

<!-- Coming in v0.5 — @perpetuals/ui-angular package -->
<div data-brand="barriers">
  <button famButton
          variant="primary"
          size="xl">
    Submit
  </button>
</div>

Props / API (v0.5)

Available once the framework wrappers ship in v0.5. Until then, use the CSS classes directly — the modifier classes are 1:1 with these props.

Accessibility

Keyboard

• Tab — moves focus to the button (in document order)
• Enter or Space — activates the button (when focused)
• Focus-visible outline uses --brand-primary with a 2px outline + 2px offset

Screen reader

• Native <button> element is announced as "button"
• For icon-only buttons, aria-label is required (the visible icon doesn't read as text)
• For toggle-state buttons, use aria-pressed instead of styling alone
• For loading state, set aria-busy="true" while async work runs

Compliance

• Touch target — All sizes md and above (38px+) meet the 44×44 minimum when padding is included. SM (32h) is below — use only in dense desktop UI, never primary mobile actions.
• Color contrast — Primary variants meet 4.5:1 on their backgrounds (verified in /layout audit)
• Reduced motion — Hover transforms are killed when prefers-reduced-motion: reduce

Do's and Don'ts

Related

Changelog