Color Tokens - Primer

Primer Checkout iOS SDK is currently in beta (v3.0.0-beta.8). The API is subject to change before the stable release.

ColorOverrides lets you override individual color tokens used across the checkout UI. You pass one instance to PrimerCheckoutTheme as colors for light mode and, optionally, another as darkColors for dark mode. Every property is an optional Color?. Any token you leave nil keeps the SDK’s default for that appearance. colors applies only in light mode and darkColors only in dark mode. A token you set in colors does not carry over to dark mode: anything you leave nil in darkColors uses Primer’s dark default. The tables list the light and dark defaults as #RRGGBBAA hex values.

@available(iOS 15.0, *)
public struct ColorOverrides: Equatable {
  public init(
    primerColorBrand: Color? = nil,
    // ... all tokens below, each defaulting to nil
  )
}

Override primerColorBrand to recolor buttons, focus borders, loaders and selected states in one change. It applies to light mode through colors and to dark mode through darkColors. Override a more specific token only when one element must differ from the token it follows.

Brand and primary

Token	Type	Light default	Dark default	Description
`primerColorBrand`	`Color?`	`#2f98ffff`	`#2f98ffff`	Primary brand color. Fills the pay and primary buttons and tints the keyboard Done button. Focus borders, loaders and selected borders follow it unless you set them. The text cursor follows the focus border.
`primerColorOnBrand`	`Color?`	None (follows `primerColorBackgroundPrimary`)	None (follows `primerColorBackgroundPrimary`)	Label and spinner on brand-filled buttons.

Background and text

Token	Type	Light default	Dark default	Description
`primerColorBackgroundPrimary`	`Color?`	`#ffffffff`	`#171619ff`	Sheet and screen background.
`primerColorBackgroundSecondary`	`Color?`	`#2121210a`	`#efefef0a`	Subtle panels: ACH mandate box, country picker search bar, surcharge badge on the card number field, card network fallback badge on saved cards, and the vault section.
`primerColorBackgroundOutlinedDefault`	`Color?`	`#ffffffff`	`#171619ff`	Input field and Pay with card row fill. Follows `primerColorBackgroundPrimary` unless set.
`primerColorBackgroundOutlinedDisabled`	`Color?`	`#2121210a`	`#efefef0a`	Disabled input fill and disabled button fill.
`primerColorTextPrimary`	`Color?`	`#212121ff`	`#efefefff`	Main text and outlined button label.
`primerColorTextSecondary`	`Color?`	`#2121219e`	`#efefef9e`	Labels and descriptions.
`primerColorTextPlaceholder`	`Color?`	`#21212170`	`#efefef70`	Input placeholders.
`primerColorTextDisabled`	`Color?`	`#2121214d`	`#efefef4d`	Disabled button label and disabled field text.
`primerColorTextNegative`	`Color?`	`#b4324bff`	`#f6bfbfff`	Field error messages.
`primerColorTextLink`	`Color?`	`#2270f4ff`	`#4aaeffff`	Reserved. No component reads this token.
`primerColorTextOutlinedDefault`	`Color?`	`#212121ff`	`#efefefff`	Text typed into inputs. Follows `primerColorTextPrimary` unless set.

Border colors (outlined)

Borders of inputs, payment method rows, saved cards and outlined buttons, per state.

Token	Type	Light default	Dark default	Description
`primerColorBorderOutlinedDefault`	`Color?`	`#21212124`	`#efefef24`	Resting border of inputs, the Pay with card row, saved cards, outlined buttons and the card network badge.
`primerColorBorderOutlinedActive`	`Color?`	`#21212170`	`#efefef70`	Reserved. No component reads this token.
`primerColorBorderOutlinedFocus`	`Color?`	`#2f98ffff`	`#2f98ffff`	Focused input border. Follows `primerColorFocus` unless set.
`primerColorBorderOutlinedDisabled`	`Color?`	`#21212112`	`#efefef12`	Disabled input and outlined button border.
`primerColorBorderOutlinedError`	`Color?`	`#ff7279ff`	`#e46d70ff`	Border of an input in error. Also colors the error message shown under the payment method list.
`primerColorBorderOutlinedSelected`	`Color?`	`#2f98ffff`	`#2f98ffff`	Selected saved card, payment method row, Klarna category, card network and country check mark. Follows `primerColorBrand` unless set.
`primerColorBorderOutlinedLoading`	`Color?`	`#21212112`	`#efefef12`	Reserved. No component reads this token.

Border colors (transparent)

Reserved for elements with a transparent border. No component reads these tokens.

Token	Type	Light default	Dark default	Description
`primerColorBorderTransparentDefault`	`Color?`	`#ffffff00`	`#ffffff00`	Reserved.
`primerColorBorderTransparentActive`	`Color?`	`#ffffff00`	`#ffffff00`	Reserved.
`primerColorBorderTransparentFocus`	`Color?`	`#2f98ffff`	`#2f98ffff`	Reserved. Follows `primerColorFocus` unless set.
`primerColorBorderTransparentDisabled`	`Color?`	`#ffffff00`	`#ffffff00`	Reserved.
`primerColorBorderTransparentSelected`	`Color?`	`#ffffff00`	`#ffffff00`	Reserved.

Icon colors

Token	Type	Light default	Dark default	Description
`primerColorIconPrimary`	`Color?`	`#212121ff`	`#efefefff`	Back and close buttons, the card icon on the card payment method row, chevrons, and the saved card delete mark.
`primerColorIconDisabled`	`Color?`	`#2121214d`	`#efefef4d`	Reserved. No component reads this token.
`primerColorIconNegative`	`Color?`	`#ff7279ff`	`#e46d70ff`	Field error icon, error screen icon, and the QR code failure icon.
`primerColorIconPositive`	`Color?`	`#3eb68fff`	`#27b17dff`	Success screen check mark and the QR code success icon.

Utility

Token	Type	Light default	Dark default	Description
`primerColorFocus`	`Color?`	`#2f98ffff`	`#2f98ffff`	Focus color. Not drawn directly: the SDK copies it into `primerColorBorderOutlinedFocus` and `primerColorBorderTransparentFocus` unless you set those. Follows `primerColorBrand` unless set.
`primerColorLoader`	`Color?`	`#2f98ffff`	`#2f98ffff`	Loading spinners on screens and lists. A loading button shows its spinner in the button label color instead. Follows `primerColorBrand` unless set.

Overriding colors

Pass a ColorOverrides instance as colors for light mode and another as darkColors for dark mode. Tokens you omit keep the SDK default for that appearance.

import SwiftUI
import PrimerSDK

let brand = Color(red: 0.42, green: 0.36, blue: 0.91)

let theme = PrimerCheckoutTheme(
    colors: ColorOverrides(
        primerColorBrand: brand,
        primerColorBackgroundPrimary: .white,
        primerColorTextPrimary: Color(red: 0.10, green: 0.10, blue: 0.12),
        primerColorBorderOutlinedError: .red
    ),
    darkColors: ColorOverrides(
        primerColorBrand: brand,
        primerColorBackgroundPrimary: Color(red: 0.09, green: 0.09, blue: 0.10),
        primerColorTextPrimary: Color(red: 0.94, green: 0.94, blue: 0.94),
        primerColorBorderOutlinedError: .red
    )
)

struct CheckoutScreen: View {
    let clientToken: String

    var body: some View {
        PrimerCheckout(
            clientToken: clientToken,
            primerTheme: theme,
            onCompletion: { state in
                // handle the final PrimerCheckoutState
            }
        )
    }
}

Dark mode reads only darkColors. To change a token in both appearances, set it in both colors and darkColors. A dynamic Color, such as an asset catalog color set, shows only its value for the appearance of its group. A dynamic Color in colors always shows its light value.

Some tokens follow another token unless you set them too, so one change can recolor several elements. Within the same group (colors or darkColors):

primerColorBrand also moves primerColorFocus, primerColorLoader, primerColorBorderOutlinedSelected, primerColorBorderOutlinedFocus and primerColorBorderTransparentFocus.
primerColorFocus moves primerColorBorderOutlinedFocus and primerColorBorderTransparentFocus.
primerColorBackgroundPrimary moves primerColorBackgroundOutlinedDefault.
primerColorTextPrimary moves primerColorTextOutlinedDefault.
A nil primerColorOnBrand uses primerColorBackgroundPrimary.

A token you set explicitly always wins over the token it follows.

PrimerTheme

The container that bundles color, shape, spacing, and typography overrides.

Shape Tokens

Override corner radius and border width tokens.

Typography Tokens

Override font, size, weight, and line height per text style.

Spacing Tokens

Override spacing and size scale tokens.

​Brand and primary

​Background and text

​Border colors (outlined)

​Border colors (transparent)

​Icon colors

​Utility

​Overriding colors

​See also

PrimerTheme

Shape Tokens

Typography Tokens

Spacing Tokens

Brand and primary

Background and text

Border colors (outlined)

Border colors (transparent)

Icon colors

Utility

Overriding colors

See also