Theming

The Agentforce Android SDK lets you customize the colors, typography, icons, and on-screen text of every UI component in the full-UI chat experience, so the agent matches your brand.

All theming types live in the package com.salesforce.android.agentforcesdk.components.theme.

The theming system is built on top of the Salesforce design system and provides:

• Color theming — a complete color palette with semantic foundation tokens plus a token for every individual component.
• Typography — set the font family for all text.
• Icon theming — replace built-in icons, with optional separate light and dark variants.
• Display-name theming — override user-visible strings such as titles, hints, and button labels.
• Light and dark mode — automatic switching, or an explicitly forced mode.
• System integration — adapts to the device’s system theme preference.
• Reactive updates — theme values are read through a Compose CompositionLocal, so the UI recomposes when they change.
• Server-driven branding — an org admin can supply a theme centrally that merges underneath whatever you set in code. See Server-driven (org) branding below.

Provide your theme once, through AgentforceConfiguration.Builder.setTheming(...), using the sealed AgentforceTheming type:

1sealed interface AgentforceTheming {
2    data object Default : AgentforceTheming
3    data class Overrides(val overrides: AgentforceThemeOverrides) : AgentforceTheming
4    data class CustomManager(val manager: AgentforceThemeManager) : AgentforceTheming
5}

Colors can be overridden token by token, or built up into a reusable palette.

Use AgentforceThemeOverrides with the AgentforceColorToken enum. List only what you want to change; everything else keeps its default.

1import androidx.compose.ui.graphics.Color
2import com.salesforce.android.agentforcesdk.components.theme.AgentforceColorToken
3import com.salesforce.android.agentforcesdk.components.theme.AgentforceThemeOverrides
4import com.salesforce.android.agentforcesdk.components.theme.AgentforceTheming
5
6val theming = AgentforceTheming.Overrides(
7    AgentforceThemeOverrides(
8        lightColors = mapOf(
9            AgentforceColorToken.Accent1 to Color(0xFF0170CB),
10            AgentforceColorToken.Surface1 to Color(0xFFFFFFFF),
11        ),
12        darkColors = mapOf(
13            AgentforceColorToken.Accent1 to Color(0xFF008AF7),
14            AgentforceColorToken.Surface1 to Color(0xFF1F1F1F),
15        ),
16    )
17)
18
19val configuration = AgentforceConfiguration.builder(authCredentialProvider)
20    .setApplication(application)
21    .setSalesforceDomain("https://your-instance.salesforce.com")
22    .setTheming(theming)
23    .build()

Most component tokens fall back to a foundation token, so overriding a single foundation token (like Accent1) re-skins everything that derives from it. To change just one component, override its specific token — for example AgentforceColorToken.CarouselSurface — without touching Surface1. See the Android Theming Overview for the full list of tokens.

When you want a reusable palette object, start from a default palette and derive a new one. withOverrides(...) never mutates the base.

1import com.salesforce.android.agentforcesdk.components.theme.AgentforceDarkColors
2import com.salesforce.android.agentforcesdk.components.theme.AgentforceLightColors
3import com.salesforce.android.agentforcesdk.components.theme.withOverrides
4
5val myLight = AgentforceLightColors.withOverrides(
6    AgentforceColorToken.Accent1 to Color(0xFFFF8700), // brand orange
7    AgentforceColorToken.CarouselSurface to Color(0xFFFFF5EE),
8)
9
10val myDark = AgentforceDarkColors.withOverrides(
11    AgentforceColorToken.Accent1 to Color(0xFFFF9933),
12)

Start from AgentforceTypography.Default, apply your font family to every text style, and pass it into a custom manager (or an overrides bag).

1import androidx.compose.ui.text.font.FontFamily
2import com.salesforce.android.agentforcesdk.components.theme.AgentforceTypography
3import com.salesforce.android.agentforcesdk.components.theme.createCustomAgentforceThemeManager
4
5val brandFont = FontFamily(/* your Font(...) resources */)
6val typography = AgentforceTypography.Default.copyWithFontFamily(brandFont)
7
8val manager = createCustomAgentforceThemeManager(
9    typography = typography,
10)
11// ...setTheming(AgentforceTheming.CustomManager(manager))

To change individual styles rather than the whole scale, derive from AgentforceTypography.Default and apply mergeWith(...). See the Android Theming Overview for an example.

Replace any built-in icon by mapping an AgentforceIconType to an AgentforceIcon. An icon can be a single painter (used for both themes) or separate light and dark variants.

1import com.salesforce.android.agentforcesdk.components.theme.AgentforceIcon
2import com.salesforce.android.agentforcesdk.components.theme.AgentforceIconType
3
4val overrides = AgentforceThemeOverrides(
5    icons = mapOf(
6        // Same image for light and dark:
7        AgentforceIconType.ActionSend to AgentforceIcon(mySendPainter),
8        // Separate variants:
9        AgentforceIconType.StatusError to AgentforceIcon(light = myErrorLight, dark = myErrorDark),
10    )
11)

Tinting. Many icons are recolored by the SDK using a color token. For those, supply a single-color glyph, or set the icon’s tint token to Color.Unspecified to keep your icon’s original colors. Each AgentforceIconType value documents whether it’s tinted and which token drives the tint.

Override user-visible strings by mapping an AgentforceDisplayNameType to your text. Preserve any format placeholders (%s, %d, %1$s) present in the default string.

1import com.salesforce.android.agentforcesdk.components.theme.AgentforceDisplayNameType
2
3val overrides = AgentforceThemeOverrides(
4    displayNames = mapOf(
5        AgentforceDisplayNameType.ServiceAIAgentName to "Acme Assistant",
6        AgentforceDisplayNameType.InputTextPlaceholder to "Ask me anything…",
7        AgentforceDisplayNameType.PreChatSubmitButton to "Connect with Support",
8    )
9)

Each AgentforceDisplayNameType value documents its default text, the screen it appears on, and its resource ID.

1import com.salesforce.android.agentforcesdk.components.theme.AgentforceThemeMode
2
3val overrides = AgentforceThemeOverrides(
4    themeMode = AgentforceThemeMode.SYSTEM, // or LIGHT / DARK
5)

• SYSTEM — follow the device setting.
• LIGHT / DARK — force a mode regardless of the device setting.

Combine everything in a single overrides bag:

1val overrides = AgentforceThemeOverrides(
2    lightColors = mapOf(AgentforceColorToken.Accent1 to Color(0xFFFF8700)),
3    darkColors = mapOf(AgentforceColorToken.Accent1 to Color(0xFFFF9933)),
4    typography = AgentforceTypography.Default.copyWithFontFamily(brandFont),
5    icons = mapOf(AgentforceIconType.AiAgent to AgentforceIcon(myAvatar)),
6    displayNames = mapOf(AgentforceDisplayNameType.ServiceAIAgentName to "Acme Assistant"),
7    themeMode = AgentforceThemeMode.SYSTEM,
8)
9
10val configuration = AgentforceConfiguration.builder(authCredentialProvider)
11    .setApplication(application)
12    .setSalesforceDomain("https://your-instance.salesforce.com")
13    .setTheming(AgentforceTheming.Overrides(overrides))
14    .build()

Or own the whole theme as a fully resolved manager:

1val manager = createCustomAgentforceThemeManager(
2    lightColors = myLight,
3    darkColors = myDark,
4    typography = typography,
5    themeMode = AgentforceThemeMode.SYSTEM,
6    icons = mapOf(AgentforceIconType.AiAgent to AgentforceIcon(myAvatar)),
7    displayNames = mapOf(AgentforceDisplayNameType.ServiceAIAgentName to "Acme Assistant"),
8)
9// ...setTheming(AgentforceTheming.CustomManager(manager))

Roll out a custom theme gradually by choosing the theming input at runtime:

1val theming = if (customThemeEnabled) {
2    AgentforceTheming.Overrides(myOverrides)
3} else {
4    AgentforceTheming.Default
5}
6
7val configuration = AgentforceConfiguration.builder(authCredentialProvider)
8    .setTheming(theming)
9    .build()

The SDK can also fetch an org-level theme from Salesforce and merge it underneath your app’s own theme, so admins can set brand colors, fonts, icons, and strings centrally without an app update. It’s gated behind the enableRemoteBranding feature flag and composes with everything above — anything your app sets in code always wins.

1import com.salesforce.android.agentforcesdkimpl.utils.AgentforceFeatureFlagSettings
2
3val flags = AgentforceFeatureFlagSettings.builder()
4    .setupFlags(mapOf("enableRemoteBranding" to true))
5    .build()
6
7val configuration = AgentforceConfiguration.builder(authCredentialProvider)
8    .setFeatureFlagSettings(flags)
9    .setTheming(AgentforceTheming.Overrides(myOverrides)) // still applied on top of branding
10    .build()

Your app never parses or constructs the branding payload — the SDK fetches, validates, and merges it entirely on its own. Use AgentforceTheming.Overrides if you want an org’s colors or font to reach your app: a fully resolved CustomManager carries no “unset” signal for branding to layer beneath.

See Server-Driven Branding for the fetch flow, exactly what an org can supply, precedence rules, and payload validation.

If you render custom components inside the chat and want them to match the theme, read the active values from the CompositionLocal:

1val theme = LocalAgentforceTheme.current
2val colors = theme.colors()
3val typography = theme.typography()
4
5Text(
6    text = "Hello",
7    style = typography.bodyFontScale1Regular.copy(color = colors.onSurface1),
8)

1. Prefer AgentforceThemeOverrides. Override only what you need and let the SDK supply the rest.
2. Use foundation tokens for broad changes, component tokens for surgical ones. Change Accent1 to re-skin everything accent-colored; change CarouselSurface to affect only the carousel.
3. Always use the AgentforceColorToken enum rather than raw strings — typos become compile errors.
4. Set both light and dark. Provide lightColors and darkColors so your theme looks right in both modes; test with AgentforceThemeMode.SYSTEM.
5. Check contrast. Ensure sufficient contrast for accessibility (WCAG AA) in both modes.
6. Preserve string placeholders (%s, %d, %1$s) when overriding display names.
7. For tinted icons, supply single-color glyphs, or set the tint token to Color.Unspecified.

When branding is saved for an Embedded Service configuration — for example, through the Mobile Publisher Branding Setup UI described above — the SDK creates a BrandingSet metadata record named:

AFM_ESC_<EmbeddedServiceConfigDeveloperName>

For example, an Embedded Service configuration with the developer name MyMessagingConfig creates the BrandingSet AFM_ESC_MyMessagingConfig.

BrandingSet doesn’t have a parent metadata entity, so it can’t be included in a change set. To promote this branding from a sandbox to production, use Salesforce DevOps Center instead:

1. Create or open a DevOps Center work item for the Embedded Service configuration.
2. On the work item’s Changes tab, select Add Components Manually.
3. Select the BrandingSet metadata type and add the BrandingSet named AFM_ESC_<EmbeddedServiceConfigDeveloperName>.
4. Commit the work item to source control, complete any required review, and promote it through the configured pipeline to production.
5. Validate the branding in the target org after deployment.

When the Embedded Service configuration itself changes, include both the configuration and its associated BrandingSet in the same work item.

This limitation and workaround apply the same way regardless of mobile platform — the BrandingSet metadata is created server-side, independent of whether your app uses the Android, iOS, or React Native SDK.

For more information, see Salesforce’s DevOps Center documentation on manually adding metadata components, committing work-item changes, and promoting work items through a pipeline.

• Android Theming Overview: See Android Theming Overview for the full reference index, including the Color Token Reference, AgentforceColors, and AgentforceTypography pages.
• UI Components: See Android UI Components for component theming.
• Configuration: See AgentforceConfiguration for setup.

j

Integrate Agentforce with Your Mobile App

Overview

Before You Begin

iOS Quick Start

Android Quick Start

React Native Quick Start

iOS Integration Guide

Android Integration Guide

Requirements

Install the SDK

Integrate Agentforce SDK

Use Full UI

Build a Headless Experience

Set Up Agentforce Voice

Theming

React Native Integration Guide

Message Response Formatting

Custom Lightning Types on Mobile

Release Notes