--- schema_version: "1" id: ebc4c9a47c84c074cdd809babe4a2ae7824dc608befa4b345a2cd485ddb8f71e title: Theming collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/genai/agentforce-mobile-sdk/guides/android/agentforce-mobile-sdk-android-branding-theming.md canonical_url: https://developer.salesforce.com/docs/ai/agentforce-mobile-sdk/guide/agentforce-mobile-sdk-android-branding-theming.html source_site: developer.salesforce.com content_type: documentation content_hash: ccb8b2c0efaabd9287474f8a497ed38afdf79bdddf3f8aa29d17b12c5d88ddeb products: - Agentforce Mobile SDK - Agentforce and Einstein Generative AI --- # 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. ## Mobile Publisher Branding **note:** If you're using **Agentforce Mobile Publisher**, you can configure branding through the Setup UI without writing code. The metadata-driven branding configuration supports colors, typography, icons, and display names with a live preview. This Setup UI is available starting with the Winter '27 (264) release. To configure branding via Setup: 1. In Setup, search for **Agentforce Mobile Branding** 2. Select your branding scope and preview type 3. Customize colors, typography, icons, and display names 4. Click the preview (clickable) to see your changes in real-time Changes made in Setup are applied automatically without requiring an app redeployment—only server metadata updates are needed. For programmatic customization in SDK implementations, continue reading the sections below. **note:** This branding configuration applies to the Agentforce Mobile SDK and Agentforce Mobile Publisher. It doesn't apply to the standalone Enhanced Chat (MIAW) SDK. ## Theme System All theming types live in the package `com.salesforce.android.agentforcesdk.components.theme`. ## Overview 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](#server-driven-org-branding) below. ### What you can customize | Capability | Type(s) | | ------------------------------------------------ | ------------------------------------------------ | | Colors (foundation + per-component) | `AgentforceColorPalette`, `AgentforceColorToken` | | Font family | `AgentforceTypography.copyWithFontFamily(...)` | | Per-style typography (weight, size, line height) | `Typography.mergeWith(...)` | | Icons | `AgentforceIconType`, `AgentforceIcon` | | Display-name strings | `AgentforceDisplayNameType` | | Theme mode (light, dark, system) | `AgentforceThemeMode` | ## Key components | Component | Purpose | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `AgentforceThemeManager` | Central theme interface. Exposes `colors()`, `typography()`, `getIcon(...)`, `getDisplayName(...)`, and `getThemeMode()`. | | `AgentforceColorPalette` | Immutable color palette. Holds foundation tokens (`surface1`, `accent1`, and so on) and per-component tokens (`titleBarBackground`, and so on). | | `AgentforceLightColors` / `AgentforceDarkColors` | The default palettes for light and dark mode. Start from these when customizing colors. | | `AgentforceColorToken` | Type-safe enum of every color token. Use it with `withOverrides(...)` for compile-time safety. | | `withOverrides(...)` | Extension that returns a new palette with the given tokens replaced. The base palette is never mutated. | | `createDefaultAgentforceThemeManager()` | Builds the out-of-the-box theme manager. | | `createCustomAgentforceThemeManager(...)` | Builds a manager with any subset of overrides (colors, typography, theme mode, icons, display names). | | `AgentforceTheming` | Sealed type you pass to `setTheming(...)`: `Default`, `Overrides`, or `CustomManager`. | | `AgentforceThemeOverrides` | A sparse bag of just the tokens you want to change. The recommended way to theme. | | `AgentforceThemeMode` | `SYSTEM`, `LIGHT`, or `DARK`. | | `AgentforceIconType` / `AgentforceIcon` | Enumerates customizable icons and carries the replacement painter(s). | | `AgentforceDisplayNameType` | Enumerates customizable user-visible strings. | | `LocalAgentforceTheme` | Compose `CompositionLocal` used to read the active theme. | ## Supplying a theme Provide your theme once, through `AgentforceConfiguration.Builder.setTheming(...)`, using the sealed `AgentforceTheming` type: ```kotlin sealed interface AgentforceTheming { data object Default : AgentforceTheming data class Overrides(val overrides: AgentforceThemeOverrides) : AgentforceTheming data class CustomManager(val manager: AgentforceThemeManager) : AgentforceTheming } ``` | Option | When to use | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `AgentforceTheming.Overrides` (recommended) | Tweak specific tokens and let everything else follow the SDK defaults. Any token you leave out keeps its default. | | `AgentforceTheming.CustomManager` | Own the entire theme end-to-end with a fully resolved manager. | | `AgentforceTheming.Default` | No in-code theme — the SDK default theme is used. | ## Customize colors Colors can be overridden token by token, or built up into a reusable palette. ### Override specific tokens (recommended) Use `AgentforceThemeOverrides` with the `AgentforceColorToken` enum. List only what you want to change; everything else keeps its default. ```kotlin import androidx.compose.ui.graphics.Color import com.salesforce.android.agentforcesdk.components.theme.AgentforceColorToken import com.salesforce.android.agentforcesdk.components.theme.AgentforceThemeOverrides import com.salesforce.android.agentforcesdk.components.theme.AgentforceTheming val theming = AgentforceTheming.Overrides( AgentforceThemeOverrides( lightColors = mapOf( AgentforceColorToken.Accent1 to Color(0xFF0170CB), AgentforceColorToken.Surface1 to Color(0xFFFFFFFF), ), darkColors = mapOf( AgentforceColorToken.Accent1 to Color(0xFF008AF7), AgentforceColorToken.Surface1 to Color(0xFF1F1F1F), ), ) ) val configuration = AgentforceConfiguration.builder(authCredentialProvider) .setApplication(application) .setSalesforceDomain("https://your-instance.salesforce.com") .setTheming(theming) .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](/docs/ai/agentforce-mobile-sdk/references/agentforce-mobile-sdk/theming-overview-android.html) for the full list of tokens. ### Build a full palette with `withOverrides(...)` When you want a reusable palette object, start from a default palette and derive a new one. `withOverrides(...)` never mutates the base. ```kotlin import com.salesforce.android.agentforcesdk.components.theme.AgentforceDarkColors import com.salesforce.android.agentforcesdk.components.theme.AgentforceLightColors import com.salesforce.android.agentforcesdk.components.theme.withOverrides val myLight = AgentforceLightColors.withOverrides( AgentforceColorToken.Accent1 to Color(0xFFFF8700), // brand orange AgentforceColorToken.CarouselSurface to Color(0xFFFFF5EE), ) val myDark = AgentforceDarkColors.withOverrides( AgentforceColorToken.Accent1 to Color(0xFFFF9933), ) ``` ## Customize typography (font family) Start from `AgentforceTypography.Default`, apply your font family to every text style, and pass it into a custom manager (or an overrides bag). ```kotlin import androidx.compose.ui.text.font.FontFamily import com.salesforce.android.agentforcesdk.components.theme.AgentforceTypography import com.salesforce.android.agentforcesdk.components.theme.createCustomAgentforceThemeManager val brandFont = FontFamily(/* your Font(...) resources */) val typography = AgentforceTypography.Default.copyWithFontFamily(brandFont) val manager = createCustomAgentforceThemeManager( typography = typography, ) // ...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](/docs/ai/agentforce-mobile-sdk/references/agentforce-mobile-sdk/theming-overview-android.html) for an example. ## Customize icons 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. ```kotlin import com.salesforce.android.agentforcesdk.components.theme.AgentforceIcon import com.salesforce.android.agentforcesdk.components.theme.AgentforceIconType val overrides = AgentforceThemeOverrides( icons = mapOf( // Same image for light and dark: AgentforceIconType.ActionSend to AgentforceIcon(mySendPainter), // Separate variants: AgentforceIconType.StatusError to AgentforceIcon(light = myErrorLight, dark = myErrorDark), ) ) ``` **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. ## Customize display names (strings) Override user-visible strings by mapping an `AgentforceDisplayNameType` to your text. Preserve any format placeholders (`%s`, `%d`, `%1$s`) present in the default string. ```kotlin import com.salesforce.android.agentforcesdk.components.theme.AgentforceDisplayNameType val overrides = AgentforceThemeOverrides( displayNames = mapOf( AgentforceDisplayNameType.ServiceAIAgentName to "Acme Assistant", AgentforceDisplayNameType.InputTextPlaceholder to "Ask me anything…", AgentforceDisplayNameType.PreChatSubmitButton to "Connect with Support", ) ) ``` Each `AgentforceDisplayNameType` value documents its default text, the screen it appears on, and its resource ID. ## Theme mode (light, dark, system) ```kotlin import com.salesforce.android.agentforcesdk.components.theme.AgentforceThemeMode val overrides = AgentforceThemeOverrides( themeMode = AgentforceThemeMode.SYSTEM, // or LIGHT / DARK ) ``` - `SYSTEM` — follow the device setting. - `LIGHT` / `DARK` — force a mode regardless of the device setting. ## Complete customization Combine everything in a single overrides bag: ```kotlin val overrides = AgentforceThemeOverrides( lightColors = mapOf(AgentforceColorToken.Accent1 to Color(0xFFFF8700)), darkColors = mapOf(AgentforceColorToken.Accent1 to Color(0xFFFF9933)), typography = AgentforceTypography.Default.copyWithFontFamily(brandFont), icons = mapOf(AgentforceIconType.AiAgent to AgentforceIcon(myAvatar)), displayNames = mapOf(AgentforceDisplayNameType.ServiceAIAgentName to "Acme Assistant"), themeMode = AgentforceThemeMode.SYSTEM, ) val configuration = AgentforceConfiguration.builder(authCredentialProvider) .setApplication(application) .setSalesforceDomain("https://your-instance.salesforce.com") .setTheming(AgentforceTheming.Overrides(overrides)) .build() ``` Or own the whole theme as a fully resolved manager: ```kotlin val manager = createCustomAgentforceThemeManager( lightColors = myLight, darkColors = myDark, typography = typography, themeMode = AgentforceThemeMode.SYSTEM, icons = mapOf(AgentforceIconType.AiAgent to AgentforceIcon(myAvatar)), displayNames = mapOf(AgentforceDisplayNameType.ServiceAIAgentName to "Acme Assistant"), ) // ...setTheming(AgentforceTheming.CustomManager(manager)) ``` ## Feature-flag-based theming Roll out a custom theme gradually by choosing the theming input at runtime: ```kotlin val theming = if (customThemeEnabled) { AgentforceTheming.Overrides(myOverrides) } else { AgentforceTheming.Default } val configuration = AgentforceConfiguration.builder(authCredentialProvider) .setTheming(theming) .build() ``` ## Server-driven (org) branding 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. ```kotlin import com.salesforce.android.agentforcesdkimpl.utils.AgentforceFeatureFlagSettings val flags = AgentforceFeatureFlagSettings.builder() .setupFlags(mapOf("enableRemoteBranding" to true)) .build() val configuration = AgentforceConfiguration.builder(authCredentialProvider) .setFeatureFlagSettings(flags) .setTheming(AgentforceTheming.Overrides(myOverrides)) // still applied on top of branding .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](/docs/ai/agentforce-mobile-sdk/references/agentforce-mobile-sdk/theming-overview-android.html#reference-pages) for the fetch flow, exactly what an org can supply, precedence rules, and payload validation. ## Reading theme values in your own components If you render custom components inside the chat and want them to match the theme, read the active values from the `CompositionLocal`: ```kotlin val theme = LocalAgentforceTheme.current val colors = theme.colors() val typography = theme.typography() Text( text = "Hello", style = typography.bodyFontScale1Regular.copy(color = colors.onSurface1), ) ``` ## Best practices 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`. ## Promoting Embedded Service Branding with DevOps Center 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_` 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_`. 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](https://help.salesforce.com/s/articleView?id=platform.devops_center_work_item_add_metadata.htm&language=en_US&type=5), [committing work-item changes](https://help.salesforce.com/s/articleView?id=platform.devops_center_work_item_commit_changes.htm&language=en_US&type=5), and [promoting work items through a pipeline](https://help.salesforce.com/s/articleView?id=platform.devops_center_promotion_options.htm&language=en_US&type=5). ## Next steps - **Android Theming Overview**: See [Android Theming Overview](/docs/ai/agentforce-mobile-sdk/references/agentforce-mobile-sdk/theming-overview-android.html) for the full reference index, including the Color Token Reference, AgentforceColors, and AgentforceTypography pages. - **UI Components**: See [Android UI Components](/docs/ai/agentforce-mobile-sdk/references/agentforce-mobile-sdk/ui-components-android.html) for component theming. - **Configuration**: See [AgentforceConfiguration](/docs/ai/agentforce-mobile-sdk/references/agentforce-mobile-sdk/configuration-overview-android.html) for setup.