Skip to content

Theming

Primer CSS offers multiple color themes for components and utilities. The colors change based on the active theme and color mode.

Currently there are 3 themes (light, dark, dark_dimmed) to choose from. When nothing is specified, Primer CSS uses the light theme.

Set a theme

Configure Primer CSS to use a certain theme by adding the following attributes:

  • data-color-mode with a value of either light or dark
  • either data-light-theme or data-dark-theme with a value of either light, dark, dark_dimmed

The attributes can be added to any element, but ideally it should be added to the document root (<html>). Below an example to use the dark_dimmed theme:

<html data-color-mode="dark" data-dark-theme="dark_dimmed">

More examples:

Sync to the system

If the theme should be synced to the OS's color mode, use data-color-mode="auto" and set a data-light-theme as well as a data-dark-theme.

Change the color mode of your OS to see the switch between the data-light-theme="light" and data-dark-theme="dark_dimmed".

Custom color variables

It's recommended to use the functional variables as much as possible. It will guarantee that the variables will work as expected with any new theme that might get added in the future. Somtimes you might still need a custom variable that changes based on the color mode. You can create a custom variable with the color-variables mixin.

@include color-variables(
("custom-css-variable-1": (
light: var(--color-scale-gray-3),
dark: var(--color-scale-gray-5)
),
"custom-css-variable-2": (
light: var(--color-scale-gray-2),
dark: var(--color-scale-gray-6)
),
"custom-css-variable-3": (
light: var(--color-scale-gray-2),
dark: var(--color-scale-gray-6)
)
));

The custom variables will be prefixed with --color- and can be used in the same way as other functional variables.

.my-class {
color: var(--color-custom-css-variable-1);
background-color: var(--color-custom-css-variable-2);
border-color: var(--color-custom-css-variable-2);
}

Auto variables

If you tried using the scale color variables you might have noticed that they are not that useful with multiple color modes. That's because they stay light or dark in any color mode. As seen above, you could create custom variables that invert the scale like so:

@include color-variables(
("custom-css-variable": (
light: var(--color-scale-gray-7),
dark: var(--color-scale-gray-2)
)
));
.my-class {
color: var(--color-custom-css-variable);
}

In this case, the auto variables might come in handy.

.my-class {
color: var(--color-auto-gray-7);
}

The benefit of auto over the scale variables is that auto variables automatically get inverted in dark mode.

Note: If you use stylelint, the primer/no-scale-colors will fail with "[variable] is a non-functional scale color and cannot be used without being wrapped in the color-variables mixin". You can disable stylelint for this case by adding // stylelint-disable-line:

.my-class {
color: var(--color-auto-gray-7); // stylelint-disable-line
}

In general,

  1. use functional variables as much as possible.
  2. create new custom color variables if there is no functional variable that fits the use case.
  3. as an alternaitve to custom color variables, use auto variables if the results give enough constrast.
Edit this page on GitHub
2 contributorssimuraijonrohan
Last edited by simurai on April 6, 2021