← Cloudflare Realtime / realtime / realtimekit / ui-kit / branding

Design System

UI Kit RealtimeKit предоставляет все необходимые UI-компоненты для полной настройки всех компонентов UI Kit. Вы можете настроить цвета бренда, шрифты, логотип и многое другое.

Предварительные требования

Чтобы начать настройку дизайн-системы для своих встреч, сначала необходимо интеграция RealtimeKit SDK в ваше приложение.

Переопределение Design System

provideRtkDesignSystem() утилита позволяет переопределить используемую дизайн-систему собственной кастомной дизайн-системой.

Каждая мобильная платформа предоставляет систему дизайн-токенов, которая управляет цветами, границами, типографикой и отступами. Вы настраиваете токены перед запуском встречи, а UI Kit применяет их ко всем компонентам.

Импорт

<script type="module">
	import { provideRtkDesignSystem } from "https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit-ui@latest/dist/index.js";
</script>

import { provideRtkDesignSystem } from "@cloudflare/realtimekit-react-ui";

import { provideRtkDesignSystem } from "@cloudflare/realtimekit-angular-ui";

import RealtimeKitUI

import com.cloudflare.realtimekit.ui.RealtimeKitUIBuilder
import com.cloudflare.realtimekit.ui.RealtimeKitUIInfo
import com.cloudflare.realtimekit.ui.token.*
import com.cloudflare.realtimekit.models.RtkMeetingInfo

import {
	RtkUIProvider,
	provideRtkDesignSystem,
	generateBrandColors,
	generateBackgroundColors,
} from "@cloudflare/realtimekit-react-native-ui";

Использование

<div id="app"></div>

<script>
	provideRtkDesignSystem(document.getElementById("app"), {
		googleFont: "Lobster",
		// sets light background colors
		theme: "light",
		colors: {
			danger: "#ffac00",
			brand: {
				300: "#00FFE1",
				400: "#00FFFF",
				500: "#00E1D4",
				600: "#007B74",
				700: "#00655F",
			},
			text: "#071428",
			"text-on-brand": "#ffffff",
			"video-bg": "#E5E7EB",
		},
		borderRadius: "extra-rounded",
	});
</script>

<div id="app"></div>

<script>
	provideRtkDesignSystem(document.getElementById("app"), {
		googleFont: "Lobster",
		// sets light background colors
		theme: "light",
		colors: {
			danger: "#ffac00",
			brand: {
				300: "#00FFE1",
				400: "#00FFFF",
				500: "#00E1D4",
				600: "#007B74",
				700: "#00655F",
			},
			text: "#071428",
			"text-on-brand": "#ffffff",
			"video-bg": "#E5E7EB",
		},
		borderRadius: "extra-rounded",
	});
</script>

function Example() {
	const meetingEl = useRef();
	const { meeting } = useRealtimeKitMeeting();

	useEffect(() => {
		provideRtkDesignSystem(meetingEl.current, {
			googleFont: "Lobster",
			// sets light background colors
			theme: "light",
			colors: {
				danger: "#ffac00",
				brand: {
					300: "#00FFE1",
					400: "#00FFFF",
					500: "#00E1D4",
					600: "#007B74",
					700: "#00655F",
				},
				text: "#071428",
				"text-on-brand": "#ffffff",
				"video-bg": "#E5E7EB",
			},
			borderRadius: "extra-rounded",
		});
	}, []);

	return (
		<div style={{ height: "400px" }}>
			<RtkMeeting meeting={meeting} ref={meetingEl} mode="fill" />
		</div>
	);
}

Создайте RtkDesignTokens объект и передайте его в RealtimeKitUIInfo. Затем вызовите RealtimeKitUIBuilder.build() чтобы запустить встречу.

import android.graphics.Color

val customColors = RtkColorTokens(
    brand = BrandColor(
        shade300 = Color.parseColor("#FF9A6C"),
        shade400 = Color.parseColor("#FF8552"),
        shade500 = Color.parseColor("#FF6B35"),
        shade600 = Color.parseColor("#E55A24"),
        shade700 = Color.parseColor("#CC4A14"),
    ),
    background = BackgroundColor(
        shade600 = Color.parseColor("#666666"),
        shade700 = Color.parseColor("#4C4C4C"),
        shade800 = Color.parseColor("#333333"),
        shade900 = Color.parseColor("#1A1A1A"),
        shade1000 = Color.parseColor("#080808"),
    ),
    text = TextColor(
        onBrand = TextColor.TextColorOnBrand(
            shade1000 = Color.parseColor("#FF111111"),
            shade900 = Color.parseColor("#E0111111"),
            shade800 = Color.parseColor("#C2111111"),
            shade700 = Color.parseColor("#A3111111"),
            shade600 = Color.parseColor("#85111111"),
        ),
        onBackground = TextColor.TextColorOnBackground(
            shade1000 = Color.parseColor("#FFFFFFFF"),
            shade900 = Color.parseColor("#E0FFFFFF"),
            shade800 = Color.parseColor("#C2FFFFFF"),
            shade700 = Color.parseColor("#A3FFFFFF"),
            shade600 = Color.parseColor("#85FFFFFF"),
        ),
    ),
)

val designTokens = RtkDesignTokens(
    colors = customColors,
    borderRadius = RtkBorderRadiusToken.Rounded,
    borderWidth = RtkBorderWidthToken.Thin,
)

val uiKitInfo = RealtimeKitUIInfo(
    activity = this,
    rtkMeetingInfo = RtkMeetingInfo(authToken = "<auth_token>"),
    designTokens = designTokens,
)
RealtimeKitUIBuilder.build(uiKitInfo).startMeeting()

Вызовите provideRtkDesignSystem() с DesignTokens объект до или во время рендеринга. Оберните компоненты встречи в RtkUIProvider.

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    provideRtkDesignSystem({
      theme: 'darkest',
      colors: {
        brand: generateBrandColors('#FF6B35'),
        text: '#FFFFFF',
      },
      borderRadius: 'rounded',
      borderWidth: 'thin',
      fontFamily: 'Helvetica',
    });
  }, []);

  return (
    <RtkUIProvider>
      {/* Your meeting components */}
    </RtkUIProvider>
  );
}

generateBrandColors() вспомогательная функция вычисляет пять оттенков бренда из одного шестнадцатеричного значения. Используйте generateBackgroundColors() для аналогичного поведения с цветами фона.

iOS UI Kit использует DesignLibrary.shared в качестве центрального реестра дизайн-токенов. Создайте собственный конфигуратор, соответствующий DesignLibraryConfiguratorProtocol и передать её в библиотеку дизайна перед началом встречи.

import RealtimeKitUI

class CustomConfigurator: DesignLibraryConfiguratorProtocol {
    let colorBrandBase: BrandColorToken.Shade = .init(hex: "#FF6B35")!
    let colorBackgroundBase: BackgroundColorToken.Shade = .init(hex: "#080808")!

    let textColorBackgroundBase: TextColorToken.Background.Shade = .init(hex: "#FFFFFF")!
    let textColorBrandBase: TextColorToken.Brand.Shade = .init(hex: "#111111")!

    let statusDangerColor: StatusColor.Shade = .init(hex: "#FF2D2D")!
    let statusSuccessColor: StatusColor.Shade = .init(hex: "#83D017")!
    let statusWarningColor: StatusColor.Shade = .init(hex: "#FFCD07")!

    let cornerRadiusRoundFactor: CGFloat = 4.0
    let cornerRadiusExtraRoundFactor: CGFloat = 8.0
    let cornerRadiusCircularFactor: CGFloat = 8.0

    let borderSizeThinFactor: CGFloat = 1.0
    let borderSizeFatFactor: CGFloat = 2.0
}

// Apply the custom configurator
DesignLibrary.shared.setConfigurator(configurator: CustomConfigurator())

SDK автоматически создаёт вариации оттенков для каждого базового цвета. Оттенки бренда варьируются от 300 до 700, а оттенки фона от 600 до 1000. Оба ряда получены осветлением базового цвета.

Design Tokens

UI Kit использует дизайн-токены ↗ для своей дизайн-системы.

Дизайн-токены представляют собой связанные с дизайном значения, которые используются для поддержания дизайн-системы и обеспечивают гибкость при настройке общего вида системы с помощью таких значений, как типографика, отступы, цвета и так далее.

Эти дизайн-токены хранятся и совместно используются компонентами с помощью CSS-переменные ↗.

Система токенов охватывает цвета, границы, типографику и отступы. В таблице ниже приведены значения по умолчанию для всех мобильных платформ.

Токен	Android	iOS	React Native
Цвет бренда	`#2160FD`	`#0246FD`	`#2160FD`
Контекст	`#080808`	`#050505`	`#080808`
Текст на фоне	`#FFFFFF`	`#FFFFFF`	`#FFFFFF`
Текст на цвете бренда	`#111111`	`#111111`	`#FFFFFF`
Опасность	`#FF2D2D`	`#FF2D2D`	`#FF2D2D`
Успешно	`#83D017`	`#83D017`	`#83D017`
Предупреждение	`#FFCD07`	`#FFCD07`	`#FFCD07`

Типографика

Вы можете легко настроить семейство шрифтов, используемое в компонентах UI Kit, с помощью этого токена. Изменить это значение можно двумя способами с помощью утилиты provideRtkDesignSystem.

--rtk-font-family: Inter;

Использование

Задайте одно из этих значений в своих дизайн-токенах.

С fontFamily. Используйте собственное семейство шрифтов, но тогда шрифт придется загружать вручную.
С googleFont. Используйте шрифт Google, он загружается автоматически.

const designTokens = {
	fontFamily: "Custom Font",
	// or
	googleFont: "A Google Font",
};

Настройка шрифта недоступна через RtkDesignTokens API. UI Kit по умолчанию использует системный шрифт.

Передайте fontFamily строку в provideRtkDesignSystem() для использования пользовательского шрифта. Вы должны загрузить шрифт в приложении до вызова этой функции.

provideRtkDesignSystem({
	fontFamily: "Helvetica",
});

iOS UI Kit использует системный шрифт (UIFont.systemFont) по умолчанию. Настройка шрифта недоступна через DesignLibraryConfiguratorProtocol. Чтобы изменить шрифты, создайте пользовательский AppThemeProtocol реализацию и переопределить свойства оформления для отдельных компонентов.

class CustomTheme: AppThemeProtocol {
    // ...
    var clockViewAppearance: RtkTextAppearance {
        let model = RtkTextAppearanceModel()
        model.font = UIFont(name: "Helvetica", size: 12) ?? .systemFont(ofSize: 12)
        return model
    }
    // ...
}

Цвета

CSS-переменные задаются в формате: R G B.

Ниже приведены все цветовые токены и их значения по умолчанию.

--rtk-colors-brand-500: 33 96 253;
--rtk-colors-background-1000: 8 8 8;
/* ... rest of the shades */

Использование

Набор часто используемых background оттенков доступно по умолчанию с theme свойство.

Значения темы: light, dark, darkest.

Измените цветовые токены следующим образом. Будут заданы только указанные вами цвета.

const designTokens = {
	theme: "darkest",
	colors: {
		brand: { 500: "#0D51FD" },
		background: { 1000: "#080808" },
		text: "#ffffff",
		"text-on-brand": "#ffffff",
		"video-bg": "#181818",
	},
};

Оттенки цвета бренда варьируются от 300 (самый светлый) до 700 (самый тёмный), при этом 500 является основным оттенком. Оттенки фона варьируются от 600 (самый светлый) до 1000 (самый насыщенный).

Задайте colorBrandBase и colorBackgroundBase в вашем DesignLibraryConfiguratorProtocol реализацию. SDK автоматически создаёт оттенки 300-700 для бренда и 600-1000 для фона, осветляя базовый цвет с шагом 12%.

iOS также предоставляет доступ к video свойство у BackgroundColorToken который управляет цветом фона под плитками видео, когда поток неактивен. По умолчанию используется shade800.

class CustomConfigurator: DesignLibraryConfiguratorProtocol {
    let colorBrandBase: BrandColorToken.Shade = .init(hex: "#FF6B35")!
    let colorBackgroundBase: BackgroundColorToken.Shade = .init(hex: "#1A1A1A")!

    let textColorBackgroundBase: TextColorToken.Background.Shade = .init(hex: "#FFFFFF")!
    let textColorBrandBase: TextColorToken.Brand.Shade = .init(hex: "#111111")!

    let statusDangerColor: StatusColor.Shade = .init(hex: "#FF2D2D")!
    let statusSuccessColor: StatusColor.Shade = .init(hex: "#83D017")!
    let statusWarningColor: StatusColor.Shade = .init(hex: "#FFCD07")!

    // Border properties (required by protocol)
    let cornerRadiusRoundFactor: CGFloat = 4.0
    let cornerRadiusExtraRoundFactor: CGFloat = 8.0
    let cornerRadiusCircularFactor: CGFloat = 8.0
    let borderSizeThinFactor: CGFloat = 1.0
    let borderSizeFatFactor: CGFloat = 2.0
}

Android предоставляет videoBackground поле в RtkColorTokens чтобы задать цвет фона под плитками видео, когда видеопоток неактивен. Значение по умолчанию: #333333.

val customColors = RtkColorTokens(
    brand = BrandColor( /* ... */ ),
    background = BackgroundColor( /* ... */ ),
    text = TextColor( /* ... */ ),
    videoBackground = Color.parseColor("#1A1A1A"),
)

React Native предоставляет три готовые темы, которые задают согласованную цветовую палитру фона.

Тема	Описание
`darkest`	Очень темный фон (по умолчанию)
`dark`	Темный фон
`light`	Светлый фон

Передайте theme свойство в provideRtkDesignSystem(). Готовую тему можно сочетать с пользовательскими переопределениями цвета.

provideRtkDesignSystem({
	theme: "dark",
	colors: {
		brand: generateBrandColors("#0246FD"),
	},
});

Отступы

Шкала отступов используется для задания ширины, высоты, внешних отступов, внутренних отступов, позиций и т. д. во всех компонентах.

Значение по умолчанию для базовой единицы шкалы отступов составляет 4px.
Остальные значения рассчитываются на основе этого базового значения, установленного в --rtk-space-1.
Текущая шкала отступов находится в диапазоне от 0 до 96.

--rtk-space-1: 4px;
/* ... rest of the spacing scale */

Использование

Задайте базу шкалы отступов с помощью spacingBase свойство.

const designTokens = {
	spacingBase: 4, // value in px
};

spacingBase свойство задает базовую единицу шкалы отступов в пикселях. Все значения отступов в UI Kit рассчитываются на основе этой базовой единицы.

provideRtkDesignSystem({
	spacingBase: 4, // default: 4px
});

Настройка отступов недоступна через API дизайн-токенов на этой платформе.

iOS UI Kit использует SpaceToken с базовой единицей в 4 пункта. Шкала отступов начинается от space0 (0) до space9 (36). Настройка отступов недоступна через публичный DesignLibraryConfiguratorProtocol. Все значения отступов вычисляются внутренне на основе базовой единицы.

Границы

Свойства ширины границы и радиуса границы также можно настраивать с помощью дизайн-токенов!

Имя токена	Значения
`borderWidth`	`none`, `thin`, `fat`
`borderRadius`	`sharp`, `rounded`, `extra-rounded`, `circular`

Использование

const designTokens = {
	borderWidth: "thin",
	borderRadius: "rounded",
};

Все мобильные платформы поддерживают одинаковые параметры радиуса и толщины границы.

Токен	Значения
`borderRadius`	`sharp`, `rounded`, `extra-rounded`, `circular`
`borderWidth`	`none`, `thin`, `fat`

Передайте borderRadius и borderWidth напрямую в RtkDesignTokens конструктор.

val designTokens = RtkDesignTokens(
    colors = customColors,
    borderRadius = RtkBorderRadiusToken.Circular,
    borderWidth = RtkBorderWidthToken.Thin,
)

Передайте borderRadius и borderWidth к provideRtkDesignSystem().

provideRtkDesignSystem({
	borderRadius: "extra-rounded",
	borderWidth: "fat",
});

Задайте cornerRadiusRoundFactor, cornerRadiusExtraRoundFactor, cornerRadiusCircularFactor, borderSizeThinFactor, а также borderSizeFatFactor в вашем DesignLibraryConfiguratorProtocol реализацию. Эти коэффициенты определяют множитель, используемый для каждого стиля границы.

class CustomConfigurator: DesignLibraryConfiguratorProtocol {
    // ... color properties ...

    let cornerRadiusRoundFactor: CGFloat = 4.0
    let cornerRadiusExtraRoundFactor: CGFloat = 8.0
    let cornerRadiusCircularFactor: CGFloat = 8.0

    let borderSizeThinFactor: CGFloat = 1.0
    let borderSizeFatFactor: CGFloat = 2.0
}

DesignLibrary.shared.setConfigurator(configurator: CustomConfigurator())

iOS использует BorderRadiusToken.RadiusType со значениями .sharp, .rounded, .extrarounded, а также .circular. Ширина границы использует BorderWidthToken.Width со значениями .none, .thin, а также .fat.