Theming · Koobiq

What's new?

Using components is now simpler! We are moving toward full component isolation, making it easy to plug in and use components.

You no longer need to import separate SCSS files to change component colors, sizes, and fonts.
Almost all components define their styles using CSS variables that are already included in the component code. This makes styles more transparent and easier to understand.
A few small components cannot load styles on their own, so those styles need to be included globally.
We use global design-system CSS variables for colors, sizes, and fonts. This makes the code more readable and simplifies application theming — improving both code readability and the theming process significantly.

How to use

Install the Koobiq design system package.
Include the css-tokens.css, css-tokens-light.css, and css-tokens-dark.css files to use the global design-system values such as colors, sizes, and font settings.
Include the prebuilt styles file in your main styles file. This step is required for components and overlays (e.g. popups) to render correctly.
Add the kbq-light selector to the <body> element of your HTML document for the light theme, or kbq-dark for the dark theme.
Import a component and use it in your markup! 🚀

Including the prebuilt styles file


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

Here is what the body tag in index.html looks like after adding the required classes:


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

The kbq-app-background class applies the base theme styles to the application — background and text colors.

Switching themes

To switch themes, simply change the corresponding selector to go from dark to light (or vice versa), for example from kbq-dark to kbq-light. Color values will be automatically adapted to the selected theme.

Use ThemeService to switch themes. Example:


import { ThemeService } from '@koobiq/components/core';
import { Component } from '@angular/core';
 
@Component()
class AppComponent {
    constructor(private themeService: ThemeService) {
        /* the light theme will become active, and the class `kbq-light` will be added to the `body` tag */
        this.themeService.setTheme(0);
    }
}

Theme selectors

Available selectors for the dark and light themes:

Theme	Selectors
Dark	.kbq-dark, .theme-dark, .kbq-theme-dark
Light	.kbq-light, .theme-light, .kbq-theme-light

We recommend using the selectors defined in ThemeService (kbq-dark for dark and kbq-light for light).

Switching based on the OS theme

This can be implemented using window.matchMedia.

To switch the theme based on the operating system setting, three steps are required:

Define a media query to detect the user's preferred theme:


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

Add a theme object to the themes array that is passed to ThemeService during application initialization. In this object, the className property is set conditionally:


{
    name: 'Match system',
    className: this.colorAutomaticTheme.matches ? Themes.Default : Themes.Dark,
    selected: false
},

Subscribe to user theme updates and set the active theme whenever it changes:


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

An example implementation of theme switching in the Koobiq documentation can be found here.

Component customization

You can change colors, sizes, and fonts by overriding the component's CSS variables with the desired values. For example:


.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);
}

Compatibility

Stable with @koobiq/design-tokens@3.5.1.

Using CSS variables

If you are already using CSS variables from the @koobiq/design-tokens package, you need to remove the CSS variables for all components included in the design system. They now have default values built in, so you no longer need them.

Files that need to be updated:

css-tokens.css — component sizes
css-tokens-light.css — component colors for the light theme
css-tokens-dark.css — component colors for the dark theme
css-tokens-font.css — font, its sizes, and parameters for the component. This file can be removed.

List of design system components with links to their CSS variables:

Token value sources

Design system tokens are a set of values that define the visual style of our components. They are stored in the @koobiq/design-tokens package and allow us to easily manage and maintain consistent styles across all components.

Component CSS variables are a set of values used in component styles. They are derived from design tokens and live in the @koobiq/components repository. This makes it easy to use tokens in component styles and speeds up development, including design reviews.

Component tokens in the @koobiq/design-tokens package are no longer being updated.

Roadmap

We will update our component CSS variables and replace them with direct references to global design-system CSS variables where applicable.
Component tokens will be removed from the @koobiq/design-tokens package in version 4.0.0.
We will create a page displaying all global design-system tokens with their visual representations.
Component tokens in CSS variable format will be stored in the Angular components repository @koobiq/components.

If you have any questions or would like to contribute to writing the documentation, please create an issue in our GitHub repository.