Getting started

What are Figma libraries?

Figma libraries contain UI components and design tokens (variables and styles). At GitHub we have one product design system library called Primer Web that our teams at GitHub use to design GitHub. The components contained within Primer match what is available for developers in Primer React Components, Primer ViewComponents, and Primer CSS.

Installation

To use a library in Figma enable (install) it from the assets tab (option + 2). You can also directly open the team library view via the command palette or with the shortcut option + cmd + o.

Styles and variables

Styles and variables are two ways to use Primer Primitives (design tokens) in Figma. Our goal is to move everything over to variables, but at the moment only color and size tokens are supported. This is why we still provide text and shadow tokens using styles.

Understanding styles

Figma libraries like Primer Web provide styles for you to use. In contrast to local styles, styles from a library don't show up in the sidebar. However, once you open a selection to choose a text style or shadow style you will see the styles from team libraries as well.

Available styles:

• text styles
• shadow styles

To quickly find a style you can use the search box. E.g. search for body to bring up all body text styles as well as related ones.

Understanding variables (primitives)

Our Figma libraries use variables to represent design tokens. Variables from a library don't show up in the sidebar. However once you open a selection to choose a color, or size, etc. you will see the variables from team library as well.

To use the variables you need to enable the Primer Web library in your file.

Available variables:

• color variables
• size variables

To quickly find a variable you can use the search box. E.g. use accent to bring up all accent colors or fgColor to find all text related colors.

Scope

Variables in Figma are "scoped", meaning they can only be used in specific situations. Currently Figma offers the following scopes for color variables: Frame fill, Shape fill, Text fill , Stroke.

For you this means that if you want to create a border using a borderColor you need to use a stroke (path tool) or a border around a frame or shape. Similarly fgColors can not be used for borders and bgColors can only be used for frame fills and shape fills.

Note: There are two exceptions to this rule.

1. Some bgColors are available for borders and strokes because we use them when placing things like notification dots on top of elements like an avatar.
2. fgColors are also available for shape fill. This is nessary because icons are shapes, but use fgColors

Variables vs. styles

Variables and styles are fairly similar, but there are some key differences. You can identify a color variables by the squared color representation and a style by the round one.

Styles can be used for color, grids and shadows. The can have multiple colors, pictures or gradients combined in one style and they can be replaced using the style swap utility. However they can not be nested.

Variables are more similar to design tokens in that they can only have a single raw value, either a color, string or number. However they can reference another valid variable e.g. the variable fgColor/danger can reference base/color/red/4. This makes variables a better choice to represent design tokens.

Understanding components

At GitHub, we have created a set of guidelines that contributors and maintainers can reference when creating and updating components.

Components in our libraries have been built to be easy to understand for consumers. When possible try to keep components small and simple. Avoid advanced methods/tricks if possible.

Variants and component properties

To make components dynamic, we favor component properties over nesting, so users don't have to override parts of a component manually.

Whenever possible use components as they are without detaching.

Using variable themes

Primer Web provides light mode and dark mode using figma variables. This means you don't need a plugin to change between modes. Simply select any frame that uses variables or components with variables. Select the mode from the dropdown in the layer section in the right sidebar

Video introduction to primer web variables and modes / themes (GitHub staff only)