gamut-theming

Use this skill when choosing or extending Gamut themes (Core, Admin, Platform, LX Studio, Percipio), wiring GamutProvider and Emotion theme TypeScript augmentation, or following CreatingThemes — not f

SKILL.md

GitHub

Gamut Theming

Source: @codecademy/gamut-styles

See also: gamut-style-utilities (css, variant, states, StyleProps, useTheme escape hatch). gamut-color-mode (semantic color, <ColorMode>, <Background>). gamut-system-props (system.*, responsive Box props).

Overview

Gamut uses Emotion's theme system. Themes are org-specific token bundles (colors, typography, spacing, etc.). The active theme is set at the app root with <GamutProvider theme={...}>; child styled components read tokens through Emotion context.

For authoring component styles (css, variant, states, system props, ColorMode), use the skills linked above and the styleguide Best practices.

Install

yarn add @codecademy/gamut-kit @emotion/react @emotion/styled

gamut-kit bundles gamut, gamut-icons, gamut-illustrations, gamut-patterns, gamut-styles, variance, and gamut-tests.

Full guide: Meta / Installation in Storybook (CSP nonce on GamutProvider, Jest, Next/Gatsby entry points).

Optionally add a peerDependencies block in package.json listing @codecademy/gamut, @codecademy/gamut-icons, @codecademy/gamut-illustrations, @codecademy/gamut-patterns, @codecademy/gamut-styles, @codecademy/gamut-tests, and @codecademy/variance (e.g. "*") so editors surface those packages — see Meta / Installation for the JSON snippet.

Required wrapper

Wrap the app root in <GamutProvider> from @codecademy/gamut-styles. This wires up the theme, color mode, and logical properties for all child components.

At runtime, GamutProvider defaults to Core when theme is omitted (theme = coreTheme in the implementation). For non-Core products and for TypeScript (theme is required on GamutProviderProps), pass theme explicitly using the table below.

import { GamutProvider, theme } from '@codecademy/gamut-styles';

const App = () => (
  <GamutProvider theme={theme}>{/* app content */}</GamutProvider>
);

Available themes

Theme Used for Import from @codecademy/gamut-styles
Core Codecademy default coreTheme or theme (default)
Admin Codecademy admin tools adminTheme
Platform Codecademy learning environment / shared platform surfaces platformTheme
LX Studio Learning Experience Studio lxStudioTheme
Percipio Skillsoft Percipio platform percipioTheme

TypeScript (theme.d.ts)

Augment @emotion/react so props.theme in styled / css matches the same theme object you pass to <GamutProvider theme={...}>. If the types disagree, system props and token autocomplete will not line up with runtime.

Add a root theme.d.ts (or merge into your existing global types):

// theme.d.ts
import '@emotion/react';

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

declare module '@emotion/react' {
  export interface Theme extends CoreTheme {}
}

Use the theme interface that matches your provider:

GamutProvider theme prop Import for Theme extends …
theme or coreTheme CoreTheme
adminTheme AdminTheme
platformTheme PlatformTheme
lxStudioTheme LxStudioTheme
percipioTheme PercipioTheme

Example when the app uses Percipio:

// theme.d.ts
import '@emotion/react';

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

declare module '@emotion/react' {
  export interface Theme extends PercipioTheme {}
}

See Emotion’s TypeScript / define a theme for details.

Theme vs color mode vs style API

Concern Where to read
Which theme object to pass to GamutProvider This skill
Light / dark semantic colors, ColorMode, Background gamut-color-mode
css / variant / states, useTheme for non-CSS JS gamut-style-utilities
Composed system.* props on styled primitives / Box gamut-system-props
Spacing, breakpoints, page grid gamut-layout

Creating a new theme

See Creating Themes in Storybook. Themes are defined in @codecademy/gamut-styles and must extend the base theme shape with all required token keys.