Add color modes to theming API

[colebemis]

Problem

Primer React doesn't provide an easy way for consumers to change color modes in their applications.

Solution

This PR updates the Primer React theming API to provide first-class support for color modes.

👉 Click here to review the new theming documentation

Impact

Primer React consumers can now easily change color modes in their applications using the new ThemeProvider component.

Breaking changes

You'll need to replace the ThemeProvider from styled-components with the new Primer React ThemeProvider:

- import {ThemeProvider} from 'styled-components'
- import {theme} from '@primer/components
+ import {ThemeProvider} from '@primer/components'

function App() {
  return (
-   <ThemeProvider theme={theme}>
+   <ThemeProvider>
      <div>your app here...</div>
    </ThemeProvider>
  )
}

Also, if you're customizing the theme, note that the structure of the theme object has changed to support color schemes:

const theme = {
- colors,
- shadows,
+ colorSchemes: {
+   light: {
+     colors,
+     shadows,
+   },
+   dark: {...},
+   dark_dimmed: {...},
+ },
  space,
  fonts,
  fontSizes,
  fontWeights,
  lineHeights,
  borderWidths,
  radii,
  breakpoints,
  sizes,
}

cc @bscofield

[changeset-bot]

🦋 Changeset detected

Latest commit: 3fc66b3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/components	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/primer/primer-components/5TW2ViTVYiuPcWWZnduiThSUdwrt
✅ Preview: https://primer-components-git-update-theming-api-primer.vercel.app

[emplums]

Made a few suggestions! One question I had that I don't think is covered by the docs - out of the box does the color scheme change at all depending on what OS color mode the user is in? Should we call out somewhere that PRC will only render in light mode unless you explicitly set up a switching mechanism using the useColorScheme prop?

[emplums]

One more suggestion: should we add a glossary of terms at the top of the theme docs? 😂

Addressed feedback

[bscofield]

Left one typo, but otherwise this looks great 🎉