Color

Color is a fundamental piece in the Primer visual language. In this guide you will learn about the principles, patterns, and abstractions that make Primer’s color system.

Get started

Image showing the two different types of color modes: light mode and dark mode

GitHub's UI offers a variety of different color modes. Every pattern in Primer is built to work across all color modes out of the box.

When designing product interfaces in Figma, we recommend using light mode. This is best because the Primer Figma components are only available in light mode. To preview your work in other modes, use the Figma color mode plugin.

How to use color for product UI

Primer delivers colors in the form of design tokens. Design tokens are a layer of abstraction that allows better maintainability, consistency and easy theming.

For example use bg-default for the background of the page and fg-default for the text color. If the user changes to dark mode, the underlying color that those tokens reference change, but the token names stay the same.

Same component shown in light mode and dark mode color palettes

Color design tokens are grouped based on their purpose:

  • Presentational: To represent a color. For example, the color steps in the Primer scale are named by color and lightness, such as scale.blue.5. These design tokens don't support color modes.
  • Functional: To convey a meaning or a state. For example, from a functional perspective the color green is used to reinforce positive messaging. In a functional system, green design tokens are named with the suffix .success.
  • Component: To represent a specific use case. For example, button.bg references from the system to be used as the background of a button component.

As the system grows, it will provide more APIs that fit different color needs. Check the Primer Primitives repository to follow along as we release new design tokens and systems.

Functional system

The functional system is based on the meaning, or purpose, that colors have in the interface. Use functional design tokens in designs and code to build product interfaces.

By using Primer's functional color system you make sure that your interface:

The functional system is structured into two groups of design tokens:

  • Foundations: Foregrounds (text and icons), backgrounds, and borders that make up most of a product interface.
Dark gray, midtone gray and light gray swatches as example of foundational colors
  • Color roles: Foregrounds (text and icons), backgrounds, and borders that highlight affordance or the meaning of elements in the UI.
Accent: blue, Success: green, Attention: yellow, Danger: red, Severe: orange, Open: green, Closed: red, Done: purple

Foregrounds

Foreground elements are text and icons. You can apply color to them by using any of the fg (short for foreground) design tokens.

FoundationsUsage
"" fg.defaultPrimary color for text and icons in any given interface. It should be used for body content, titles and labels.
"" fg.mutedUse for content that is secondary or that provides additional context but is not critical to understanding the flow of an interface.
"" fg.subtleUse for placeholder text, icons or decorative foregrounds.
"" fg.onEmphasisOn emphasis is the text color designed to combine with .emphasis backgrounds for optimal contrast.
Color rolesUsage
"" fg.accentUse for interactive text or icons like links or buttons.
"" fg.successUse to emphasize a positive message.
"" fg.attentionUse to highlight text or icons that require the user's attention.
"" fg.dangerUse to emphasize an error or a blocking status. Action is required.
"" fg.severeUse to emphasize a level of severity between attention and danger.
"" fg.openUse to style text that refers to open tasks or workflows.
"" fg.closedUse to style text that refers to closed tasks or workflows.
"" fg.doneUse to style text that refers to completed tasks or workflows.

Backgrounds

Background colors apply to surfaces of components or UI elements, such as pages, boxes, and overlays.

FoundationsUsage
"" bg.emphasisProvides the highest contrast against the default background, such as in tooltips.
"" bg.defaultPrimary background color.
"" bg.subtleProvides visual rest and contrast against the default background.
"" bg.insetCan be used instead of the default background to create a focal point, such as in conversations or activity feeds.
Color rolesUsage
"" bg.accentUse to accentuate interactive areas in the UI like selected elements.
"" bg.successUse to highlight a positive message.
"" bg.attentionUse to highlight elements that require a user's attention or pending statuses.
"" bg.dangerUse to emphasize an error or a blocking status, where action is required.
"" bg.severeUse to emphasize an extra level of severity between attention and danger.
"" bg.openUse to style text that refers to open tasks or workflows.
"" bg.closedUse to style text that refers to closed tasks or workflows.
"" bg.doneUse to style text that refers to completed tasks or workflows.
"" bg.[ANY_OF_ABOVE].emphasisUse to highlight the most important item of a view or an interface.

Borders

Borders can be used to group content or to create a visible separation between sections or items. They’re most commonly used on tables, side sections, and cards.

FoundationsUsage
"" border.defaultUse to create bounds around content, for example elements inside a card. Default borders are critical to understanding a page layout.
"" border.mutedUse for dividers to emphasize the separation between items, columns or sections.
Color rolesUsage
"" border.accentUse to accentuate interactive areas in the UI like selected elements.
"" border.successUse to highlight a positive message.
"" border.attentionUse to highlight elements that require a users attention or pending statuses.
"" border.dangerUse to emphasize an error or a blocking status. Action is required.
"" border.severeUse to emphasize an extra level of severity between attention and danger.
"" border.openUse to style text that refers to open tasks or workflows.
"" border.closedUse to style text that refers to closed tasks or workflows.
"" border.doneUse to style text that refers to completed tasks or workflows.
"" border.[ROLE].emphasisUse to highlight the most important item of a view or an interface.

Functional system in action

Table component showing the combination of bg.subtle with border.default, and border.muted

Example of pairing foundation tokens: bg.subtle with border.default, and border.muted.

UI demonstration of what bg.inset looks like. It darkens the background of the whole UI

Thinking in terms of elevation, bg.inset would represent an underground level. It's meant to create a feeling of focus or depth.

Example of a hover style on a list where the background uses bg.accent.emphasis and the text uses fg.onEmphasis.

fg.onEmphasis pairs with bg.[ANY_COLOR_ROLE].emphasis tokens. This example shows fg.onEmphasis paired with bg.accent.emphasis.

Green success alert with check icon, pairing bg.success, fg.success, and border.success color tokens

An example of an alert that pairs bg.success, fg.success, and border.success.

Combining colors

Not all colors pair well with each other. There are combinations of backgrounds and foregrounds that guarantee compliance with WCAG contrast guidelines and a wide range of hierarchical relationships between elements. Never use color on its own to convey a message or meaning. Pair it with explicit text and icons instead.

Pairing color roles

Do

Pair color role foregrounds with their background counterparts or with bg.default and bg.subtle.

Don’t

Never pair emphasis foregrounds with emphasis background.

Color roles and foregrounds

Do

Only use fg.muted with bg.default, bg.subtle, and bg.inset.

Don’t

Never use fg.muted on bg.emphasis or any of the color roles backgrounds.

Color roles recipes

Combination of design tokens 1: bg.[COLOR-ROLE] + border.[COLOR-ROLE] + fg.[COLOR-ROLE]Combination of design tokens 2: bg.[COLOR-ROLE] + border.[COLOR-ROLE].emphasis + fg.[COLOR-ROLE]Combination of design tokens 3: bg.default + border.[COLOR-ROLE].emphasis + fg.[COLOR-ROLE]Combination of design tokens 4: bg.[COLOR-ROLE] + border.[COLOR-ROLE] + fg.default

Accessibility

When designing with colors consider the following to make your UI visually accessible.

Assure adequate color contrast

Color contrast between text and its background must meet required WCAG standards.

The contrast requirements are:

  • 4.5:1 for normal text
  • 3:1 for large text (>24px)
  • 3:1 for UI elements and graphics
  • No contrast requirement for decorative and disabled elements

Use an online contrast checker or a Figma plugin to test your contrast.

If you work with the functional colors, this work has already been done for you. We checked all recommended combinations, so you are all set.

Don't rely on color alone

Show state with more than color

Color vision deficiency is different for different people. To make sure everyone can understand and use your UI you should show state with more than a change in color. For example by using icons or changing the content.

Example icon that uses a distinct shape in addition to color to indicate an error.

Connect labels to graphs with lines or patterns

For charts and graphs you can position the labels on top or close to each section. You can also use patterns to distinguish different parts.

Two graphs. One is a line graph and one is a pie graph. The line graph is demonstrating using unique shapes for each comparison line's plot symbol. The pie chart is demonstrating how each slice's label can use a line to point to its corresponding slide.

Color outside the functional system

Primer does not currently provide a presentational or data visualization color system. If you or your team at GitHub are working on a feature that has color needs beyond the functional system, please open an issue in the github/primer repository (only available to GitHub staff).

How to use colors in Primer libraries?

Primer colors exist in different formats and are made available throughout the Primer libraries and tools. Not all colors exist everywhere and the naming depends on the Primer library. Below is a list to help find the right Primer color documentation that is specific to that role and environment.

I amDocumentationExample color usage
A product designer working in FigmaPrimer Primitivesbg/accent
An engineer using Primer ViewComponentscolor system argumentsbg: :accent
An engineer using Primer Reactsx propsaccent.subtle
An engineer creating custom UIPrimer CSS color utilitiescolor-bg-accent
A Primer React maintainer creating a componentPrimer Primitives js propertiesaccent.subtle
A Primer CSS maintainer creating a componentPrimer Primitives css variables--color-accent-subtle

Stuck choosing the right color? Feel free to reach out in the #primer Slack channel.