Theming · Koobiq

Что нового?

Теперь использование компонентов стало проще! Мы движемся к полной изоляции компонентов, что позволит вам легко подключать и использовать их.

Больше не нужно подключать отдельные файлы SCSS для изменения цветов, размеров и шрифтов компонентов.
Практически во всех компонентах стили задаются с помощью CSS-переменных, которые уже включены в код компонента. Это делает стили более прозрачными и понятными.
Некоторые маленькие компоненты не могут самостоятельно подключать стили, поэтому их нужно подключить глобально.
Мы используем глобальные CSS-переменные дизайн-системы для цветов, размеров и шрифтов. Это делает код более читаемым и упрощает изменение темы приложения. Это не только улучшает читабельность кода, но и значительно упрощает процесс темизации.

Как использовать?

Установите пакет дизайн системы Koobiq.
Подключите файлы css-tokens.css, css-tokens-light.css, css-tokens-dark.css для использования глобальных значений дизайн-системы, например, цветов, размеров и параметров шрифтов.
Подключите файл преднастроенных стилей в свой основной файл стилей. Этот шаг нужен для правильного отображения компонентов и оверлеев (например, всплывающих окон).
Добавьте селектор kbq-light к элементу <body> вашего HTML-документа для использования светлой темы и kbq-dark для темной темы.
Импортируйте компонент и используйте его в вёрстке!🚀

Подключение файла преднастроенных стилей


@use '@koobiq/components/prebuilt-themes/theme.css';

Так выглядит тег body в index.html после добавления необходимых классов:


<body class="kbq-app-background kbq-light">
    <app></app>
</body>

Класс kbq-app-background используется для применения базовых стилей темы к приложению - цвет фона и текста.

Переключение тем

Для переключения темы достаточно изменить соответствующий селектор, чтобы перейти от темной к светлой теме (или наоборот). Например, с kbq-dark на kbq-light. Цветовые значения будут автоматически адаптированы под выбранную тему.

Для переключения тем используйте ThemeService. Вот пример:


import { ThemeService } from '@koobiq/components/core';
import { Component } from '@angular/core';
 
@Component()
class AppComponent {
    constructor(private themeService: ThemeService) {
        /* светлая тема станет активной, к тегу `body` добавится класс `kbq-light` */
        this.themeService.setTheme(0);
    }
}

Селекторы для тем

Вот таблица доступных селекторов для темной и светлой тем:

Тема	Селекторы
Темная	.kbq-dark, .theme-dark, .kbq-theme-dark
Светлая	.kbq-light, .theme-light, .kbq-theme-light

Мы рекомендуем использовать те селекторы, которые указаны в сервисе ThemeService (kbq-dark для темной и kbq-light для светлой).

Переключение по выбранной в ОС теме

Данный механизм возможно реализовать с помощью window.matchMedia;

Для реализации переключения темы в зависимости от операционной системы необходимы выполнить 3 условия:

Определить медиа-запрос для получения пользовательской темы:


colorAutomaticTheme = window.matchMedia('(prefers-color-scheme: light)');

Добавить объект темы в массив тем, который будет подключаться в ThemeService при инициализации приложения. В данной теме свойство className будет устанавливаться по условию


{
    name: 'Как в системе',
    className: this.colorAutomaticTheme.matches ? Themes.Default : Themes.Dark,
    selected: false
},

Подписаться на обновление темы пользователя и устанавливать активную тему при обновлении.


this.colorAutomaticTheme.addEventListener('change', this.setAutoTheme);

Пример реализации переключения тем в документации Koobiq тут.

Кастомизация компонентов

Изменить цвета, размеры и шрифты можно задав соответствующие значения CSS-переменным компонента. Например:


.kbq-dark .kbq-alert {
    --kbq-alert-default-contrast-container-background: var(--kbq-foreground-contrast-secondary);
    --kbq-alert-default-contrast-container-title: var(--kbq-background-contrast-fade);
}

Совместимость

Работает стабильно с @koobiq/design-tokens@3.5.1.

Использование CSS-переменных

Если уже используются CSS-переменные из пакета @koobiq/design-tokens, необходимо удалить CSS-переменные для всех включенных в дизайн систему компонентов. В них используется значение по умолчанию, они вам больше не нужны.

В каких файлы необходимо внести изменения:

css-tokens.css - размеры компонента
css-tokens-light.css - цвета компонента для светлой темы
css-tokens-dark.css - цвета компонента для темной темы
css-tokens-font.css - шрифт, его размеры и параметры для компонента. Его можно удалить.

Список компонентов дизайн системы со ссылками на их CSS-переменные:

Источник значений токенов

Токены дизайн-системы – это набор значений, которые определяют визуальный стиль наших компонентов. Они хранятся в пакете @koobiq/design-tokens и позволяют нам легко управлять стилем и обеспечивать его согласованность во всех компонентах.

Компонентные CSS-переменные – это набор значений, которые используются в стилях наших компонентов. Они задаются на основе токенов и хранятся в репозитории @koobiq/components. Это позволяет нам легко использовать токены в стилях компонентов и ускоряет разработку, в том числе проведение дизайн-ревью.

На данный момент компонентные токены в пакете @koobiq/design-tokens больше не обновляются.

Планы

Проведем обновление наших компонентных CSS-переменных и будем использовать вместо них глобальные CSS-переменные нашей дизайн-системы напрямую, где необходимо.
Удалим компонентные токены из пакета @koobiq/design-tokens в версии 4.0.0.
Создадим страницу, где будут отображаться глобальные токены дизайн-системы с их визуальным представлением.
Будем хранить компонентные токены в формате CSS-переменных в репозитории Angular-компонентов @koobiq/components.

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