Customization

Guide

All components are built on the shared token system in theme.css. Override tokens at the theme level and every component updates automatically.

How it works

Components use Tailwind utility classes that map directly to CSS custom properties — bg-bg-surface-2 compiles to background-color: var(--color-bg-surface-2). Override the token, every component reading it updates.

/* global.css — override once, propagates everywhere */
:root {
  --color-bg-surface-2: #1c1c1e;  /* changes Input, Dropdown, Switch track, etc. */
  --radius-sm: 6px;               /* changes Button, Input, Checkbox, Slider thumb… */
  --color-text-primary: #a78bfa;  /* changes primary Button bg, checked states… */
}

For per-instance overrides use the className prop with Tailwind utilities or inline CSS vars:

import { cn } from '@forma-studio/components'

// className — always works, specific to one element
<Button.Root variant="primary" className="rounded-full px-8">
  Pill button
</Button.Root>

// Scoped CSS var — overrides a token for this subtree only
<div style={{ '--color-text-primary': '#a78bfa' } as React.CSSProperties}>
  <Button.Root variant="primary">Purple primary</Button.Root>
  <Switch.Root>…</Switch.Root>  {/* also purple */}
</div>

Don't fight the system

Override tokens with other tokens, not raw values:

/* ✗ Fragile — breaks if you change the brand color later */
:root { --color-text-primary: #8b5cf6; }

/* ✓ Semantic — one source of truth */
:root {
  --color-brand: #8b5cf6;
  --color-text-primary: var(--color-brand);  /* now everything follows brand */
}

Token map — per component

Which base tokens each component reads, and what they control.

Form Controls
Button
TokenControls
--color-text-primaryPrimary variant background
--color-text-invertedPrimary variant text
--color-bg-surface-2Secondary variant background
--color-border-subtleSecondary variant border
--color-errorDestructive variant background
--color-state-hoverGhost / outline hover fill
--radius-smBorder radius (all variants)
Input · Autocomplete · Combobox · NumberField · OTPField
TokenControls
--color-bg-surface-2Background
--color-text-primaryValue text
--color-text-mutedPlaceholder text
--color-border-subtleBorder (default state)
--color-border-defaultBorder (hover state)
--color-border-strongBorder (focused state)
--color-error-borderBorder (error state)
--radius-smBorder radius
Checkbox · Radio
TokenControls
--color-bg-surface-2Unchecked background
--color-border-defaultBorder
--color-text-primaryChecked background
--color-text-invertedCheckmark / dot color
--radius-smCheckbox radius (Radio always uses --radius-full)
Switch
TokenControls
--color-bg-surface-3Track when off
--color-text-primaryTrack when on
--color-text-mutedThumb when off
--color-text-invertedThumb when on
Toggle · ToggleGroup
TokenControls
--color-text-secondaryInactive label color
--color-text-primaryActive label color
--color-bg-surface-3Active background
--color-border-subtleOuter border
--color-border-defaultActive item border
--color-state-hoverHover fill
--radius-smBorder radius
Slider
TokenControls
--color-bg-surface-3Track (unfilled) background
--color-text-primaryFill + thumb background
--color-bg-baseThumb inner border ring
--shadow-smThumb shadow
Select
TokenControls
--color-bg-surface-2Trigger + dropdown background
--color-border-subtleTrigger border (default)
--color-border-defaultTrigger border (hover) + dropdown border
--color-state-hoverItem hover fill
--color-state-activeSelected item fill
--radius-smTrigger radius
--radius-mdDropdown panel radius
--shadow-mdDropdown panel shadow
Field · Fieldset · Form
TokenControls
--color-text-primaryLabel text
--color-text-secondaryDescription text
--color-errorError message text + icon
--color-border-subtleFieldset border
--color-text-mutedFieldset legend text
--radius-smFieldset border radius
Overlays
Dialog · AlertDialog · Drawer
TokenControls
--color-bg-surface-1Panel background
--color-border-defaultPanel border
--color-bg-overlayBackdrop scrim
--radius-lgPanel border radius
--shadow-xlPanel shadow
Popover · PreviewCard
TokenControls
--color-bg-surface-1Panel background
--color-border-defaultPanel border
--radius-mdPanel border radius
--shadow-mdPanel shadow
Tooltip
TokenControls
--color-bg-surface-3Background
--color-text-primaryText color
--color-border-defaultBorder
--radius-smBorder radius
Toast
TokenControls
--color-bg-surface-2Background
--color-border-defaultBorder
--color-state-hoverDismiss button hover fill
--radius-mdBorder radius
--shadow-mdShadow
ContextMenu
TokenControls
--color-bg-surface-2Menu background
--color-border-defaultMenu border
--color-state-hoverItem hover fill
--color-errorDestructive item text
--color-error-bgDestructive item hover fill
--radius-smItem + menu border radius
--shadow-mdMenu shadow
Navigation
Menu · Menubar · NavigationMenu
TokenControls
--color-bg-surface-1Menubar container background
--color-bg-surface-2Popup / dropdown background
--color-border-defaultPopup border
--color-border-subtleTrigger border + item separators
--color-state-hoverTrigger + item hover fill
--color-state-activeOpen / active trigger fill
--color-text-mutedGroup label text
--radius-smTrigger + item radius
--shadow-mdPopup shadow
Tabs
TokenControls
--color-text-secondaryInactive tab label
--color-text-primaryActive tab label + indicator line
--color-border-subtleTab list bottom border
--color-state-hoverTab hover fill
Toolbar
TokenControls
--color-bg-surface-1Container background
--color-border-subtleContainer border + separator
--color-text-secondaryButton icon/label (inactive)
--color-text-primaryButton icon/label (active)
--color-state-hoverButton hover fill
--color-state-activeButton active/pressed fill
--radius-smButton border radius
Display
Accordion · Collapsible
TokenControls
--color-border-subtleDivider lines between items
--color-text-primaryTrigger label
--color-text-secondaryPanel / content text
--radius-smChevron icon border radius
Avatar
TokenControls
--color-bg-surface-3Fallback (no image) background
--color-text-secondaryFallback initials color
--color-border-subtleBorder (when shown)
--font-displayInitials font family
Progress · Meter
TokenControls
--color-bg-surface-3Track (unfilled) background
--color-text-primaryFill color
Scroll Area
TokenControls
--color-border-defaultScrollbar thumb
--color-border-strongScrollbar thumb (hover)
Separator
TokenControls
--color-border-subtleLine color
Code Preview
TokenControls
--color-bg-surface-1Container background
--color-bg-surface-2Tab bar background
--color-border-defaultContainer border
--color-border-subtleTab bar border
--color-text-secondaryInactive tab label
--color-text-primaryActive tab label + code text
--font-monoCode font family
--radius-smContainer border radius

Example — brand color

Set a single brand color and watch it propagate through every interactive component:

:root {
  /* One override drives: primary Button bg, Checkbox checked state,
     Switch on-track, Slider fill, active Tab indicator, Progress fill */
  --color-text-primary: #8b5cf6;

  /* Pair it: text on primary surfaces */
  --color-text-inverted: #ffffff;
}