WIP: color modes docs

docs/content/support/color-system.mdx

@@ -9,22 +9,33 @@ 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 {colorModes, palettes, functionalVarNames, flattened} from '../../src/color-variables'
+import {PaletteTable, PaletteCell, ColorModeTable, overlayColor} from '../../src/color-system'
 
-<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)
-</Flash>
+## 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 the CSS color variables.
+
+<ColorModeTable
+  baseColor="#ffffff"
+  values={functionalVarNames.filter(v => !v.includes('shadow') && !v.includes('Shadow')).map(name => ({
+    variable: name,
+    slug: name,
+    values: colorModes.reduce((acc, mode) => {
+      acc[mode] = flattened[mode][name]
+      return acc
+    }, {})
+  }))}
+/>
 
 ## 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 +55,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 +77,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/src/color-system.js

@@ -3,9 +3,55 @@ import PropTypes from 'prop-types'
 import chroma from 'chroma-js'
 import styled from 'styled-components'
 import {Box, Text} from '@primer/components'
-import {colors, getPaletteByName} from './color-variables'
+import {colors, colorModes, getPaletteByName} from './color-variables'
 import Table from './table'
 
+function capitalize(word) {
+  return word[0].toUpperCase() + word.substr(1)
+}
+
+export function ColorModeTable({baseColor, values, ...rest}) {
+  const fgColor = overlayColor(baseColor)
+  const colorProps = {bg: baseColor, color: fgColor}
+
+  values.forEach(({variable, values, slug}) => {
+    if (!values.light || !values.dark) {
+      console.log(variable, values)
+    }
+  })
+
+  return (
+    <Table {...rest}>
+      <thead>
+        <tr>
+          <PaletteCell as="th" {...colorProps}>
+            Variable
+          </PaletteCell>
+          {colorModes.map(mode => (
+            <PaletteCell as="th" {...colorProps} key={mode}>
+              {capitalize(mode)} Mode
+            </PaletteCell>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {values.map(({variable, slug, values}) => (
+          <tr key={slug}>
+            <PaletteCell {...colorProps}>
+              <Var>{variable}</Var>
+            </PaletteCell>
+            {Object.keys(values).map(mode => (
+              <PaletteCell key={mode} bg={values[mode]} color={overlayColor(values[mode])}>
+                <Var>{values[mode]}</Var>
+              </PaletteCell>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </Table>
+  )
+}
+
 export function PaletteTable(props) {
   const {columns = [], hasHeader, ...rest} = props
   const {children = <PaletteTableFragment columns={columns} {...rest} />} = rest
@@ -212,9 +258,14 @@ export function overlayColor(bg) {
   if ($overlayColorCache.has(bg)) {
     return $overlayColorCache.get(bg)
   } else {
-    const result = chroma(bg).luminance() > 0.5 ? colors.black : colors.white
-    $overlayColorCache.set(bg, result)
-    return result
+    try {
+      const result = chroma(bg).luminance() > 0.5 ? colors.black : colors.white
+      $overlayColorCache.set(bg, result)
+      return result
+    } catch (err) {
+      console.log('error with value', bg)
+      return 'white'
+    }
   }
 }
 

docs/src/color-variables.js

@@ -1,11 +1,17 @@
 import titleCase from 'title-case'
-import lightModeColors from '@primer/primitives/dist/js/colors/light'
+import allModeColors from '@primer/primitives/dist/js/colors'
 
 // XXX we don't necessarily define them in this order in primer-colors,
 // so we define an array here just to be safe
 const gradientHues = ['gray', 'blue', 'green', 'purple', 'yellow', 'orange', 'red', 'pink']
 
-const colors = lightModeColors.scale
+const colors = allModeColors.light.scale
+
+const colorModes = Object.keys(allModeColors).sort((a, b) => {
+  if (a.startsWith('light') && !b.startsWith('light')) return -1
+  if (!a.startsWith('light') && b.startsWith('light')) return 1
+  else return a.localeCompare(b)
+})
 
 const palettes = gradientHues.map(name => {
   return {
@@ -14,6 +20,10 @@ const palettes = gradientHues.map(name => {
     value: colors[name][5],
     values: colors[name].map((value, index) => ({
       value,
+      values: colorModes.reduce((acc, mode) => {
+        acc[mode] = allModeColors[mode].scale[name][index]
+        return acc
+      }, {}),
       index,
       variable: `--color-scale-${name}-${index}`,
       slug: `color-scale-${name}-${index}`,
@@ -22,7 +32,16 @@ const palettes = gradientHues.map(name => {
   }
 })
 
-export {colors, gradientHues, palettes, getPaletteByName}
+export {colors, colorModes, gradientHues, palettes, getPaletteByName}
+
+export const flattened = colorModes.reduce((acc, mode) => {
+  acc[mode] = flattenVars(allModeColors[mode])
+  return acc
+}, {})
+
+export const functionalVarNames = Object.keys(flattened.light).filter(
+  v => !v.startsWith('scale-') && !v.startsWith('auto-')
+)
 
 export const allColors = palettes.reduce((all, {values}) => all.concat(values), [])
 
@@ -41,3 +60,27 @@ export const allColors = palettes.reduce((all, {values}) => all.concat(values),
 function getPaletteByName(name) {
   return palettes.find(palette => palette.name === name)
 }
+
+function flattenVars(tree, prefix = []) {
+  let output = {}
+
+  for (const key of Object.keys(tree)) {
+    const val = tree[key]
+    const varName = [...prefix, key].join('-')
+    if (Array.isArray(val) && !varName.includes('shadow')) {
+      for (const i in val) {
+        const arrayVarName = `${varName}-${i}`
+        output[arrayVarName] = val[i]
+      }
+    } else if (Array.isArray(val)) {
+      output[varName] = val.join(' ')
+    } else if (typeof val === 'object') {
+      const obj = flattenVars(val, [...prefix, key])
+      output = {...output, ...obj}
+    } else {
+      output[varName] = val
+    }
+  }
+
+  return output
+}