feat(ColorModes): Base ColorMode support and serialization of color variables [GM-177]

[codecaaron]

Overview

This adds the concept of ColorModes which are a critical pieces to scalability of our design system. Adding predictability and interoperability at a foundational level.

Important Context

• This is mission critical to the success and scalability of the Sandbox project. Please reference this section of the Sandbox RFC for details around the initial implementation and planned use cases.
• For more information on the method of variable serialization and philosophy please refer to the description in this pull request.

Interactive Docs

• Color Mode Docs Page
• Initial Mode Docs

ModeToJoy.mp4

ColorModes

In order to guarantee that our components work in all contexts this introduces the concept of Color Modes. A defined set of color aliases that create a consistent visual output, without added configuration at the component level.

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 will 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.

theme

Color modes are defined at the theme level as an object:

const theme = {
  colorModes: {
    active: 'light', // the current mode
    modes: {
      light: {
        background: colors.white,
        text: colors.navy,
        primary: colors.hyper,
        secondary: colors.navy,
      },
     dark: {
       background: colors.navy,
       text: colors.white,
       primary: colors.yellow,
       secondary: colors.white,
      },
   }
}

The active mode is serialized to CSS variables in the current scope.

The default definitions are placed on :root. Overrides are placed on the containing element and scoped to all descendants.

Provisioning

--primary: #ffffff;

Consumption

color: var(--primary);

We only want users to access these variables through JS so all color variables are accessible through the color key on theme. The values of all colors on theme now only gets the css variable reference.

const { colors } = theme;
colors.hyper // var(--hyper);
colors.primary // var(--primary);

<ColorMode />

A component that will switch the active mode and provision the correct variables for consumption. And wrap the children in a <ThemeProvider /> that overrides the active key to allow components to know what context they are currently in.

Usage

import { ColorMode } from '@codecademy/gamut-styles';
const Page = ({ children }) => (
  <ColorMode mode="light">{children}</ColorMode>;
);

<Background />

To handle the many cases where we 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 automatically detect the contrast of the background and 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!

Usage

import { Background } from '@codecademy/gamut';
const Page = ({ children }) => (
  <Background color="hyper">{children}</Background>;
);

• Converts all colors to CSS Variables)
• Creates 4 basic aliases (background, text, primary, secondary) that can be toggled with color modes.
• Adds safety checks for nested Providers (multiple themes will not re-provision assets erroneously).
• Adds variables to root.
• Switches Anchor to no longer have a mode prop and only use aliased colors as an example of how the system should operate.
• Adds Docs Page for External Use and sections in the colors section of theme.

PR Checklist

• Related to designs: Literally all of them.
• Related to JIRA ticket: GM-177
• I have run this code to verify it works
• This PR includes unit tests for the code change

[jakemhiller]

siiiiiick

[codecademydev]

📬Published Alpha Packages:

@codecademy/gamut-illustrations@0.9.9-alpha.88a8a1.0
@codecademy/gamut-kit@0.3.4-alpha.88a8a1.0
@codecademy/gamut-labs@13.3.4-alpha.88a8a1.0
@codecademy/gamut-styles@9.2.1-alpha.88a8a1.0
@codecademy/gamut-system@0.6.2-alpha.88a8a1.0
@codecademy/gamut-tests@2.3.6-alpha.88a8a1.0
@codecademy/gamut@29.8.4-alpha.88a8a1.0
@codecademy/konamimojisplosion@0.2.6-alpha.88a8a1.0
@codecademy/markdown-overrides@0.5.19-alpha.88a8a1.0
@codecademy/styleguide@33.7.5-alpha.88a8a1.0
@codecademy/variance@0.6.1-alpha.88a8a1.0

[codecademydev]

🚀 Styleguide deploy preview ready!

https://606f0a50f6fd25d1c7358251--gamut-preview.netlify.app

Deploy Logs