Skip to content

Commit

Permalink
Merge pull request #1186 from primer/mkt/color-modes-docs
Browse files Browse the repository at this point in the history 
WIP: color modes docs
  • Loading branch information
@simurai
simurai committed Mar 11, 2021
2 parents bbd0cb6 + 1441170 commit 27555ac
Show file tree
Hide file tree
Showing 10 changed files with 522 additions and 42 deletions.
88 changes: 74 additions & 14 deletions docs/content/support/color-system.mdx
View file
Expand Up @@ -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}
Expand All @@ -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}`}
Expand All @@ -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>
Expand Down
262 changes: 262 additions & 0 deletions docs/content/support/v16-migration.mdx
View file
@@ -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)`
2 changes: 0 additions & 2 deletions docs/content/support/variables.mdx
View file
Expand Up @@ -5,9 +5,7 @@ status: Experimental
bundle: alerts
---

```
import {Variables, DeprecationIcon} from '../../src/variables'
```

> ⚠️ GitHub employees only! These color variables are deprecated and will be replaced at some point. On "_dotcom_" please use the [new functional variables](https://primer-css-git-mkt-color-modes-docs.primer.now.sh/css/support/color-system).
Expand Down

0 comments on commit 27555ac

Please sign in to comment.