Customize Colors for iOS
The UI SDK automatically brands the app with a default color scheme. You can customize this color scheme in your app by creating color sets in your Assets catalog using the SDK's token names.
This article applies to the following implementations:
| UI SDK | Core SDK |
|---|---|
| ✅ |
Test any color customizations in light and dark mode.
You can customize colors using generic branding tokens such as “primary color” or “secondary color.” Or you can customize each individual element in the UI using detailed branding tokens such as “sent bubble background color.”
The generic tokens are better if you want to update the colors across the entire app with just a few changes. The detailed tokens are better if you want full control over the colors for each UI element. When you modify the detailed tokens, it overrides the generic branding token colors for the specific elements that you modify.
Use these tokens to adjust the colors of the app to match your product's brand.
| Keyword | Default Light Color | Default Dark Color | Description |
|---|---|---|---|
| SMI.primary | #FAFAF9  | #2B2B26  | Primary branding color |
| SMI.primaryVariant | #706E6B  | #2B2826  | Variant of the primary color |
| SMI.onPrimary | #2B2B26 | #ECEBEA  | Primary text color |
| SMI.secondary | #0070D2  | #007ADD  | Secondary branding color |
| SMI.onSecondary | #FFFFFF  | #FFFFFF | Secondary text color |
| SMI.secondaryActive | #014485  | #16325C  | Secondary color for active elements |
| SMI.secondaryHighlight | #062680  | #6EC4FA  | Secondary color for highlighted elements |
| SMI.onSecondaryVariant | #DDDBDA  | #1A1B1E  | Alternate secondary text color |
| SMI.background | #F3F2F2  | #080707  | Background color |
| SMI.onBackground | #706E6B | #B0ADAB  | Color for elements on the background color |
| SMI.surface | #FFFFFF | #1A1B1E | Primary color for surfaces |
| SMI.onSurface | #2B2826 | #C9C7C5  | Text color on surfaces |
| SMI.surfaceHighlight | #B3B3B3  | #66676B  | Highlight color for surfaces |
| SMI.surfaceVariant | #DDDBDA | #30373D  | Variant color for surfaces |
| SMI.onSurfaceVariant | #0070D2 | #FFFFFF | Variant color for surfaces |
| SMI.surfaceSecondary | #CED0D2  | #30373D | Secondary color for surfaces |
| SMI.tertiary | #000000  | #000000 | Tertiary branding color |
| SMI.highlight | #FCC003  | #FCC003 | Highlight color |
| SMI.error | #A61A14  | #D4504C  | Error feedback color |
| SMI.warning | #FFB75D  | #FFB75D | Warning feedback color |
| SMI.success | #04844B  | #4BCA81  | Success feedback color |
| SMI.transparent | (alpha #00) #00FFFF | (alpha #00) #00FFFF | Transparent color |
| SMI.backgroundTransparent | (alpha #80) #F3F2F2 | (alpha #80) #080707 | Transparent background color |
| SMI.surfaceTransparent | (alpha #80) #FFFFFF | (alpha #80) #1A1B1E | Transparent surface color |
| SMI.onSecondaryTransparent | (alpha #80) #FFFFFF | (alpha #80) #FFFFFF | Transparent secondary color |
| SMI.onSecondarySemiTransparent | (alpha #99) #FFFFFF | (alpha #99) #FFFFFF | Transparent color on secondary |
| SMI.onBackgroundSemiTransparent | (alpha: #80) #706E6B | (alpha: #80) #B0ADAB | Semi-transparent color for elements on the background color |
Use these tokens if you want to configure specific elements of the app. When you change any of these detailed branding token values, it overrides the generic token used by that element.
| Detailed Token | Generic Token | Description |
|---|---|---|
| HEADER/GENERAL COLORS | ||
| SMI.navigationBackground | primary | Navigation background color |
| SMI.navigationText | onPrimary | Navigation text color |
| SMI.navigationIcon | onPrimary | Navigation icon color |
| SMI.chatBackground | background | Chat window background color |
| SMI.ctaButtons | secondary | Call-to-action button color |
| SMI.ctaButtonsText | secondary | Call-to-action text color |
| SMI.bannerBackground | onBackground | Banner background color |
| SMI.bannerText | background | Banner text color |
| SMI.imageViewerBackground | tertiary | Image viewer background color |
| PRE-CHAT COLORS | ||
| SMI.prechatBackground | background | Pre-chat window background color |
| SMI.prechatBorder | onPrimary | Border color for text input field in pre-chat |
| SMI.prechatText | onPrimary | Text color on pre-chat form |
| SMI.prechatTextActive | secondary | Color for the active pre-chat cell |
| SMI.prechatButton | secondary | Pre-chat button color |
| SMI.prechatButtonActive | secondaryActive | Pre-chat active button color |
| SMI.prechatButtonText | onSecondary | Pre-chat button text color |
| SMI.prechatInputBackground | surface | Pre-chat window background color |
| SMI.prechatError | error | Pre-chat error feedback color |
| SMI.prechatDisabled | surfaceSecondary | Disabled pre-chat field |
| INPUT COLORS | ||
| SMI.inputBackground | surface | Background color for text input field |
| SMI.inputBorder | surfaceVariant | Border color for text input field |
| SMI.inputText | onSurface | Text font color when typing a message |
| SMI.inputPlaceholder | onBackground | Placeholder text color for the input text field |
| BUBBLE/CHAT COLORS | ||
| SMI.sentBubbleText | onSecondary | Text color for an outgoing message bubble |
| SMI.sentBubbleBackground | secondary | Background color for an outgoing chat bubble |
| SMI.receivedBubbleText | onSurface | Text color for an incoming message bubble |
| SMI.receivedBubbleBackground | surface | Background color for an incoming chat bubble |
| SMI.receivedBubbleBorder | surfaceVariant | Border color for incoming chat bubble |
| SMI.typingIndicatorText | onBackground | Typing indicator color |
| SMI.timestamp | onBackground | Timestamp text color |
| SMI.avatarBackground | secondary | Avatar background color |
| SMI.avatarForeground | onSecondary | Avatar foreground color |
| SMI.chatSeperator | onBackgroundSemiTransparent | Chat separator color |
| CARD COLORS | ||
| SMI.cardBackground | primary | Background color for a card |
| SMI.cardBorder | primaryVariant | Border color for a card |
| SMI.cardHeadlineText | onPrimary | Headline text for a card |
| SMI.cardSubheaderText | primaryVariant | Subheader text for a card |
| ICON COLORS | ||
| SMI.iconForeground | onSecondary | Icon foreground color |
| SMI.iconBackground | secondary | Icon background color |
| SMI.iconBackgroundSecondary | onBackground | Icon secondary background color |
| SMI.iconDisabled | onBackground | Icon disabled color |
| BUTTON COLORS | ||
| SMI.buttonText | onSurfaceVariant | Button text color |
| SMI.buttonBackground | surface | Button background color |
| SMI.buttonBorder | surfaceVariant | Button border color |
| SMI.buttonFocusText | surface | Focus text color |
| SMI.buttonFocusBackground | onSurfaceVariant | Focus text background color |
| SMI.buttonDisabledText | onBackground | Disabled text color |
| SMI.buttonDisabledBackground | onSurfaceVariant | Disabled text background color |
| SMI.listPickerTitleText | onSurface | List picker title text color |
| SMI.cancelButtonActive | onSecondary | Cancel button active color |
| SMI.cancelButtonBgActive | onBackground | Cancel button active background color |
| SMI.cancelButtonPressed | onSecondary | Cancel button pressed color |
| SMI.cancelButtonBgPressed | secondaryActive | Cancel button pressed background color |
| MESSAGE SEARCH COLORS | ||
| SMI.messageSearchInputBar | onBackgroundSemiTransparent | Search input bar color |
| SMI.messageSearchHighlightBorderAgent | highlight | Highlighted border color for agent |
| SMI.messageSearchHighlightBorderUser | highlight | Highlighted border color for user |
| SMI.messageSearchHighlightTextAgent | primary | Highlighted text color for agent |
| SMI.messageSearchHighlightTextUser | primary | Highlighted text color for user |
| SMI.messageSearchHighlightBackgroundAgent | surfaceHighlight | Higlighted background color for agent |
| SMI.messageSearchHighlightBackgroundUser | secondaryHighlight | Higlighted background color for user |
| CAMERA COLORS | ||
| SMI.cameraButtonActive | onSecondary | Camera button active color |
| SMI.cameraButtonBgActive | onSecondaryTransparent | Camera button active background color |
| SMI.cameraButtonFocused | secondary | Camera button focused color |
| SMI.cameraButtonBgFocused | onSecondarySemiTransparent | Camera button focused background color |
| SMI.cameraButtonPressed | onSecondary | Camera button pressed color |
| SMI.cameraButtonBgPressed | onSecondary | Camera button pressed background color |
| LOADING SCREEN COLORS | ||
| SMI.loadingScreenTextPlaceholder | surfaceSecondary | Loading screen placeholder text color |
| SMI.loadingScreenSentBubbleBackground | surfaceSecondary | Loading screen sent bubble background color |
| SMI.loadingScreenReceivedBubbleBackground | onBackground | Loading screen received bubble background color |
| SMI.loadingScreenAvatar | onBackground | Loading screen avatar color |
| SMI.loadingScreenBackground | background | Loading screen background color |
| SMI.loadingScreenInputTextPlaceholder | surfaceSecondary | Loading screen input text placeholder color |