✨ Introducing Primer Primitives v8.0! ✨

[lukasoppermann]

Note

This was moved over from primer/primitives as we close discussions over there.

Primitives v8.0 introduces a re-imagined design token build process, a token naming convention, and new tokens to handle sizing, spacing and typography. These changes have been tested behind the scenes for the past year, and are now becoming the default experience with this major release.

New features and improvements

• Primitives now utilizes Style Dictionary, improving the contribution experience and allowing for customization and token transformation
• Color themes are directly available for consumption via dist, whereas previously they needed to be consumed through Primer CSS
• New size and typography tokens built with rem units
• All tokens follow a naming convention for a more predictable experience both contributing and consuming values
• Testing and linting to ensure proper color contrast for complementary color tokens

Breaking changes

• scale color tokens are abstracted from the built color CSS, and only used internally
• Removes support for js, scss, ts output
• Color tokens have been renamed to match our naming convention

Upgrade guide

Upgrading from v7 to v8

npm install @primer/primitives@latest

Everything new in v8 is available in v7 today. If you would prefer to do a slower upgrade, you can start importing new colors and variables from dist before bumping to v8:

Sizing, spacing & typography

@import '@primer/primitives/dist/css/base/size/size.css';
@import '@primer/primitives/dist/css/base/typography/typography.css';
@import '@primer/primitives/dist/css/functional/size/border.css';
@import '@primer/primitives/dist/css/functional/size/breakpoints.css';
@import '@primer/primitives/dist/css/functional/size/size-coarse.css';
@import '@primer/primitives/dist/css/functional/size/size-fine.css';
@import '@primer/primitives/dist/css/functional/size/size.css';
@import '@primer/primitives/dist/css/functional/size/viewport.css';
@import '@primer/primitives/dist/css/functional/typography/typography.css';

Colors

@import '@primer/primitives/dist/css/functional/themes/light.css';
@import '@primer/primitives/dist/css/functional/themes/light-tritanopia.css';
@import '@primer/primitives/dist/css/functional/themes/light-high-contrast.css';
@import '@primer/primitives/dist/css/functional/themes/light-colorblind.css';
@import '@primer/primitives/dist/css/functional/themes/dark.css';
@import '@primer/primitives/dist/css/functional/themes/dark-colorblind.css';
@import '@primer/primitives/dist/css/functional/themes/dark-dimmed.css';
@import '@primer/primitives/dist/css/functional/themes/dark-high-contrast.css';
@import '@primer/primitives/dist/css/functional/themes/dark-tritanopia.css';

CSS and SCSS usage

If you're consuming Primer themes via Primer CSS with .scss files:

• Remove Primer CSS theme imports
• Import colors from primer/primitives (see imports above)
• For autofixing name changes, utilize our custom stylelint plugin to provide a suitable replacement value

Using stylelint to autofix color token names

npm install @primer/stylelint-config@latest

In your stylelint config file, add the following plugins:

"plugins": ["@primer/stylelint-config/plugins/no-deprecated-colors"]
"rules": {
    "primer/no-deprecated-colors": true
  }

If you would like to do a slower upgrade to v8, you can use this flag with no-deprecated-colors which will provide a fallback value:

'primer/no-deprecated-colors': [
    true,
    {
      inlineFallback: true,
    },
  ],

Using inlineFallback will result in something like this, where the new color var has fallback value to the old:

color: var(--fgColor-default, var(--color-fg-default));

React usage

If you're consuming Primer themes via Primer React, you will notice the existing themes now reference CSS variables under the hood with a fallback value. Consider importing the CSS file imports listed above into your app to take advantage of these new values.

sx prop

If you're already referencing CSS variables as a string via the sx prop, you can use our custom eslint plugin to help autofix to the new color variables.

npm install --save-dev eslint-plugin-primer-react

Reference the plugin in your eslint config:

primer-react/new-color-css-vars

If you would like to do a slower upgrade to v8, you can use the new-color-css-vars-have-fallback plugin which will provide a fallback value:

'primer-react/new-color-css-vars-have-fallback': 2,

Using the fallback plugin will result in something like this:

<Button sx={{color: 'var(--fgColor-muted, var(--color-fg-muted))'}}>Test</Button>

Color scale usage

In v8.0, the range of scale colors such as --color-scale-red-x have been removed from the dist files. This change is designed to better enforce proper color contrast between foreground and background colors. Our functional color tokens were designed to not only handle theming and color mode changes, but ensure adequate contrast when they are combined.

If you're currently using scale colors directly, you can reference our color documentation to find the next closest functional color variable to swap in.

Documentation

See Primer Primitives documentation for more detailed guidelines and lists of available CSS variables.

For a more detailed explanation of our color system, check out the color documentation.

Support

If you have any issues upgrading or need help finding replacement color tokens for legacy values, feel free to comment on this discussion or open an issue!