Skip to main content
Styling variables (design tokens) are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use tokens instead of hard-coded values to ensure a consistent UI across different platforms.

​
Color

​
Brand & Primary

ExampleDescriptionToken
Brand
Primary brand color. Used for interactive elements, focus states, and primary actions.		--primer-color-brand
Focus
Focus ring color for interactive elements. Defaults to brand color.		--primer-color-focus
Loader
Loading indicator color.		--primer-color-loader
Background Primary
Primary background color for components and surfaces.		--primer-color-background-primary
Background Secondary
Secondary background for subtle differentiation.		--primer-color-background-secondary

​
Text Colors

ExampleDescriptionToken
Text Primary
Main text color for body content and labels.		--primer-color-text-primary
Text Secondary
Supporting text, captions, and metadata.		--primer-color-text-secondary
Text Placeholder
Placeholder text in input fields.		--primer-color-text-placeholder
Text Disabled
Disabled text states.		--primer-color-text-disabled
Text Negative
Error messages and validation text.		--primer-color-text-negative
Text Link
Hyperlinks and interactive text.		--primer-color-text-link

​
Border Colors

ExampleDescriptionToken
Border Default
Default border for outlined containers.		--primer-color-border-outlined-default
Border Hover
Border color on hover state.		--primer-color-border-outlined-hover
Border Active
Border color on active/pressed state.		--primer-color-border-outlined-active
Border Focus
Border color when focused.		--primer-color-border-outlined-focus
Border Selected
Border color when selected.		--primer-color-border-outlined-selected
Border Error
Border color for error states.		--primer-color-border-outlined-error
Border Disabled
Border color when disabled.		--primer-color-border-outlined-disabled

​
Icon Colors

ExampleDescriptionToken
Icon Primary
Default icon color.		--primer-color-icon-primary
Icon Disabled
Disabled icon state.		--primer-color-icon-disabled
Icon Negative
Error and warning icons.		--primer-color-icon-negative
Icon Positive
Success and confirmation icons.		--primer-color-icon-positive

​
Border Radius

ExampleDescriptionToken
2pxX-Small
Subtle rounding for small elements.		--primer-radius-xsmall
4pxSmall
Default radius for inputs and small components.		--primer-radius-small
8pxMedium
Buttons and medium-sized components.		--primer-radius-medium
12pxLarge
Cards and larger containers.		--primer-radius-large

​
Spacing

ExampleDescriptionToken
2pxXX-Small
Minimal spacing for tight layouts.		--primer-space-xxsmall
4pxX-Small
Compact spacing between related elements.		--primer-space-xsmall
8pxSmall
Standard tight spacing.		--primer-space-small
12pxMedium
Default component padding.		--primer-space-medium
16pxLarge
Spacing between sections.		--primer-space-large
20pxX-Large
Generous spacing for visual separation.		--primer-space-xlarge

​
Size

ExampleDescriptionToken
16pxSmall
Small icons and indicators.		--primer-size-small
20pxMedium
Default icon size.		--primer-size-medium
24pxLarge
Prominent icons.		--primer-size-large
32pxX-Large
Large icons and avatars.		--primer-size-xlarge
40pxXX-Large
Featured icons.		--primer-size-xxlarge
56pxXXX-Large
Hero elements.		--primer-size-xxxlarge

​
Typography

​
Font Family

ExampleDescriptionToken
Aa Bb Cc 123Brand Font
System font stack for optimal rendering across platforms.		--primer-typography-brand

​
Title X-Large

PropertyValueToken
Font FamilySystem font stack--primer-typography-title-xlarge-font
Font Size24px--primer-typography-title-xlarge-size
Font Weight550--primer-typography-title-xlarge-weight
Line Height32px--primer-typography-title-xlarge-line-height
Letter Spacing-0.6px--primer-typography-title-xlarge-letter-spacing
The quick brown fox jumps over the lazy dog

​
Title Large

PropertyValueToken
Font FamilySystem font stack--primer-typography-title-large-font
Font Size16px--primer-typography-title-large-size
Font Weight550--primer-typography-title-large-weight
Line Height20px--primer-typography-title-large-line-height
Letter Spacing-0.2px--primer-typography-title-large-letter-spacing
The quick brown fox jumps over the lazy dog

​
Body Large

PropertyValueToken
Font FamilySystem font stack--primer-typography-body-large-font
Font Size16px--primer-typography-body-large-size
Font Weight400--primer-typography-body-large-weight
Line Height20px--primer-typography-body-large-line-height
Letter Spacing-0.2px--primer-typography-body-large-letter-spacing
The quick brown fox jumps over the lazy dog

​
Body Medium

PropertyValueToken
Font FamilySystem font stack--primer-typography-body-medium-font
Font Size14px--primer-typography-body-medium-size
Font Weight400--primer-typography-body-medium-weight
Line Height20px--primer-typography-body-medium-line-height
Letter Spacing0px--primer-typography-body-medium-letter-spacing
The quick brown fox jumps over the lazy dog

​
Body Small

PropertyValueToken
Font FamilySystem font stack--primer-typography-body-small-font
Font Size12px--primer-typography-body-small-size
Font Weight400--primer-typography-body-small-weight
Line Height16px--primer-typography-body-small-line-height
Letter Spacing0px--primer-typography-body-small-letter-spacing
The quick brown fox jumps over the lazy dog

​
Border Width

ExampleDescriptionToken
1pxDefault
Standard border width for inputs.		--primer-width-default
2pxFocus
Emphasized border for focus states.		--primer-width-focus
2pxSelected
Border width when selected.		--primer-width-selected
2pxError
Border width for error states.		--primer-width-error

​
Animation

PropertyValueToken
Duration200ms--primer-animation-duration
Easingcubic-bezier(0.44, 0, 0.4, 1)--primer-animation-easing
Hover to see animation

​
Input Styling Tokens

The hosted input components (primer-input-card-number, primer-input-card-expiry, primer-input-cvv, primer-input-cardholder-name) share a common set of CSS variables for consistent styling. These properties are applied via the primer-input-wrapper component which provides the visual structure.

​
Input Structure

All input components use these tokens for their visual appearance:
CategoryPropertiesDescription
Typography--primer-typography-body-large-*Input text (16px, weight 400)
Label--primer-typography-body-small-*Label text (12px, weight 400)
Spacing--primer-space-xsmall, --primer-space-mediumInternal padding and gaps
Border--primer-radius-smallBorder radius (4px)
ColorsSee state-specific colors belowBackground, border, and text colors

​
Input State Colors

Inputs respond to user interaction with different visual states:
StateBorderBackgroundText
Default--primer-color-border-outlined-default--primer-color-background-outlined-default--primer-color-text-primary
Hover--primer-color-border-outlined-hover--primer-color-background-outlined-hover-
Focus--primer-color-border-outlined-focus--
Error--primer-color-border-outlined-error--primer-color-background-outlined-error--primer-color-text-negative
Disabled--primer-color-border-outlined-disabled--primer-color-background-outlined-disabled--primer-color-text-disabled
Placeholder----primer-color-text-placeholder

​
Border Width by State

Border widths change based on interaction state to provide visual feedback:
StateTokenValue
Default--primer-width-default1px
Hover--primer-width-hover1px
Active--primer-width-active1px
Focus--primer-width-focus2px
Error--primer-width-error2px
Disabled--primer-width-disabled1px

​
Animation

All state transitions use consistent animation:
PropertyTokenValue
Duration--primer-animation-duration200ms
Easing--primer-animation-easingcubic-bezier(0.44, 0, 0.4, 1)

​
Example: Customizing Input Appearance

primer-checkout {
  /* Change input border radius */
  --primer-radius-small: 8px;

  /* Custom focus color */
  --primer-color-border-outlined-focus: #6366f1;

  /* Larger input text */
  --primer-typography-body-large-size: 18px;

  /* Custom error styling */
  --primer-color-border-outlined-error: #dc2626;
  --primer-color-text-negative: #dc2626;
}

​
Primitive Color Tokens

These are the base color values that semantic tokens reference. You typically won’t customize these directly — instead, customize the semantic tokens above which use these as their default values.

​
Gray Scale

ExampleDescriptionToken
Gray 000
Pure white. Base background color.		--primer-color-gray-000
Gray 100
Subtle backgrounds, disabled states.		--primer-color-gray-100
Gray 200
Light borders, dividers.		--primer-color-gray-200
Gray 300
Default border color.		--primer-color-gray-300
Gray 400
Disabled text, hover borders.		--primer-color-gray-400
Gray 500
Placeholder text, active borders.		--primer-color-gray-500
Gray 600
Secondary text color.		--primer-color-gray-600
Gray 900
Primary text color. Highest contrast.		--primer-color-gray-900

​
Red

ExampleDescriptionToken
Red 100
Light red for error backgrounds.		--primer-color-red-100
Red 500
Error borders and icons.		--primer-color-red-500
Red 900
Error text color.		--primer-color-red-900

​
Green

ExampleDescriptionToken
Green 500
Success and positive states.		--primer-color-green-500

​
Blue

ExampleDescriptionToken
Blue 500
Informational elements.		--primer-color-blue-500
Blue 900
Link text color.		--primer-color-blue-900