To get started using Primer Primitives, install the package with your package manager of choice:
npm:
npm install @primer/primitives
yarn:
yarn add @primer/primitives
Primer Primitive design tokens are available to consume as CSS variables. Import the desired token files into the root of your project.
For sizing, spacing and typography tokens, import the following files:
@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';
Color tokens are grouped by individual theme files:
@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';
Utilizing CSS variables in SCSS or CSS files:
.Text {color: var(--fgColor-default);}
Utilizing CSS variables in React with Primer React (styled components):
<Text sx={{color: 'var(--fgColor-default)'}}></Text>
Note: legacy variables in Primer React from the theme
object all resolve to CSS variables under the hood. While the new naming convention is not available as a JS object, you can continue using the legacy variables in your React components or switch to using CSS variables directly (recommended).
Primer color design tokens are made available within data-attribute selectors on the body
tag or other high level dom element. There are three distinct data-attributes used to handle theming: data-color-mode
, data-light-theme
, and data-dark-theme
.
The data-color-mode
attribute is used to set the color mode of the theme. The value of the attribute should be either auto
, light
, or dark
. When set to auto
, the theme will automatically switch between light and dark based on the user's system preferences.
The data-light-theme
and data-dark-theme
attributes are used to set the theme. The value of the attribute should be the name of the theme file, replacing dashes -
with underscore _
. For example, to use the light theme, set the data-light-theme
attribute to light
.
<body data-color-mode="light" data-light-theme="light" data-dark-theme="dark">
To see theming in action, toggle between the theme in the following example:
light
light_tritanopia
light_high_contrast
light_colorblind
dark
dark_colorblind
dark_dimmed
dark_high_contrast
dark_tritanopia
To see all available tokens, reference the following guides: