2021-03-26 02:11:16 +03:00
---
2021-03-29 17:52:48 +03:00
title: Primer v16 migration guide
2021-03-26 02:11:16 +03:00
description: 'Guide for migrating to version 16.0.0 of Primer'
---
2021-03-25 21:10:52 +03:00
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.
2021-03-26 02:11:16 +03:00
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.
2021-03-25 21:10:52 +03:00
2021-03-29 17:52:48 +03:00
## Components
2021-03-25 21:10:52 +03:00
2021-03-29 17:52:48 +03:00
Most components don't need to be updated and should work without making changes. However some components that use presentational class names now use functional class names.
2021-03-25 21:10:52 +03:00
2021-03-29 17:52:48 +03:00
### Buttons
2021-03-25 21:10:52 +03:00
| `v15` | `v16` |
| ----------- | ----- |
| `.btn-blue` | n/a |
2021-03-29 17:52:48 +03:00
### Counters
2021-03-25 21:10:52 +03:00
2021-03-26 02:11:16 +03:00
| [`v15`](https://primer.style/css/components/labels#counters) | `v16` |
2021-03-25 21:10:52 +03:00
| ------------------------------------------------------------ | --------------------- |
| `.Counter--gray` | `.Counter--primary` |
| `.Counter--gray-light` | `.Counter--secondary` |
2021-04-30 19:04:10 +03:00
### Dropdown
2021-03-25 21:10:52 +03:00
2021-03-26 02:11:16 +03:00
| [`v15`](https://primer.style/css/components/dropdown#dark) | `v16` |
2021-03-25 21:10:52 +03:00
| ---------------------------------------------------------- | ----- |
| `.dropdown-menu-dark` | n/a |
2021-03-29 17:52:48 +03:00
### Labels
2021-03-25 21:10:52 +03:00
2021-03-26 02:11:16 +03:00
| [`v15`](https://primer.style/css/components/labels) | `v16` |
2021-03-25 21:10:52 +03:00
| --------------------------------------------------- | ------------------- |
| `.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 |
2021-03-29 17:52:48 +03:00
### States
2021-03-25 21:10:52 +03:00
2021-03-26 02:11:16 +03:00
| [`v15`](https://primer.style/css/components/labels#states) | `v16` |
2021-03-25 21:10:52 +03:00
| ---------------------------------------------------------- | ---------------- |
| n/a | `.State--draft` |
| `.State--green` | `.State--open` |
| `.State--purple` | `.State--merged` |
| `.State--red` | `.State--closed` |
2021-03-29 17:52:48 +03:00
## Utility classes
2021-03-25 21:10:52 +03:00
2021-03-29 17:52:48 +03:00
See [color utility classes](/utilities/colors) for a list of all the functional color utility classes.
2021-03-25 21:10:52 +03:00
2021-03-29 17:52:48 +03:00
### Text
2021-03-25 21:10:52 +03:00
2021-03-26 02:11:16 +03:00
| [`v15`](https://primer.style/css/utilities/colors#text-color-utilities) | `v16` |
2021-03-25 21:10:52 +03:00
| ----------------------------------------------------------------------- | ----------------------- |
| `.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 |
2021-03-29 17:52:48 +03:00
### Icon
2021-03-25 21:10:52 +03:00
| `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` |
2021-03-29 17:52:48 +03:00
### Border
2021-03-25 21:10:52 +03:00
2021-03-26 02:11:16 +03:00
| [`v15`](https://primer.style/css/utilities/borders#border-color-utilities) | `v16` |
2021-03-25 21:10:52 +03:00
| -------------------------------------------------------------------------- | ------------------------- |
| `.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 |
2021-03-29 17:52:48 +03:00
### Background
2021-03-25 21:10:52 +03:00
2021-03-26 02:11:16 +03:00
| [`v15`](https://primer.style/css/utilities/colors#background-utilities) | `v16` |
2021-03-25 21:10:52 +03:00
| ----------------------------------------------------------------------- | --------------------------- |
| `.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 |
2021-03-29 17:52:48 +03:00
### Shadow
2021-03-25 21:10:52 +03:00
| `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` |
2021-03-29 17:52:48 +03:00
### Link
2021-03-25 21:10:52 +03:00
The `link` utilities are part of the `Link` component.
2021-03-26 02:11:16 +03:00
| [`v15`](https://primer.style/css/utilities/colors##link-colors) | `v16` |
2021-03-25 21:10:52 +03:00
| --------------------------------------------------------------- | ------------------ |
| `.link-gray-dark` | `.Link--primary` |
| `.link-gray` | `.Link--secondary` |
| `.muted-link` | `.Link--muted` |
| `.link-hover-blue` | `.Link--onHover` |
| n/a | `.Link` |
2021-03-29 17:52:48 +03:00
## Mixins
2021-03-25 21:10:52 +03:00
| `v15` | `v16` |
| --------------- | ----- |
| `btn-solid()` | n/a |
| `btn-inverse()` | n/a |
| `btn-outline()` | n/a |
2021-03-29 17:52:48 +03:00
## Variables
2021-03-25 21:10:52 +03:00
2021-03-29 17:52:48 +03:00
See [color system](/support/color-system) for a list of all the functional CSS variables.
2021-03-25 21:10:52 +03:00
2021-03-29 17:52:48 +03:00
### Text
2021-03-25 21:10:52 +03:00
| `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 |
2021-03-29 17:52:48 +03:00
### Icon
2021-03-25 21:10:52 +03:00
| `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)` |
2021-03-29 17:52:48 +03:00
### Border
2021-03-25 21:10:52 +03:00
| `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 |
2021-03-29 17:52:48 +03:00
### Background
2021-03-25 21:10:52 +03:00
| `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 |
2021-03-29 17:52:48 +03:00
### Shadow
2021-03-25 21:10:52 +03:00
| `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)` |
2021-03-29 17:52:48 +03:00
## Color system
2021-03-25 21:10:52 +03:00
| `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)` |
2021-03-29 17:52:48 +03:00
## Auto colors
2021-03-25 21:10:52 +03:00
| `v15` | `v16` |
| ----- | -------------------------- |
| n/a | `var(--color-auto-black)` |
| n/a | `var(--color-auto-white)` |
| n/a | `var(--color-auto-gray-0)` |
| n/a | `var(--color-auto-gray-1)` |
| n/a | `var(--color-auto-gray-2)` |
| ... | ... |
| n/a | `var(--color-auto-pink-7)` |
| n/a | `var(--color-auto-pink-8)` |
| n/a | `var(--color-auto-pink-9)` |
2021-03-29 17:52:48 +03:00
Note: The `auto` colors automatically invert based on the color mode. Example:
2021-03-25 21:10:52 +03:00
| Variable | In `light` mode | In `dark` mode |
| -------------------------- | --------------- | -------------- |
| `var(--color-auto-gray-0)` | light gray | dark gray |
| `var(--color-auto-gray-9)` | dark gray | light gray |
2021-03-29 17:52:48 +03:00
This doesn't work perfectly all the time, so you should use functional variables as much as possible. But in some cases auto colors can still be handy.
2021-03-25 21:10:52 +03:00
2021-03-29 17:52:48 +03:00
## Misc
2021-03-25 21:10:52 +03:00
2021-04-07 07:53:24 +03:00
A few more selectors and variables were removed. Please refer to [deprecations.js](https://github.com/primer/css/blob/main/deprecations.js) for a complete list.
