Skip to main content
Version: 5.9.0

Glossary

Definitions of key design system terms.

Core concepts​

Token​

An atomic value of the design system — a color, font, or icon. Defined once and used across the SDK as the default value.

Token classes: ChatColors, ChatTypography, ChatImages

// Color token
let colors = ChatColors()
colors.link = .systemBlue  // applied everywhere "link" is used

Component​

A ready-made SDK widget with a configurable appearance: button, input field, navigation bar, and so on. Components use tokens as default values but allow targeted overrides.

Container class: ChatComponents

let components = ChatComponents()
// Override the navigation title style — without affecting colors globally
components.navigationBarStyle.titleTextStyle.color = .white

Flow​

A set of styles bound to a specific SDK screen. Lets you override any component on a single screen only, without affecting the others.

Classes: ChatFlow (chat screen), SearchFlow (search screen)

// Change the button color only on the search screen
theme.flows.searchFlow.navigationBarStyle.titleTextStyle.color = .black
// On the chat screen the color remains unchanged

Theme (ChatTheme)​

A top-level container that combines tokens, components, and flows. Passed to the SDK to be applied.

// Full signature: ChatTheme(colors:images:typography:), all parameters have defaults
let theme = ChatTheme(colors: colors, images: images, typography: typography)
chatCenterSDK.theme = theme
chatCenterSDK.darkTheme = darkTheme // separate theme for dark mode

Style​

An object that defines the appearance of a specific UI element. For example, NavigationBarStyle, ChatInputStyle, TextChatMessageStyle.

Styles inside ChatComponents are initialized lazily — their values are fixed on first access, from the current tokens. Styles inside ChatFlow are initialized the same way, except for inputViewStyle, addFileMenuStyle, loadingChatStyle, chatPlaceholderStyle, and errorPlaceholderStyle — these are created immediately in the constructor.

For the full list, see Styles.

ChatTextStyle​

The base text display style — contains only a font and a color. Used in all text elements: navigation titles, message text, time labels, and so on.

// ChatTextStyle properties:
components.navigationBarStyle.titleTextStyle.font = .systemFont(ofSize: 18, weight: .bold)
components.navigationBarStyle.titleTextStyle.color = .white

// Constructor:
let titleStyle = ChatTextStyle(font: .systemFont(ofSize: 18, weight: .bold),
                                color: .white)

ChatImage​

A wrapper around UIImage. Supports SF Symbols, images from a bundle, and prebuilt UIImage instances.

ChatImage(system: "paperplane.fill", tintColor: .white)
ChatImage(system: "paperplane.fill", size: 22, tintColor: .white)
ChatImage(named: "icon_send", bundle: .main)   // app resource; for SDK resources the bundle parameter can be omitted
ChatImage(image: myUIImage)

Appearance​

The display mode of the system UI: light or dark. The SDK selects a theme based on the current mode:

  • chatCenterSDK.theme — used in light mode;
  • chatCenterSDK.darkTheme — used in dark mode (if set; otherwise the SDK uses theme).

Dynamic Color​

A UIColor that selects its value based on the current appearance. Useful when you want a single ChatColors object for both light and dark themes — instead of separate theme and darkTheme.

colors.main = UIColor { $0.userInterfaceStyle == .dark ? .white : .black }

PostScript Name​

The exact internal font name accepted by UIFont(name:size:). Differs from the file name and the display name:

FileFamilyPostScript Name
Roboto-Regular.ttfRobotoRoboto-Regular

Design system hierarchy​

ChatTheme
├── colors:       ChatColors
├── images:       ChatImages
├── typography:   ChatTypography
├── components:   ChatComponents
│   ├── navigationBarStyle: NavigationBarStyle
│   ├── inputViewStyle:     ChatInputStyle
│   ├── audioPlayerStyle:   AudioPlayerStyle
│   └── ...
└── flows:        ChatFlows
    ├── chatFlow:   ChatFlow
    └── searchFlow: SearchFlow

For the full list of ChatComponents and ChatFlow fields, see Styles and the API Reference.

Override priority (from lowest to highest):

Token → Component → Flow

When the same property is set at multiple levels, the value from Flow wins.

Lazy initialization

ChatComponents styles are initialized lazily — on first access they capture the current token values (ChatColors, ChatTypography, ChatImages). If you change a token after a style has already been read (for example, after the chat has been opened), the new values will not affect it — recreate ChatTheme and reassign it to chatCenterSDK.theme / darkTheme.

Mapping table​

TaskWhat to changeLevel
Color everywhere in the SDKChatColorsToken
Font everywhere in the SDKChatTypographyToken
Icon everywhere in the SDKChatImagesToken
A button / panel everywhereChatComponents.*StyleComponent
An element only in chattheme.flows.chatFlow.*Flow
An element only in searchtheme.flows.searchFlow.*Flow

Frequently confused​

ChatMessageStyle vs ChatMessagesStyles​

  • ChatMessageStyle (no trailing s) — the base style of a single message: time, status, insets, error icons.
  • ChatMessagesStyles (with s) — a container for all message types (textMessageStyle, imageMessageStyle, etc.), plus avatar, bubble, and mask.

chatFlow.outcomeMessages vs chatFlow.incomeMessages​

  • outcomeMessages — outgoing messages (from the user / client).
  • incomeMessages — incoming messages (from the operator / agent).
Automatic bubble mask flipping

On assignment to incomeMessages, the SDK automatically mirrors bubbleMaskImage — unless you have explicitly overridden it. That way a single mask can be used for both directions. For a custom mask, set bubbleMaskImage before assigning it to incomeMessages: after assignment the flip can no longer be reverted.

typography.title vs navigationBarStyle.titleTextStyle​

  • typography.title — a global font token, used as the default value.
  • navigationBarStyle.titleTextStyle — a specific property of the navigation bar. If set explicitly, it overrides the typography.title token for navigation only.

A concrete example: navigation bar title color​

You can achieve the same effect at any of the three levels — choose the level based on the scope of the change.

// Token — affects the entire SDK until a component overrides it explicitly
typography.title = .systemFont(ofSize: 18, weight: .bold)

// Component — affects navigation on all screens
components.navigationBarStyle.titleTextStyle.font = .systemFont(ofSize: 18, weight: .bold)
components.navigationBarStyle.titleTextStyle.color = .white

// Flow — affects the search screen only
theme.flows.searchFlow.navigationBarStyle.titleTextStyle.color = .black

On conflict, the value from Flow wins, then from Component, then from Token.

Last updated on