Oryx: Color system

An important part of the application user interface is the colors. Colors are used everywhere throughout components and are important for a good user experience. To ensure that you can adjust the colors to your needs throughout the application, a configurable color system is provided.

The color system lets you set up the color values globally as well as override them per component. Components do not define values for colors directly in their CSS but use design tokens. Design tokens are (CSS) variables that are provided by themes, which you can customize in your project.

The color system comes with semantic color types and a consistent number of color steps. This results in a consistent naming system throughout all the components. The actual colors for those groups are not relevant to the color system and are part of the theme configuration. This lets you configure the colors in a global theme.

Color palette

The color palette provides a number of colors that you can use to quickly set up an Oryx application with the colors of your choice. This is particularly useful to demonstrate and experience how consistently the color system is applied across all components. All colors in the color palette are fully accessible by default, both in light and dark modes.

To enable you to create fully accessible colors, we added a third-party open-source library: Radix. Radix contains a wide range of colors and neutrals that can be configured in Oryx. Spryker green and gray are the only custom colors on top of the Radix color system.

Color contrast

Color contrast is an important accessibility feature. When colors do not have enough contrast, users with limited sight might not be able to use the experience to its full extent.

Color contrast is based on two colors. The color system provides 13 color shades which can be used to create enough contrast. The Oryx design system and the application components are fully equipped to provide enough contrast, even if you configure an alternative color from the palette. However, if you provide a custom color, you should test its accessibility.

Color mode

Colors can be provided for both light and dark modes. The dark mode is another important feature for accessibility and is supported by all colors in the color palette. Oryx applications can automatically adapt to the device mode, but you can also use the ColorModeSelectorComponent component to let the user manage the color mode manually.

Semantic color types

There are eight semantic color types used in Oryx components:

Color steps

Each color type comes in 13 values, also known as steps. Components might not use all the steps of a color, but there are enough to provide enough nuance and create accessible experiences.

The steps count from 0 to 12. In light mode, the steps go from light to dark: the higher the number, the darker the color. In dark mode, this is reversed.

The Radix color system provides 15 color scales that are designed with a white foreground text and 5 bright scales for black foreground text. The foreground color is provided by step 0. For the bright colors, this color is black, while for the other colors, it’s white. In dark mode, this is reversed.

The color values can be of any supported color in the web platform, such as named colors like red or blue, hex color, HCL, or RBA. Oryx doesn’t interfere with the provided colors but uses them as-is.

Configure colors from the color palette

To change the colors in an Oryx application, you can configure the colors using the color palette. This is convenient and the recommended approach to quickly try out the color system.

import { appBuilder } from "@spryker-oryx/application";
import { colorPalette } from "@spryker-oryx/experience";

appBuilder().withTheme({
  designTokens: [
    {
      color: {
        primary: colorPalette.colors.sky,
        secondary: colorPalette.grays.slate,
      },
    },
  ],
});

Configure custom colors

If your exact color of choice is not provided by the pallette, you can configure it using an extended configuration.

import { appBuilder } from "@spryker-oryx/application";

appBuilder().withTheme({
  designTokens: [
    {
      color: {
        primary: {
          light: {
            0: "lightblue",
            1: "blue",
            // etc, up to 12
          },
          dark: {
            0: "blue",
            1: "lightblue",
            // etc, up to 12
          },
        },
      },
    },
  ],
});

Color design tokens

Each color type and its values are provided as a design token. Design tokens are provided as CSS variables to the root of the application. The color design tokens follow a consistent naming pattern to improve the integration into your components:

--oryx-color-[type]-[step]

For example, if you create a solid button with an accessible foreground text color, you can do the following:

button {
  color: var(--oryx-color-primary-0);
  background: var(--oryx-color-primary-9);
}

button:hover {
  background-color: var(--oryx-color-primary-10);
}

The example shows the usage of design tokens in CSS. The primary color is defined for the default state of the the button background color. When the user hovers over the button, the 400 color shade is used. It works consistently with all colors. The buttons have a white foreground color on a colorful background. In case the background color is bright, the foreground color becomes black.