Глоссарий

Определения ключевых терминов дизайн-системы.

---

Основные понятия

Токен (Token)

Атомарное значение дизайн-системы — цвет, шрифт или иконка. Задаётся один раз и используется во всём SDK как значение по умолчанию.

Классы-токены: ChatColors, ChatTypography, ChatImages

// Токен цвета
let colors = ChatColors()
colors.link = .systemBlue  // применяется везде, где используется "link"

---

Компонент (Component)

Готовый виджет SDK с настраиваемым внешним видом: кнопка, поле ввода, навигационная панель и т.д. Компоненты используют токены как значения по умолчанию, но допускают точечные переопределения.

Класс-контейнер: ChatComponents

let components = ChatComponents()
// Переопределяем стиль заголовка навигации — не затрагивая цвета глобально
components.navigationBarStyle.titleTextStyle.color = .white

---

Сценарий / Flow

Набор стилей, привязанный к конкретному экрану SDK. Позволяет переопределить любой компонент только на одном экране, не затрагивая остальные.

Классы: ChatFlow (экран чата), SearchFlow (экран поиска)

// Изменяем цвет кнопки только в экране поиска
theme.flows.searchFlow.navigationBarStyle.titleTextStyle.color = .black
// В экране чата цвет остаётся прежним

---

Тема (ChatTheme)

Контейнер верхнего уровня, объединяющий токены, компоненты и сценарии. Передаётся в SDK для применения.

// Полная сигнатура: ChatTheme(colors:images:typography:), все параметры с дефолтами
let theme = ChatTheme(colors: colors, images: images, typography: typography)
chatCenterSDK.theme = theme
chatCenterSDK.darkTheme = darkTheme // отдельная тема для тёмного режима

---

Стиль (Style)

Объект, задающий внешний вид конкретного элемента UI. Например, NavigationBarStyle, ChatInputStyle, TextChatMessageStyle.

Стили внутри ChatComponents инициализируются лениво — их значения фиксируются при первом обращении, из текущих токенов. Стили внутри ChatFlow инициализируются по тому же принципу, кроме inputViewStyle, addFileMenuStyle, loadingChatStyle, chatPlaceholderStyle и errorPlaceholderStyle — они создаются сразу в конструкторе.

Полный список — см. Стили.

---

ChatTextStyle

Базовый стиль отображения текста — содержит только шрифт и цвет. Используется во всех текстовых элементах: заголовках навигации, тексте сообщений, метках времени и т. д.

// Поля ChatTextStyle:
components.navigationBarStyle.titleTextStyle.font = .systemFont(ofSize: 18, weight: .bold)
components.navigationBarStyle.titleTextStyle.color = .white

// Конструктор:
let titleStyle = ChatTextStyle(font: .systemFont(ofSize: 18, weight: .bold),
                                color: .white)

---

ChatImage

Обёртка над UIImage. Поддерживает SF Symbols, изображения из бандла и готовые UIImage.

ChatImage(system: "paperplane.fill", tintColor: .white)
ChatImage(system: "paperplane.fill", size: 22, tintColor: .white)
ChatImage(named: "icon_send", bundle: .main)   // ресурс приложения; для ресурсов SDK параметр bundle можно опустить
ChatImage(image: myUIImage)

---

Appearance (Внешний вид)

Режим отображения системного UI: светлый или тёмный. SDK выбирает тему по текущему режиму:

• chatCenterSDK.theme — используется в светлом режиме;
• chatCenterSDK.darkTheme — в тёмном (если задана; иначе SDK использует theme).

---

Dynamic Color

UIColor, который сам выбирает значение в зависимости от текущего Appearance. Удобен, когда хочется один объект ChatColors для светлой и тёмной темы — вместо отдельных theme и darkTheme.

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

---

PostScript Name

Точное внутреннее имя шрифта, которое принимает UIFont(name:size:). Отличается от имени файла и отображаемого названия:

Файл	Семейство	PostScript Name
Roboto-Regular.ttf	Roboto	Roboto-Regular

---

Иерархия дизайн-системы

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

Полный список полей ChatComponents и ChatFlow — в Стилях и API Reference.

Приоритет переопределения (от низшего к высшему):

Токен → Компонент → Flow

Когда одно свойство задано на нескольких уровнях, побеждает значение из Flow.

Ленивая инициализация

Стили ChatComponents инициализируются лениво — при первом обращении они фиксируют значения текущих токенов (ChatColors, ChatTypography, ChatImages). Если изменить токен после того, как стиль уже был прочитан (например, после открытия чата), новые значения на него не повлияют — пересоздайте ChatTheme и заново присвойте его в chatCenterSDK.theme / darkTheme.

---

Таблица соответствий

Задача	Что изменить	Уровень
Цвет везде в SDK	ChatColors	Токен
Шрифт везде в SDK	ChatTypography	Токен
Иконка везде в SDK	ChatImages	Токен
Кнопка/панель везде	ChatComponents.*Style	Компонент
Элемент только в чате	theme.flows.chatFlow.*	Flow
Элемент только в поиске	theme.flows.searchFlow.*	Flow

---

Часто путают

ChatMessageStyle vs ChatMessagesStyles

• ChatMessageStyle (без s на конце) — базовый стиль одного сообщения: время, статус, отступы, иконки ошибок.
• ChatMessagesStyles (с s) — контейнер для всех типов сообщений (textMessageStyle, imageMessageStyle, и т.д.), плюс аватар, пузырь и маска.

---

chatFlow.outcomeMessages vs chatFlow.incomeMessages

• outcomeMessages — исходящие сообщения (от пользователя/клиента).
• incomeMessages — входящие сообщения (от оператора/агента).

Авто-разворот маски пузыря

При присвоении incomeMessages SDK автоматически зеркалит bubbleMaskImage — если вы её явно не переопределяли. Так одну маску можно использовать для обоих направлений. Для кастомной маски задайте bubbleMaskImage до присвоения в incomeMessages: после присвоения разворот уже не отменится.

---

typography.title vs navigationBarStyle.titleTextStyle

• typography.title — глобальный токен шрифта, используется как значение по умолчанию.
• navigationBarStyle.titleTextStyle — конкретное свойство навигационной панели. Если задать его явно, оно переопределяет токен typography.title только для навигации.

---

Конкретный пример: цвет заголовка навигационной панели

Один и тот же эффект можно получить на любом из трёх уровней — выбирайте уровень исходя из охвата изменений.

// Токен — повлияет на весь SDK, пока компонент не переопределён явно
typography.title = .systemFont(ofSize: 18, weight: .bold)

// Компонент — повлияет на навигацию на всех экранах
components.navigationBarStyle.titleTextStyle.font = .systemFont(ofSize: 18, weight: .bold)
components.navigationBarStyle.titleTextStyle.color = .white

// Flow — повлияет только на экран поиска
theme.flows.searchFlow.navigationBarStyle.titleTextStyle.color = .black

При конфликте побеждает значение из Flow, затем из Компонента, затем из Токена.