Color usage
Color is a fundamental part of Primer's visual language. In this guide you will learn about the principles, patterns, and abstractions that make up Primer’s color system.
Overview
GitHub's UI offers two color modes, light and dark. Primer supports both color modes across nine themes. Every pattern in Primer is built to work across all color modes out of the box.
Color modes in Figma
When designing product interfaces in Figma, we recommend using light mode or dark mode as the Primer Web Figma library provides components and tokens in those two modes.
Color design tokens
Primer delivers colors in the form of design tokens. Design tokens are a layer of abstraction that allows for better maintainability, consistency and theming. Within Primer, design tokens are represented as CSS variables for code and Figma variables for design. For a full reference table of all available design tokens, see the color CSS variables page.
As an example of how color tokens work, when bgColor-default is referenced for a background color, the value of that token will automatically change depending on the color mode.
Design token categories
Primer design tokens are categorized into three groups:
- Base
- Functional
- Component/pattern
To read more about the naming convention, see the design token naming guidelines page.
Base color tokens are the lowest level tokens and map directly to a raw value. They are only to be used as a reference for functional and component/pattern tokens. Base color tokens don't respect color modes and should never be used directly in code or design.
Example: color-scale-pink-5
Functional color tokens represent global UI patterns such as text, borders, shadows, and backgrounds. These are the most commonly used design tokens throughout all of Primer and GitHub UI. Functional color tokens reference base color tokens under the hood, and respect color modes.
Example: borderColor-sponsors-emphasis
Component/pattern tokens are used for values that are more specific or unique than functional tokens. These tokens are limited and functional tokens are preferred. Component/pattern color tokens may reference both base and functional tokens under the hood, and respect color modes.
Example: focus-outlineColor
Neutral colors
Primer's neutral scales offer shades of gray between 0 and 13, including white and black. There are two versions of the neutral scale: light, and dark.
The light and dark scale directions are inverted, with the light scale starting with white and the dark scale starting with black. By inverting the scales, light and dark themes are able to share many of the same functional color tokens without custom overrides.
Background
The first six steps of the neutral scales are typically used for background colors. The two most commonly used background colors are bgColor-default and bgColor-muted. All contrast values for text and borders are calculated against bgColor-muted to ensure proper contrast ratios for both muted and default.
For control components with state, the scale accommodates rest, hover, and active.
Borders and dividers
Steps 7 and 8 are typically used for borders and dividers in the default light/dark themes. Step 8 is considered the minimum contrast value for interactive control borders against bgColor-muted.
Text and icons
Steps 9 and 10 are typically used for text and icons. Step 9 is considered the minimum contrast value for text against steps 0 through 4, while 10 meets the minimum against 5 and 6.
Adjusting contrast
Contrast levels can be adjusted by moving up or down the scale. For example, the light high contrast theme utilizes steps 2 through 7 for backgrounds, 10 for borders, and 11 to 13 for text.
For high contrast themes, the goal is to hit a minimum of 7:1 for most text and interactive elements. If a softer background color must be used, make use of borders around elements to increase contrast.
Semantic colors
Semantic colors are typically used to communicate status, action, or emphasis. Each semantic color is tied to a role with a specific meaning. Color tokens are available for foreground, background, and border. Background and border colors have both a muted and emphasis option.
Muted
Muted background and border colors are often combined to draw attention to a specific piece of content with a subtle emphasis.
Emphasis
Emphasis background colors provide a stronger emphasis for UI elements and are always combined with fgColor-onEmphasis tokens for text and icons.
Semantic foreground
Foreground semantic colors provide contrast against muted and default background colors and should be used for text and icons.
Base colors
Base color values should only be used to construct functional and component/pattern design tokens, never used directly in code
Use the theme menu to see how the base scales change per theme.
Color roles
| Color roles | Usage |
|---|---|
accent | Links, selected, active, and focus states, and neutral information |
success | Primary buttons, positive messaging and successful states |
attention | Warning states, active processes such as queued PRs and tests in progress |
danger | Danger buttons and error states |
open | Open tasks, PRs or workflows |
closed | Closed tasks, PRs or workflows |
done | Completed tasks, PRs or workflows |
sponsors | Text and icons related to GitHub Sponsors |
Developers
Colors are available in the form of CSS variables and CSS utility classes that can be used across all frameworks including React and Rails. Check out the color CSS variables for more information.