Overview

#

During design and development, colors should be referenced by name. Using named colors has a few important benefits:

• More meaningful than hex values in mockups and code
• Encourages consistency and accessibility across the application
• Support for alternate themes

Some examples of named colors in the Kolibri Design System include:

Care must be taken as we adjust the colors in the application. There are a number of considerations to take into account, including:

• Branding, aesthetics, and color harmony
• Sufficient contrast between foreground and background colors
• Accommodation of color blind users
• Maintainability and consistency of the application and code
• Amenability to theming by using tokens correctly

Usage

#

Colors can be referenced in two ways:

• CSS variables in <style> blocks and SCSS files. Use these by default.
• JavaScript accessors on Vue components, for inline :style bindings and for colors that need to be built at runtime (for example, a color combined with a custom opacity).

Both are set up by Vue.use(KThemePlugin) (see Installation ) and stay in sync when brand colors change at runtime via setBrandColors() or setTokenMapping().

CSS variables

Theme values are emitted as CSS variables on :root in three layers:

• --tokens-* for named color tokens (e.g. --tokens-primary)
• --brand-* for brand color scales (e.g. --brand-primary-v500)
• --palette-* for the full palette (e.g. --palette-grey-v200)

Reference them directly with var(--name). For example, to color text using the error token:

      <div class="error-message">This is an error</div>
      <style>
        .error-message {
          color: var(--tokens-error);
        }
      </style>
    

This will display:

For palette and brand variables, replace the dots in the path with hyphens and drop the underscore (palette.grey.v_400 becomes --palette-grey-v400). Token names are used as-is.

Computed styles

Colors are also available on every Vue component as JavaScript objects. Adding Vue.use(KThemePlugin) makes the following objects available:

• $themeBrand contains colors related to the aesthetic color scheme
• $themeTokens contains colors with special meanings in Kolibri
• $themePalette contains a wide range of additional compatible colors

Use these for inline :style bindings and for values computed at runtime. For example, to color text using $themeTokens.primary with a computed style:

      <div :style="{ color: $themeTokens.primary }">This is not an error</div>
    

This will display:

Move style definitions from the template to computed props if the style gets complex.

Computed classes

$computedClass can be used to dynamically create new classes for pseudo-elements such as :hover or :focus. For example:

      <input :class="$computedClass({ '::placeholder': { color: $themeTokens.annotation } })" >
    

This is usually not necessary, use a <style> block with var(--tokens-*) for static pseudo-class colors.

Notation

In the references below we use the following shorthand:

• brand refers to $themeBrand in JavaScript, or --brand-* in CSS
• tokens refers to $themeTokens in JavaScript, or --tokens-* in CSS
• palette refers to $themePalette in JavaScript, or --palette-* in CSS

Darken utilities

You can apply darken utilities $darken1, $darken2, and $darken3 to palette colors and tokens to achieve their darker shades. They are available on every Vue component.

      <div :style="{ backgroundColor: $themePalette.red.v_600 }">base</div>
      <div :style="{ backgroundColor: $darken1($themePalette.red.v_600) }">$darken1</div>
      <div :style="{ backgroundColor: $darken2($themePalette.red.v_600) }">$darken2</div>
      <div :style="{ backgroundColor: $darken3($themePalette.red.v_600) }">$darken3</div>
    

These utilities shouldn't be overused. Always check if there is a shade in the palette available that can be used instead.

Tokens

#

Color tokens are the most important set of named colors because they have a specific, well-defined usage within the application. Over time, our set of tokens should grow and shrink as necessary to fit the needs of the application.

Color tokens are by themselves abstract and defined by a purpose, not a color value. A theme makes them concrete by mapping them to specific brand colors and palette colors .

When using tokens, it's very important to choose them based on their semantic purpose, not because of their color values. This ensures that new themes can be created effectively.

Brand shortcuts

UI Colors

Text

Learner activity

User-related labels

Content-related labels

Scales

#

A color scale – sometimes called a color ramp – is an evenly-spaced ramp of shades for a particular color hue. In the Kolibri Design System, we follow Google's Material convention and segment colors into brightness levels, named v_50, v_100, v_200, v_300, v_400, v_500, v_600. Note that v_50 is only present on select color families:

Due to the inconsistent way that humans perceive color and light, computing these scales is both art and science. It should not be done by simply sliding a "brightness" setting. We used materialpalettes.com to generate the scales for our primary and secondary brand colors. The same should be done for new themes.

Brand colors

#

Brand colors are chosen to reflect the mood, identity, or trademark of an application or an organization. The design system defines primary (dominant) and secondary (accent) branded color hues.

Palette

#

A color palette is a set of generic base colors that cover a wide range of the color spectrum. We use the 2014 Material Design color palette, which has many colors to choose from.

In our design system, colors from the palette have names like pink, grey, and amber.

With the exception of grey values, choosing arbitrary colors from the palette is only slightly better than choosing arbitrary hex values from the full color spectrum. No consistency or meaning is ensured, and they should generally be avoided in favor of specific color tokens and brand colors.

Grey values

A scale of standard greys

Full palette

The complete set of colors available in the palette