> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Styling variables

> Visual reference for all Primer Checkout styling variables

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

| Example | Description | Token |
| - | - | - |
| | **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

| Example | Description | Token |
| - | - | - |
| | **Text Primary**  Main text color for body content and labels. | `--primer-color-text-primary` |
| | **Text Outlined Default**  Text a shopper types into any input, including the hosted card fields. Defaults to Text Primary, so set it only when a field's text should differ from the sheet's. | `--primer-color-text-outlined-default` |
| | **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

| Example | Description | Token |
| - | - | - |
| | **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

| Example | Description | Token |
| - | - | - |
| | **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

| Example | Description | Token |
| - | - | - |
|  `2px` | **X-Small**  Subtle rounding for small elements. | `--primer-radius-xsmall` |
|  `4px` | **Small**  Default radius for inputs and small components. | `--primer-radius-small` |
|  `8px` | **Medium**  Default radius for dialogs, containers, and medium-sized components. Also used as the default button radius — see [Button styling tokens](#button-styling-tokens) to change button rounding without affecting these. | `--primer-radius-medium` |
|  `12px` | **Large**  Cards and larger containers. | `--primer-radius-large` |

## Spacing

| Example | Description | Token |
| - | - | - |
|  `2px` | **XX-Small**  Minimal spacing for tight layouts. | `--primer-space-xxsmall` |
|  `4px` | **X-Small**  Compact spacing between related elements. | `--primer-space-xsmall` |
|  `8px` | **Small**  Standard tight spacing. | `--primer-space-small` |
|  `12px` | **Medium**  Default component padding. | `--primer-space-medium` |
|  `16px` | **Large**  Spacing between sections. | `--primer-space-large` |
|  `20px` | **X-Large**  Generous spacing for visual separation. | `--primer-space-xlarge` |
|  `24px` | **XX-Large**  Widest step, for separating major blocks. | `--primer-space-xxlarge` |

## Size

| Example | Description | Token |
| - | - | - |
|  `16px` | **Small**  Small icons and indicators. | `--primer-size-small` |
|  `20px` | **Medium**  Default icon size. | `--primer-size-medium` |
|  `24px` | **Large**  Prominent icons. | `--primer-size-large` |
|  `32px` | **X-Large**  Large icons and avatars. | `--primer-size-xlarge` |
|  `40px` | **XX-Large**  Featured icons. | `--primer-size-xxlarge` |
|  `56px` | **XXX-Large**  Hero elements. | `--primer-size-xxxlarge` |

## Typography

### Font family

| Example | Description | Token |
| - | - | - |
| Aa Bb Cc 123 | **Brand Font**  System font stack for optimal rendering across platforms. | `--primer-typography-brand` |

### Title X-Large

| Property | Value | Token |
| - | - | - |
| Font Family | System font stack | `--primer-typography-title-xlarge-font` |
| Font Size | `24px` | `--primer-typography-title-xlarge-size` |
| Font Weight | `550` | `--primer-typography-title-xlarge-weight` |
| Line Height | `32px` | `--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

| Property | Value | Token |
| - | - | - |
| Font Family | System font stack | `--primer-typography-title-large-font` |
| Font Size | `16px` | `--primer-typography-title-large-size` |
| Font Weight | `550` | `--primer-typography-title-large-weight` |
| Line Height | `20px` | `--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

| Property | Value | Token |
| - | - | - |
| Font Family | System font stack | `--primer-typography-body-large-font` |
| Font Size | `16px` | `--primer-typography-body-large-size` |
| Font Weight | `400` | `--primer-typography-body-large-weight` |
| Line Height | `20px` | `--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

| Property | Value | Token |
| - | - | - |
| Font Family | System font stack | `--primer-typography-body-medium-font` |
| Font Size | `14px` | `--primer-typography-body-medium-size` |
| Font Weight | `400` | `--primer-typography-body-medium-weight` |
| Line Height | `20px` | `--primer-typography-body-medium-line-height` |
| Letter Spacing | `0px` | `--primer-typography-body-medium-letter-spacing` |

The quick brown fox jumps over the lazy dog

### Body Small

| Property | Value | Token |
| - | - | - |
| Font Family | System font stack | `--primer-typography-body-small-font` |
| Font Size | `12px` | `--primer-typography-body-small-size` |
| Font Weight | `400` | `--primer-typography-body-small-weight` |
| Line Height | `16px` | `--primer-typography-body-small-line-height` |
| Letter Spacing | `0px` | `--primer-typography-body-small-letter-spacing` |

The quick brown fox jumps over the lazy dog

## Border width

| Example | Description | Token |
| - | - | - |
|  `1px` | **Default**  Standard border width for inputs. | `--primer-width-default` |
|  `2px` | **Focus**  Emphasized border for focus states. | `--primer-width-focus` |
|  `2px` | **Selected**  Border width when selected. | `--primer-width-selected` |
|  `2px` | **Error**  Border width for error states. | `--primer-width-error` |

## Animation

| Property | Value | Token |
| - | - | - |
| Duration | `200ms` | `--primer-animation-duration` |
| Easing | `cubic-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-card-holder-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:

| Category | Properties | Description |
| - | - | - |
| 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-medium` | Internal padding and gaps |
| Border | `--primer-radius-small` | Border radius (4px) |
| Colors | See state-specific colors below | Background, border, and text colors |

### Input state colors

Inputs respond to user interaction with different visual states:

| State | Border | Background | Text |
| - | - | - | - |
| Default | `--primer-color-border-outlined-default` | `--primer-color-background-outlined-default` | `--primer-color-text-outlined-default` |
| 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.

These values are **unitless** — write `2`, not `2px`. A value carrying a unit falls back to the default rather than erasing the border. If you set widths through [`custom-styles`](https://primer.io/docs/sdk/primer-checkout-web/components/primer-checkout#properties), the SDK also logs a warning.

| State | Token | Value |
| - | - | - |
| Default | `--primer-width-default` | `1` |
| Hover | `--primer-width-hover` | `1` |
| Active | `--primer-width-active` | `1` |
| Focus | `--primer-width-focus` | `2` |
| Error | `--primer-width-error` | `2` |
| Selected | `--primer-width-selected` | `2` |
| Loading | `--primer-width-loading` | `1` |
| Disabled | `--primer-width-disabled` | `1` |

### Animation

All state transitions use consistent animation:

| Property | Token | Value |
| - | - | - |
| Duration | `--primer-animation-duration` | `200ms` |
| Easing | `--primer-animation-easing` | `cubic-bezier(0.44, 0, 0.4, 1)` |

### Example: customizing input appearance

```css theme={"dark"}
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;
}
```

***

## Button styling tokens

Every button Primer Checkout renders — payment method buttons, the card form's submit button, and the confirm button inside expandable payment methods like Klarna — reads its `border-radius` from `--primer-radius-button`.

| Property | Token | Default |
| - | - | - |
| Button radius | `--primer-radius-button` | Unset — falls back to `--primer-radius-medium` or `--primer-radius-small` |

> [!NOTE]
>
> Only buttons read `--primer-radius-button`. Containers, dialogs, inputs, and the Klarna category list read `--primer-radius-medium`/`--primer-radius-small` directly and are unaffected by it.

### Example: rounding all buttons

```css theme={"dark"}
primer-checkout {
  /* Pill-shaped buttons */
  --primer-radius-button: 999px;
}
```

***

## 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

| Example | Description | Token |
| - | - | - |
| | **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

| Example | Description | Token |
| - | - | - |
| | **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

| Example | Description | Token |
| - | - | - |
| | **Green 500**  Success and positive states. | `--primer-color-green-500` |

### Blue

| Example | Description | Token |
| - | - | - |
| | **Blue 500**  Informational elements. | `--primer-color-blue-500` |
| | **Blue 900**  Link text color. | `--primer-color-blue-900` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.