We've created several color modes by default for light and dark context.

Each color mode consists of a set of aliased color tokens. Each alias has semantic meaning for how the color is used throughout our design system:

• text: The standard text color for all type.
• background: The base background color.
• primary: The color used for interactive elements with a primary action.
• secondary: The color used for interactive elements with a secondary action.

Note: This set is not final and is likely to expand as our needs grow.

Gamut components are built using these aliases instead of referring to specific tokens directly, guaranteeing that:

• Components can be used in ANY context without configuration and work correctly.
• Consistent color scheme and accessibility between contexts.
• Colors usage more meaningful when reading through code as aliases hint to usage.
• Dead simple configuration.

Light mode

Dark mode

<ColorMode />

Here's an example using components in context. By toggling dark mode you can see all the colors map to a new color that is accessible for the mode by default.

Usage

import { ColorMode } from '@codecademy/gamut-styles';

const Page = ({ children }) => (
  <ColorMode mode="light">{children}</ColorMode>;
);
Copy

system Color Mode

You can also provide ColorMode with mode="system" and it will automatically set the color mode based on the users preference.

Usage

import { ColorMode } from '@codecademy/gamut-styles';

const Page = ({ children }) => (
  <ColorMode mode="system">{children}</ColorMode>;
);
Copy

<Background />

There are many cases where you may need a specific background color for a section of a page, like a card or a landing page. Instead of having to guess the right mode for the background, we've added a <Background /> component to detect if contrast of the background and current mode's text color meet an accessible standard. If not, we will automatically change the mode to an accessible one, allowing you to be sure that all components inside your background will meet contrast requirements and designs without any configuration!

Current background

When you use Background the selected background color is set to a theme variable background-current. This is useful to reference when you need access to an ancestors background color (e.g. simulating transparency + masking content).

Usage

import { Background } from '@codecademy/gamut-styles';

const Page = ({ children }) => (
  <Background bg="hyper">{children}</Background>;
);
Copy

useCurrentMode | useColorMode

For situations where you need to access the current mode in JS, the value of always present on the emotion theme context. If you need the full theme you may use the built in useTheme hook from @emotion/react. However for cases that are specific to modes only we expose 2 hooks to help.

• useColorMode(): If you need access to all modes and their variables this hook will return a tuple of [mode, modeColors, modes].
• useCurrentMode(): For simpler usages where you want to get the default mode, this hook returns the key of the active mode.

import { useColorMode, useCurrentMode } from '@codecademy/gamut-styles';

const [current, currentColors, modes] = useColorMode();

const current = useCurrentMode();
Copy

Examples

Sometimes you may just want to wrap a page in a different background color than the base color mode.

In some cases you may want to use multiple areas with different backgrounds. <Background /> makes this a simple task by provisioning a new color context for all components inside.

usePrefersDarkMode

If you want to check which color mode the user prefers, you can use usePrefersDarkMode and it will return a boolean value using window.matchMedia('(prefers-color-scheme: dark)') media query.