primer/css
1
1
Fork 0
mirror of https://github.com/primer/css.git synced 2025-01-05 21:22:57 +03:00
Code Issues Projects Releases Wiki Activity

Flesh out color system, add (temporary) migration guide doc

Browse Source
This commit is contained in:
Michelle Tilley 2020-10-28 08:46:59 -07:00
parent 5711c3a85c
commit a24bbd15cc
No known key found for this signature in database
GPG Key ID: 810E3A96D4CF00F4
3 changed files with 341 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
docs/content/support/color-system.mdx
View File

@ -12,11 +12,12 @@ 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 the CSS color variables in custom CSS.
When at all possible, favor using [color utility classes](/utilities/colors) over using custom CSS to set colors.
<Flash scheme="yellow">
@ -46,20 +47,39 @@ Note: because the new Primer CSS color system is based on *functional* colors, y
}}
/>
---
### Borders
<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
}, {})
}))}
<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://primitives-git-mkt-color-modes.primer.vercel.app/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.

307
docs/content/support/v16-migration.mdx Normal file
View File

@ -0,0 +1,307 @@
---
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. However, some of the components that use presentational class names now use functional class names instead.
#### 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/color) 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-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`
`.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`
`.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-white` (`$white`) | `var(--color-text-inverse)`
`$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)`
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)`
`$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)`
`$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)`
## Workflow guide
> I have a new pattern to add that isn't in Primer, I've gotten the spec from my designer which lists the CSS functional variables I should use. What do I do now?
If you have a list of the relevant functional variables, you can use them to implement your design by either applying the appropriate functional utility classes:
```html
<div class="color-text-primary">...</div>
```
Or, if that's not possible, using the CSS variable in a CSS or Sass file:
```sass
.MyFeature .my-element {
&:hover {
color: var(--color-text-primary);
}
}
```
As when introducing any pattern that doesn't exist in Primer, it is worth reaching out to `#design-systems` to discuss potentially adding the pattern to Primer.
> I have a new pattern that isn't in Primer, I have the system colors it needs to map to in light and dark mode, now what do I do?
Primer exports CSS variables for [the color scale](/support/color-system#color-palette); note that these colors differ in the various color modes, so you'll need to define a *new* app-level variable that references the built-in scale variables.
As an example, imagine you've been given the light mode system color `blue-5` and the dark mode system color `blue-3`.
1. Add a new variable to `app/assets/stylesheets/hacks/hx_color-modes.scss` using the `color-mode-var` mixin:
```sass
@include color-mode-var(
'my-feature-name',
var(--color-scale-blue-5),
var(--color-scale-blue-3)
)
```
2. Reference the newly created variable prefixed with `--color-` in your implementation.
```sass
.MyFeature .my-element {
color: var(--color-my-feature-name);
}
```
As when introducing any pattern that doesn't exist in Primer, it is worth reaching out to `#design-systems` to discuss potentially adding the pattern to Primer.
> I'm designing a new pattern that doesn't exist in Primer, I want to see if there are functional colors I can use that work for my new pattern, where do I find these and how can I test them in my design?
...
> I'm desinging a new pattern that doesn't yet exist in Primer, it doesn't look like there are functional variables that work for it, what do I do next?
...

2
docs/src/@primer/gatsby-theme-doctocat/nav.yml
View File

@ -18,6 +18,8 @@
url: /support/marketing-variables
- title: Variables
url: /support/variables
- title: v16 Migration Guide
url: /support/v16-migration
- title: Utilities
url: /utilities
children: