feat(ThemeProvider): Adds GamutThemeProvider component and initial Global styles

[codecaaron]

Overview

Our styling needs are becoming a bit more complex in the near term. There are current use cases for global css variables and near term uses for different Color Palettes (LE colors) + Modes (light and dark) that are going to be tricky to scale.

This PR Introduces them in a controlled way by creating a single point of entry for any Global styles through a new component that wraps the default emotion ThemeProvider. While also adding the first CSS vars to the theme headerHeight.

Adding support for CSS variables has a few huge advantages:

• Semantic meaning (e.g. 4rem can mean a lot of things but var(--headerHeight) cannot.
• Scopable to elements and screensizes (e.g. local color modes only effect their direct descendants).
• Invisible to implementation (e.g. any JS that is consuming these doesn't need to be aware of its existence).

Adding any new pattern like this is dangerous, and I'm suggesting we consider using the following best practices:

• Root namespace vars should have a single point of entry (at the level of the root GamutThemeProvider).
• No mutation of root variables downstream.
• Components down in the stack should not use Global in almost all circumstance (the current header should consume the variable not provision it).
• Overriding root variables (colors should have a clear and consistent patterns e.g. { //markup }) and are scoped to the component.
• Variables must be accessible in JS (preferably through theme).

To ensure we can safely introducing these this PR adds variable serialization through createThemeVariables and createVariables.

createThemeVariables Usage

Basic example:

const { theme, vars } = createThemeVariables(rawTheme, ['keys', 'to' 'serialize']);

Contrived example:

// input 
const theme = {
  elements: {
     headerHeight: { base: '48px', xs: '64px' } , 
     contentWidth: '1024px' 
   }
}

// output theme
const theme = {
  elements: { 
    headerHeight: 'var(--headerHeight)',  
    contentWidth: 'var(--headerHeight)' }
}

// output vars
const vars = {
  '--headerHeight': '48px',
  '--contentWidth': '1024px',
  '@media screen and (min-width: 767px)`: {
       '--headerHeight': '64px',
  }
}

The returned theme object will include valid references to these global variables to be used through out the app without any knowledge of their complexity. End usage of these variables remains the same down stream. For almost all use cases this provides a more flexible + robust method of distributing styles combining the typesafety and dynamism of TS and the performance + flexibility of CSS Variables

const MyComponent = styled.div`
 height: ${({ theme }) => theme.elements.headerHeight};  // yay typesafe CSS vars
`

createVariables usage

Takes any object and returns a CSSObject with variable definitions along any selector.

const myVars = createVariables({ fontColor: {  base: 'blue',  xs:  'green', '[disabled]': 'grey' }})

const output = {
  `--fontColor`: 'blue',
  '@media min xxx': {
        `--fontColor`: 'green',
   },
  '[disabled]': {
      `--fontColor`: 'grey',
    }

Real world:

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

const ColorMode = styled.div(({ mode, theme }) => css(createVariables(theme[mode])));

const LightItUp = ({ children }) => <ColorMode mode="light">{children}</ColorMode>

• Adds GamutThemeProvider with initial Global styles.
• Adds createThemeVariables and createVariables for simple CSS Variable serialization.

PR Checklist

• Related to designs:
• Related to JIRA ticket: ABC-123
• I have run this code to verify it works
• This PR includes unit tests for the code change

[codecaaron]

This removes new line characters from gunking up the strings. This is a no op.

[MattSchiller]

imo, a small comment/warning about that would be helpful for future us's

[MattSchiller]

I am perhaps highly biased, being in the discussions about this since Christian's PRs, but I think this is a fantastic first PR. I'm curious/excited to see where this goes, how it evolves, and where it takes us.

Thanks, Aaron!

[MattSchiller]

imo, a small comment/warning about that would be helpful for future us's

[JoshuaKGoldberg]

🌮

(will post comment requests soon, we're still pairing)

[christian-dinh]

ya this is sick gg 🥇

[casey-speer]

So to handle say, LE dark vs light mode, we'd want our theme to be something like

const theme = {
  leDarkMode: {
    bgColor: 'black'
  },
  
  leLightMode: {
    bgColor: 'white'
  }
}

And do

createThemeVars(theme, ['leDarkMode', 'leLightMode']);

to serialize?

In our use case, would we want to keep this outside gamut for the near term (ie, create our own LEThemeProvider or add a vars argument to withEmotion or some other similar approach) or is the idea to start adding all vars in gamut?

Another question — if for whatever reason we wanted to provide extensions / variations of a theme somewhere in the monolith component tree, is it acceptable to nest <ThemeProvider>s ? (Not sure if emotion/styled system has any special support for that).

Aside from the small comments here, looks good to me overall.

[codecaaron]

@casey-speer

I've updated this to 2 separate methods: createVariables and

• createThemeVariables: used to redefine theme and generate global variables, not exported.
• createVariables: takes any object and returns a CSSObject with variable definitions along any selector. Exported.

For your use case you will want to use createVariables.

import { createVariables } from '@codecademy/gamut-styles';
import styled from '@emotion/styled';

const ColorMode = styled.div(({ mode, theme }) => css(createVariables(theme[mode])));

const Scene = ({ children }) => <ColorMode mode="light">{children}</ColorMode>

[christian-dinh]

I regret to inform everyone that this concept is now a Mark Dalgleish joke tweet

https://twitter.com/markdalgleish/status/1366629835880075267

[slin12]

😍

[codecademydev]

📬Published Alpha Packages:

@codecademy/gamut-illustrations@0.7.5-alpha.c3d839.0
@codecademy/gamut-labs@10.4.4-alpha.c3d839.0
@codecademy/gamut-styles@8.2.3-alpha.c3d839.0
@codecademy/gamut-tests@2.1.6-alpha.c3d839.0
@codecademy/gamut@25.5.1-alpha.c3d839.0
@codecademy/markdown-overrides@0.5.7-alpha.c3d839.0
@codecademy/styleguide@29.6.10-alpha.c3d839.0

[codecov]

Codecov Report

Merging #1444 (c3d8394) into main (b1792d8) will increase coverage by 42.70%.
The diff coverage is 86.66%.

@@             Coverage Diff             @@
##             main    #1444       +/-   ##
===========================================
+ Coverage   40.31%   83.01%   +42.70%     
===========================================
  Files         331      336        +5     
  Lines        2704     2755       +51     
  Branches      696      709       +13     
===========================================
+ Hits         1090     2287     +1197     
+ Misses       1434      415     -1019     
+ Partials      180       53      -127     

Impacted Files	Coverage Δ
packages/gamut-styles/src/theme/props.ts	100.00% <ø> (ø)
packages/gamut-styles/src/theme/theme.tsx	100.00% <ø> (ø)
...s/styleguide/.storybook/addons/system/enhancers.ts	0.00% <ø> (ø)
...es/styleguide/.storybook/addons/system/propMeta.ts	0.00% <0.00%> (ø)
...uide/.storybook/components/PropsTable/constants.ts	100.00% <ø> (+100.00%)	⬆️
...es/gamut-styles/src/theme/utils/createVariables.ts	76.92% <76.92%> (ø)
...mut-styles/src/theme/utils/createThemeVariables.ts	95.00% <95.00%> (ø)
...ages/gamut-styles/src/theme/GamutThemeProvider.tsx	100.00% <100.00%> (ø)
.../gamut-styles/src/theme/utils/shouldForwardProp.ts	100.00% <100.00%> (ø)
packages/gamut-styles/src/variables/elements.ts	100.00% <100.00%> (ø)
... and 169 more

[codecademydev]

🚀 Styleguide deploy preview ready!

https://604150fe292be9130c20716e--gamut-preview.netlify.app

Deploy Logs