Figma libraries

Design teams at GitHub use Figma as the single source of truth, collaboration, and exploration. Access to the GitHub Figma organization is currently only available to members of the GitHub team. Public access to any shared libraries and files is available from the Primer Figma Community page.

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

GitHub uses Figma to distribute Primer through team libraries. Each library covers a different part of the system, allowing a designer to only use what's needed. Any team within GitHub's Figma organization can create and distribute their own team/project specific libraries, but all of the core asset libraries for Primer can be found in the Primer team's "Core libraries (internal)" project or the primer community page. They include the following:

• Primer Primitives (internal | community): All of the color, type, and spacing styles used within Primer.
• Primer Web (internal | community): UI components used to design for GitHub's web interfaces.
• Primer Mobile (internal only): UI components used to design for GitHub's native mobile platforms.
• Octicons: GitHub's custom icon library.

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.

Navigate to the assets tab in the left sidebar and press the book icon to open the libraries overview.

Enable Primer Web and all other libraries you need in your file.

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.

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

Color variable panel with scope 'backgroundColor' and 'borderColor'.

Learn more about Figma variables

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.

Learn more about Figma components

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)

Interface templates

In addition to asset libraries for components and styles, you can also use template libraries to jump-start the design process.

• Primer Interfaces: Templates for common views and UI patterns found within GitHub's web product.
• Primer Email: Templates used to design product emails for GitHub.

Contributing

Currently only GitHub employees can contribute to Primer Web, due to how Figma handles open source files. To make changes you first need to create a branch from Primer Web and name it @username/changes-being-made. For example: @lukasoppermann/update-button-radius.

For more information, see Contributing to Figma.

Support

GitHub's Figma organization is currently maintained by GitHub's Design Infrastructure team. For any questions or comments please reach out to us either in our Slack #primer-figma channel or by submitting an issue in the github/primer repo.

For additional support specific to Figma, please reference the Figma Help Center.