---
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.

## Components

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.

### Buttons

| `v15`       | `v16` |
| ----------- | ----- |
| `.btn-blue` | n/a   |

### Counters

| [`v15`](https://primer.style/css/components/labels#counters) | `v16`                 |
| ------------------------------------------------------------ | --------------------- |
| `.Counter--gray`                                             | `.Counter--primary`   |
| `.Counter--gray-light`                                       | `.Counter--secondary` |

### Dropdown

| [`v15`](https://primer.style/css/components/dropdown#dark) | `v16` |
| ---------------------------------------------------------- | ----- |
| `.dropdown-menu-dark`                                      | n/a   |

### 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                 |

### 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 [color utility classes](/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`   |
| `.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`            |

## Mixins

| `v15`           | `v16` |
| --------------- | ----- |
| `btn-solid()`   | n/a   |
| `btn-inverse()` | n/a   |
| `btn-outline()` | n/a   |

## Variables

See [color system](/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)`   |
| `$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)` |

## Auto colors

| `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)` |

Note: The `auto` colors automatically invert based on the color mode. Example:

| 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     |

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.

## Misc

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.