WIP: color modes docs

docs/content/support/color-system.mdx

@@ -8,23 +8,84 @@ bundle: support
 
 import lightColors from '@primer/primitives/dist/js/colors/light'
 import {Flash, Box, Flex, Heading, Link, StyledOcticon} from '@primer/components'
-import {LinkIcon} from '@primer/octicons-react'
-import {palettes} from '../../src/color-variables'
-import {PaletteTable, PaletteCell, overlayColor} from '../../src/color-system'
+import {LinkIcon, OctofaceIcon} from '@primer/octicons-react'
+import {colorModes, palettes, functionalVarNames, flattened} from '../../src/color-variables'
+import {PaletteTable, PaletteCell, ColorModeTable, CSSModeVars, overlayColor} from '../../src/color-system'
+
+
+## Functional variables
+
+The Primer color system contains multiple color modes; currently, Primer ships with a light mode and a dark mode. Each color mode comes with a set of CSS variables that can be used to style elements based on the functionality of the element. These should be used instead of specifying colors directly so that the colors adapt correctly when switching between color modes.
+
+When at all possible, favor using [color utility classes](/utilities/colors) over using custom CSS to set colors.
 
 <Flash scheme="yellow">
-  Note: the colors listed below are different per color mode, and should not be used directly.
-  Instead, use functional color names (TODO)
+
+Note: because the new Primer CSS color system is based on *functional* colors, you should only use colors designed for the element you're applying them to. For example, text colors, which start with `--color-text-`, should not be used for icons, backgrounds, or any other non-text element.
+
 </Flash>
 
+### Text
+
+<CSSModeVars
+  modes={colorModes}
+  vars={functionalVarNames}
+  filter={/^text-/}
+  render={variable => {
+    return <span style={{color: `var(--color-${variable})`}}>--color-{variable}</span>
+  }}
+/>
+
+### Icons
+
+<CSSModeVars
+  modes={colorModes}
+  vars={functionalVarNames}
+  filter={/^icon-(?!folder)/}
+  render={variable => {
+    return <><span style={{color: `var(--color-${variable})`}}><StyledOcticon icon={OctofaceIcon} /></span> --color-{variable}</>
+  }}
+/>
+
+### Borders
+
+<CSSModeVars
+  modes={colorModes}
+  vars={functionalVarNames}
+  filter={/^border-/}
+  render={variable => {
+    return <div style={{border: `2px solid var(--color-${variable})`, marginBottom: 10, padding: 4}}>--color-{variable}</div>
+  }}
+/>
+
+### Backgrounds
+
+<CSSModeVars
+  modes={colorModes}
+  vars={functionalVarNames}
+  filter={/^bg-/}
+  render={variable => {
+    return <Flex mb={1}><div style={{
+      background: `var(--color-${variable})`,
+      height: 20,
+      width: 20,
+      display: 'inline-block',
+      border: '1px solid var(--color-border-primary)',
+      marginRight: 10
+    }} />--color-{variable}</Flex>
+  }}
+/>
+
+### Other variables
+
+For a list of *all* functional variables, including app- and component-specific variables, see [this reference page](https://primer.style/primitives/).
+
 ## Color palette
 
+In rare ocassions, it may be necessary to use one of the variables from the base color scale, though since the colors differ in the various color modes, the functional variables listed above should be used in almost all normal cases.
+
 <Flex flexWrap="wrap" mr={-2}>
   {palettes
-    .concat(
-      {title: 'Black', name: 'black', value: lightColors.scale.gray[9]},
-      {title: 'White', name: 'white', value: lightColors.scale.white, props: {className: 'border'}}
-    )
     .map(({name, title, value, props = {}}) => (
       <Flex.Item
         as={Link}
@@ -44,11 +105,11 @@ import {PaletteTable, PaletteCell, overlayColor} from '../../src/color-system'
     ))}
 </Flex>
 
-## Color variables
+### Color variables
 
 <Flex flexWrap="wrap" mr={[0, 0, -4]}>
   {palettes.map(({name, title, value, values}) => (
-    <Flex id={name} flexDirection="column" width={[1, 1, 1 / 2]} pr={[0, 0, 4]} mb={4} key={name}>
+    <Flex id={name} flexDirection="column" width={1} pr={0} mb={4} key={name}>
       <Flex
         as={Link}
         href={`#${name}`}
@@ -66,10 +127,9 @@ import {PaletteTable, PaletteCell, overlayColor} from '../../src/color-system'
         </Flex.Item>
         <StyledOcticon icon={LinkIcon} color="inherit !important" height={20} />
       </Flex>
-      <PaletteTable
-        columns={['variable', 'value']}
+      <ColorModeTable
+        baseColor={value}
         values={values}
-        hasHeader={false}
         cellPadding="8px 16px"
       />
     </Flex>

docs/content/support/v16-migration.mdx

@@ -0,0 +1,262 @@
+---
+title: Primer v16 Migration Guide
+description: 'Guide for migrating to version 16.0.0 of Primer'
+---
+
+Primer v16.0.0 introduces the idea of *color modes* and *functional variables*. A color mode defines a set of colors in the Primer system that differs from that of other color modes. Currently, Primer ships with a light mode and a dark mode.
+
+Because colors differ in each color mode, it doesn't make sense to try to make an element a specific color; instead, Primer now applies colors based on the function of an element using functional variables. As a result, the Sass color variables that existed in Primer prior to version 16.0.0 have been replaced with functional CSS variables. These variables have different values depending on the current color mode. For a list of the new functional CSS color variables, see [the color system page](/support/color-system). The color utility classes have also been updated to match; see [the color utilities page](/utilities/colors) for more information.
+
+## Migration guide
+
+### Components
+
+Most components don't need to be updated and should work without making changes. But some of the componets that use presentational class names now use functional class names.
+
+#### Labels
+
+[`v15`](https://primer.style/css/components/labels) | `v16`
+--- | ---
+`.Label--gray-darker`  | `.Label--primary`
+`.Label--gray`         | `.Label--secondary`
+`.Label--blue`         | `.Label--info`
+`.Label--green`        | `.Label--success`
+`.Label--yellow`       | `.Label--warning`
+`.Label--red`          | `.Label--danger`
+`.Label--orange`       | n/a
+`.Label--purple`       | n/a
+`.Label--pink`         | n/a
+
+#### Counters
+
+[`v15`](https://primer.style/css/components/labels#counters) | `v16`
+--- | ---
+`.Counter--gray`        | `.Counter--primary`
+`.Counter--gray-light`  | `.Counter--secondary`
+
+#### States
+
+[`v15`](https://primer.style/css/components/labels#states) | `v16`
+--- | ---
+n/a              | `.State--draft`
+`.State--green`  | `.State--open`
+`.State--purple` | `.State--merged`
+`.State--red`    | `.State--closed`
+
+### Utility classes
+
+See [the color utility classes page](/utilities/colors) for a list of all the functional color utility classes.
+
+#### Text
+
+[`v15`](https://primer.style/css/utilities/colors#text-color-utilities) | `v16`
+--- | ---
+`.text-gray-dark`         | `.color-text-primary`
+`.text-gray`              | `.color-text-secondary`
+`.text-gray-light`        | `.color-text-tertiary`
+`.text-blue`              | `.color-text-link`
+`.text-green`             | `.color-text-success`
+`.text-yellow`            | `.color-text-warning`
+`.text-red`               | `.color-text-danger`
+`.text-white`             | `.color-text-white`
+n/a                       | `.color-text-inverse`
+`.text-black`             | n/a
+`.text-orange`            | n/a
+`.text-orange-light`      | n/a
+`.text-purple`            | n/a
+`.text-pink`              | n/a
+
+#### Icon
+
+`v15` | `v16`
+--- | ---
+n/a | `.color-icon-primary`
+n/a | `.color-icon-secondary`
+n/a | `.color-icon-tertiary`
+n/a | `.color-icon-info`
+n/a | `.color-icon-success`
+n/a | `.color-icon-warning`
+n/a | `.color-icon-danger`
+
+#### Border
+
+[`v15`](https://primer.style/css/utilities/borders#border-color-utilities) | `v16`
+--- | ---
+`.border-gray`          | `.color-border-primary`
+`.border-gray-light`    | `.color-border-secondary`
+`.border-gray-dark`     | `.color-border-tertiary`
+`.border-blue`          | `.color-border-info`
+`.border-green`         | `.color-border-success`
+`.border-yellow`        | `.color-border-warning`
+`.border-red`           | `.color-border-danger`
+`.border-white`         | `.color-border-inverse`
+n/a                     | `.color-border-overlay`
+`.border-gray-darker`   | n/a
+`.border-blue-light`    | n/a
+`.border-red-light`     | n/a
+`.border-purple`        | n/a
+`.border-black-fade`    | n/a
+`.border-white-fade`    | n/a
+`.border-white-fade-15` | n/a
+`.border-white-fade-30` | n/a
+`.border-white-fade-50` | n/a
+`.border-white-fade-70` | n/a
+`.border-white-fade-85` | n/a
+
+#### Background
+
+[`v15`](https://primer.style/css/utilities/colors#background-utilities) | `v16`
+--- | ---
+`.bg-white`        | `.color-bg-primary`
+`.bg-gray-light`   | `.color-bg-secondary`
+`.bg-gray`         | `.color-bg-tertiary`
+`.bg-gray-dark`    | `.color-bg-canvas-inverse`
+`.bg-blue-light`   | `.color-bg-info`
+`.bg-blue`         | `.color-bg-info-inverse`
+`.bg-green-light`  | `.color-bg-success`
+`.bg-green`        | `.color-bg-success-inverse`
+`.bg-yellow-light` | `.color-bg-warning`
+`.bg-yellow`       | `.color-bg-warning-inverse`
+`.bg-red-light`    | `.color-bg-danger`
+`.bg-red`          | `.color-bg-danger-inverse`
+n/a                | `.color-bg-canvas`
+n/a                | `.color-bg-canvas-inset`
+n/a                | `.color-bg-overlay`
+`.bg-purple-light` | n/a
+`.bg-purple`       | n/a
+`.bg-yellow-dark`  | n/a
+`.bg-orange`       | n/a
+`.bg-pink`         | n/a
+
+#### Shadow
+
+`v15` | `v16`
+--- | ---
+`.box-shadow`               | `.color-shadow-small`
+`.box-shadow-medium`        | `.color-shadow-medium`
+`.box-shadow-large`         | `.color-shadow-large`
+`.box-shadow-extra-large`   | `.color-shadow-extra-large`
+
+#### Link
+
+The `link` utilities are part of the `Link` component.
+
+[`v15`](https://primer.style/css/utilities/colors##link-colors) | `v16`
+--- | ---
+`.link-gray-dark`         | `.Link--primary`
+`.link-gray`              | `.Link--secondary`
+`.muted-link`             | `.Link--muted`
+`.link-hover-blue`        | `.Link--onHover`
+n/a                       | `.Link`
+
+### Variables
+
+See [the color system page](/support/color-system) for a list of all the functional CSS variables.
+
+#### Text
+
+`v15` | `v16`
+--- | ---
+`$text-gray-dark` (`$gray-900`)         | `var(--color-text-primary)`
+`$text-gray` (`$gray-600`)              | `var(--color-text-secondary)`
+`$text-gray-light` (`$gray-500`)        | `var(--color-text-tertiary)`
+`$text-blue` (`$blue-500`)              | `var(--color-text-link)`
+`$text-green` (`$green-600`)            | `var(--color-text-success)`
+`$text-red` (`$red-600`)                | `var(--color-text-danger)`
+`$text-yellow` (`$yellow-800`)          | `var(--color-text-warning)`
+`$text-white` (`$white`)                | `var(--color-text-white)`
+n/a                                     | `var(--color-text-inverse)`
+n/a                                     | `var(--color-text-placeholder)`
+n/a                                     | `var(--color-text-disabled)`
+`$text-black` (`$black`)                | n/a
+`$text-orange` (`$orange-900`)          | n/a
+`$text-orange-light` (`$orange-600`)    | n/a
+`$text-purple` (`$purple-500`)          | n/a
+`$text-pink` (`$pink-500`)              | n/a
+
+#### Icon
+
+`v15` | `v16`
+--- | ---
+n/a                                     | `var(--color-icon-primary)`
+n/a                                     | `var(--color-icon-secondary)`
+n/a                                     | `var(--color-icon-tertiary)`
+n/a                                     | `var(--color-icon-info)`
+n/a                                     | `var(--color-icon-danger)`
+n/a                                     | `var(--color-icon-success)`
+n/a                                     | `var(--color-icon-warning)`
+
+#### Border
+
+`v15` | `v16`
+--- | ---
+`$border-color` (`$gray-200`)                   | `var(--color-border-primary)`
+`$border-gray` (`$gray-200`)                    | `var(--color-border-primary)`
+`$border-gray-light` (`lighten($gray-200, 3%)`) | `var(--color-border-secondary)`
+`$border-gray-dark` (`$gray-300`)               | `var(--color-border-tertiary)`
+`$border-white` (`$white`)                      | `var(--color-border-inverse)`
+`$border-blue` (`$blue-500`)                    | `var(--color-border-info)`
+`$border-green` (`$green-400`)                  | `var(--color-border-success)`
+`$border-red` (`$red-500`)                      | `var(--color-border-danger)`
+`$border-yellow` (`$yellow-600`)                | `var(--color-border-warning)`
+n/a                                             | `var(--color-border-overlay)`
+`$border-gray-darker` (`$gray-700`)     | n/a
+`$border-blue-light` (`$blue-200`)      | n/a
+`$border-red-light` (`$red-300`)        | n/a
+`$border-purple` (`$purple-500`)        | n/a
+`$border-black-fade` (`$black-fade-15`) | n/a
+`$border-white-fade` (`$white-fade-15`) | n/a
+`$border-green-light` (`desaturate($green-300, 40%)`) | n/a
+
+#### Background
+
+`v15` | `v16`
+--- | ---
+`$bg-white`        (`$white`)       | `var(--color-bg-primary)`
+`$bg-gray-light`   (`$gray-000`)    | `var(--color-bg-secondary)`
+`$bg-gray`         (`$gray-100`)    | `var(--color-bg-tertiary)`
+`$bg-gray-dark`    (`$gray-900`)    | `var(--color-bg-canvas-inverse)`
+`$bg-red`          (`$red-500`)     | `var(--color-bg-danger-inverse)`
+`$bg-red-light`    (`$red-000`)     | `var(--color-bg-danger)`
+`$bg-green`        (`$green-500`)   | `var(--color-bg-success-inverse)`
+`$bg-green-light`  (`$green-100`)   | `var(--color-bg-success)`
+`$bg-blue`         (`$blue-500`)    | `var(--color-bg-info-inverse)`
+`$bg-blue-light`   (`$blue-000`)    | `var(--color-bg-info)`
+`$bg-yellow`       (`$yellow-500`)  | `var(--color-bg-warning-inverse)`
+`$bg-yellow-light` (`$yellow-200`)  | `var(--color-bg-warning)`
+n/a                                 | `var(--color-bg-canvas)`
+n/a                                 | `var(--color-bg-canvas-inset)`
+n/a                                 | `var(--color-bg-overlay)`
+`$bg-black` (`$black`)              | n/a
+`$bg-black-fade` (`$black-fade-50`) | n/a
+`$bg-orange` (`$orange-700`)        | n/a
+`$bg-purple` (`$purple-500`)        | n/a
+`$bg-purple-light` (`$purple-000`)  | n/a
+`$bg-pink` (`$pink-500`)            | n/a
+`$bg-yellow-dark` (`$yellow-700`)   | n/a
+
+#### Shadow
+
+`v15` | `v16`
+--- | ---
+`$box-shadow`               | `var(--color-shadow-small)`
+`$box-shadow-medium`        | `var(--color-shadow-medium)`
+`$box-shadow-large`         | `var(--color-shadow-large)`
+`$box-shadow-extra-large`   | `var(--color-shadow-extra-large)`
+`$box-shadow-highlight`     | `var(--color-shadow-highlight)`
+`$box-shadow-inset`         | `var(--color-shadow-inset)`
+`$box-shadow-focus`         | `var(--color-state-focus-shadow)`
+
+### Color System
+
+`v15` | `v16`
+--- | ---
+`$black` | `var(--color-scale-black)`
+`$white` | `var(--color-scale-white)`
+`$gray-000` | `var(--color-scale-gray-0)`
+`$gray-100` | `var(--color-scale-gray-1)`
+`$gray-200` | `var(--color-scale-gray-2)`
+... | ...
+`$pink-700` | `var(--color-scale-pink-7)`
+`$pink-800` | `var(--color-scale-pink-8)`
+`$pink-900` | `var(--color-scale-pink-9)`

docs/content/support/variables.mdx

@@ -5,9 +5,7 @@ status: Experimental
 bundle: alerts
 ---
 
-```
 import {Variables, DeprecationIcon} from '../../src/variables'
-```
 
 <Variables>