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

# PrimerTheme

> Central theming configuration for all Primer Checkout components

<Warning>
  Primer Checkout Android SDK is currently in **beta** (v3.0.0-beta.4).
  The API is subject to change before the stable release.
</Warning>

Root theme container holding all design token groups. Pass to `PrimerCheckoutSheet` or `PrimerCheckoutHost` via the `theme` parameter.

## Definition

```kotlin theme={"dark"}
data class PrimerTheme(
    val lightColorTokens: LightColorTokens = LightColorTokens(),
    val darkColorTokens: DarkColorTokens = DarkColorTokens(),
    val borderWidthTokens: BorderWidthTokens = BorderWidthTokens(),
    val radiusTokens: RadiusTokens = RadiusTokens(),
    val sizeTokens: SizeTokens = SizeTokens(),
    val spacingTokens: SpacingTokens = SpacingTokens(),
    val typographyTokens: TypographyTokens = TypographyTokens(),
)
```

## Properties

| Property            | Type                                                                                  | Description                                             |
| ------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `lightColorTokens`  | [`LightColorTokens`](/docs/sdk/android-checkout/v3.0.0-beta/api/theming/color-tokens)      | Color tokens for light mode                             |
| `darkColorTokens`   | [`DarkColorTokens`](/docs/sdk/android-checkout/v3.0.0-beta/api/theming/color-tokens)       | Color tokens for dark mode. Extends `LightColorTokens`. |
| `borderWidthTokens` | [`BorderWidthTokens`](/docs/sdk/android-checkout/v3.0.0-beta/api/theming/shape-tokens)     | Border widths for inputs, focus rings, dividers         |
| `radiusTokens`      | [`RadiusTokens`](/docs/sdk/android-checkout/v3.0.0-beta/api/theming/shape-tokens)          | Corner radius for cards, inputs, bottom sheets          |
| `sizeTokens`        | [`SizeTokens`](/docs/sdk/android-checkout/v3.0.0-beta/api/theming/shape-tokens)            | Sizes for icons and touch targets                       |
| `spacingTokens`     | [`SpacingTokens`](/docs/sdk/android-checkout/v3.0.0-beta/api/theming/spacing-tokens)       | Padding and margin values                               |
| `typographyTokens`  | [`TypographyTokens`](/docs/sdk/android-checkout/v3.0.0-beta/api/theming/typography-tokens) | Font sizes, weights, and line heights                   |

## Methods

### colorTokens

```kotlin theme={"dark"}
@Composable
fun colorTokens(darkTheme: Boolean = isSystemInDarkTheme()): LightColorTokens
```

Returns `darkColorTokens` when `darkTheme` is `true`, `lightColorTokens` otherwise. Defaults to the system theme.

## Material 3 Integration

`PrimerTheme` automatically maps color tokens to a Material 3 `ColorScheme`. Material components used within the checkout tree (such as `ModalBottomSheet`) inherit your Primer tokens without additional configuration.

Both `PrimerCheckoutSheet` and `PrimerCheckoutHost` wrap content in a `MaterialTheme` that applies this mapping internally.

### Color mapping

| M3 Role                   | Primer Token                                               | Notes                  |
| ------------------------- | ---------------------------------------------------------- | ---------------------- |
| `primary`                 | `primerColorBrand`                                         |                        |
| `onPrimary`               | `primerColorGray000` (light) / `primerColorGray900` (dark) | via `onColoredSurface` |
| `primaryContainer`        | `primerColorBlue900`                                       |                        |
| `onPrimaryContainer`      | `primerColorGray000` (light) / `primerColorGray900` (dark) | via `onColoredSurface` |
| `inversePrimary`          | `primerColorBlue500`                                       |                        |
| `secondary`               | `primerColorGray600`                                       |                        |
| `onSecondary`             | `primerColorGray000` (light) / `primerColorGray900` (dark) | via `onColoredSurface` |
| `secondaryContainer`      | `primerColorGray200`                                       |                        |
| `onSecondaryContainer`    | `primerColorTextPrimary`                                   |                        |
| `tertiary`                | `primerColorBlue500`                                       |                        |
| `onTertiary`              | `primerColorGray000` (light) / `primerColorGray900` (dark) | via `onColoredSurface` |
| `tertiaryContainer`       | `primerColorGray200`                                       |                        |
| `onTertiaryContainer`     | `primerColorTextPrimary`                                   |                        |
| `background`              | `primerColorBackground`                                    |                        |
| `onBackground`            | `primerColorTextPrimary`                                   |                        |
| `surface`                 | `primerColorBackground`                                    |                        |
| `onSurface`               | `primerColorTextPrimary`                                   |                        |
| `surfaceVariant`          | `primerColorGray100`                                       |                        |
| `onSurfaceVariant`        | `primerColorTextSecondary`                                 |                        |
| `surfaceTint`             | `primerColorBrand`                                         |                        |
| `inverseSurface`          | `primerColorGray900`                                       |                        |
| `inverseOnSurface`        | `primerColorGray000`                                       |                        |
| `surfaceBright`           | `primerColorGray000` (light) / `primerColorGray300` (dark) | mode-specific          |
| `surfaceDim`              | `primerColorGray100` (light) / `primerColorGray000` (dark) | mode-specific          |
| `surfaceContainer`        | `primerColorGray100`                                       |                        |
| `surfaceContainerHigh`    | `primerColorGray200`                                       |                        |
| `surfaceContainerHighest` | `primerColorGray300`                                       |                        |
| `surfaceContainerLow`     | `primerColorGray100`                                       |                        |
| `surfaceContainerLowest`  | `primerColorBackground`                                    |                        |
| `error`                   | `primerColorRed500`                                        |                        |
| `onError`                 | `primerColorGray000` (light) / `primerColorGray900` (dark) | via `onColoredSurface` |
| `errorContainer`          | `primerColorRed100`                                        |                        |
| `onErrorContainer`        | `primerColorTextNegative`                                  |                        |
| `outline`                 | `primerColorBorderOutlinedDefault`                         |                        |
| `outlineVariant`          | `primerColorGray300`                                       |                        |
| `scrim`                   | `Color.Black` (alpha 0.32)                                 | hardcoded              |

Overriding a Primer token automatically updates every M3 role that references it. No separate M3 configuration is needed.

## LocalPrimerTheme

```kotlin theme={"dark"}
val LocalPrimerTheme = staticCompositionLocalOf { PrimerTheme() }
```

Compose `CompositionLocal` providing the current `PrimerTheme`. Set automatically by `PrimerCheckoutSheet` and `PrimerCheckoutHost`. Access with `LocalPrimerTheme.current` inside the checkout composable tree.