Customize the Theme

This guide shows how to adjust the color palette of the SDK screens to your brand, without replacing the UI. This is the minimum level of customization (see Customization model).

How it works

You set colors on the Builder with customizeColors, assigning a color to each semantic area of the UI. Areas you do not set keep the SDK default. Colors use the 0xAARRGGBB format.

Set colors

ApoloSdk.Builder(applicationContext)
    // ...
    .customizeColors {
        setColor(ColorArea.FinalizeButton, Color(0xFF0066CC))
        setColor(ColorArea.Background, Color(0xFFF0F0F0))
    }
    .build()

To keep a palette organized and reusable, define an extension on CustomizationScope and call it inside customizeColors:

ApoloSdk.Builder(context)
    // ...
    .customizeColors { applyPalette() }
    .build()

fun CustomizationScope.applyPalette() {
    setColor(ColorArea.Background, Color(0xFFFFF7DB))
    setColor(ColorArea.Surface, Color(0xFFFFFFFF))
    setColor(ColorArea.OnBackground, Color(0xFF1A1A1A))
    setColor(ColorArea.OnSurface, Color(0xFF1A1A1A))
    setColor(ColorArea.FinalizeButton, Color(0xFF1565C0))
    setColor(ColorArea.AnimationPrimary, Color(0xFF1565C0))
    setColor(ColorArea.AnimationSecondary, Color(0xFFFFCB33))
    setColor(ColorArea.AnimationBackground, Color(0xFFCFE3FF))
}

Color areas

Area	Applies to
`Background`	Screen background (Scaffold container).
`Surface`	White surfaces — cards, tickets, bottom bars, headers.
`OnBackground`	Primary text and icons over `Background`.
`OnSurface`	Primary text and icons over `Surface`.
`FinalizeButton`	Highlight color of finalize buttons on the final screens.
`ErrorContainer`	Background of error screens.
`WarningContainer`	Background of warning screens.
`SuccessContainer`	Background of success screens.
`AnimationPrimary`	Primary stroke/fill of the animations.
`AnimationSecondary`	Secondary tone of the animations (shadows, depth).
`AnimationBackground`	Background of the animations.

Best practices

Override only the areas you need — broad changes hurt consistency and can break contrast and accessibility.
Check the success, error, and warning screens visually — together they shape the final perception of the flow.
Avoid colors reserved for error or success states in neutral areas (for example, red on Background) — users associate those colors with specific states.

Next steps

Insert screens with Slots — add a screen between two steps.
Override SDK screens — replace a screen’s appearance.