Skip to content
Primer Design System

Primer Design System

UI color system

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.

On this page

On this page

Overview

Comparative display of GitHub interface elements in light and dark modes. The light mode shows a browser window with a light background, green contribution graph, and standard browser controls. The dark mode presents the same design with a dark background, enhancing the visibility of green contribution graph and browser controls.

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. You can learn more about using design tokens in Figma in our Figma guidelines.

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.

GitHub Wiki page theming comparison. On the left, a light theme featuring a card with a welcome message, a green 'Create the first page' button, and annotated with 'fgColor-default' for foreground and 'bgColor-default' for background colors. On the right, the same card is shown in dark mode with the text and button colors adjusted for contrast, also annotated with color roles.

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.

Color design guide for GitHub interface elements showing a transition from a base color, a magenta (#bf3989) to a functional color name 'color-scale-pink-5', and then to 'borderColor-sponsors-emphasis'. Below the base color, a color scale from 0 to 9 shows varying shades of pink. Two button examples demonstrate the practical application of the colors: one in a light theme with 'Sponsor' text and heart icon and another in a dark theme with the same elements.

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

GitHub interface component patterns displaying color coding for UI elements. On the left, a red border box indicates 'borderColor-danger-emphasis' changing to 'control-borderColor-danger'. On the right, a blue border box signifies 'borderColor-accent-emphasis' transitioning to 'focus-outlineColor'. Examples include text input fields for an email address with error messages and toggle switches in both light and dark themes.

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

Shades of gray used for text, borders, backgrounds, and shadows.

Foreground

Foreground tokens use the fgColor property and are used for text and icons.

GitHub pull request interface demonstrating foreground color roles in light and dark themes. Both themes highlight text 'Guidelines #798' in 'fgColor-default', the 'Draft' label in 'fgColor-onEmphasis', and a clickable username in 'fgColor-link'. The light theme uses 'fgColor-muted' for auxiliary text, mirrored in the dark theme for contrast optimization.

Background

Background tokens use the bgColor property and are used for backgrounds and fills.

GitHub's navigation menu in light and dark themes, annotated to indicate background color roles. In light mode, the menu has 'bgColor-inset' for the avatar circle, 'bgColor-emphasis' for the 'Pull requests' button, 'overlay-bgColor' for hover effects, 'bgColor-muted' for inactive menu items, and 'bgColor-default' for the overall background. The dark mode mirrors this scheme with appropriate colors for visibility.

Border

Border tokens use the borderColor property and are used for borders and dividers.

GitHub interface dropdown menu with border color annotations in light and dark themes. In light mode, the dropdown is outlined with 'borderColor-default', while menu options are separated by 'borderColor-muted'. In dark mode, the same color roles apply with adjusted shades for contrast.

Shadow

Shadow tokens use the shadow property and are used for shadows and elevation.

GitHub interface design elements annotated with shadow styles: 'shadow-floating-small', 'shadow-resting-xsmall', and 'shadow-inset', displayed on light and dark mode backgrounds.

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.

Overview of GitHub UI color roles in light and dark themes. Each theme displays labeled color swatches for: 'accent-emphasis' in blue, 'accent-muted' in light blue, 'success-emphasis' in green, 'success-muted' in light green, 'danger-emphasis' in red, 'danger-muted' in light red, 'warning-emphasis' in yellow, 'warning-muted' in light yellow, 'done-emphasis' in purple, 'done-muted' in light purple, 'sponsor-emphasis' in magenta, and 'sponsor-muted' in light magenta.

Muted

Muted background and border colors are often combined to draw attention to a specific piece of content with a subtle emphasis.

GitHub interface elements showing a warning message and a user comment in both light and dark modes. The warning message has a yellow background with a caution icon and is dismissible with a close button. The user comment by 'monalisa' features a speech bubble with a light blue background in light mode and a dark blue background in dark mode, both with muted borders.

Emphasis

Emphasis background colors provide a stronger emphasis for UI elements and are always combined with fgColor-onEmphasis tokens for text and icons.

GitHub interface showcasing button styles with emphasis colors in light and dark modes. The 'Primary' button is green, the 'Danger' button is red with a trash icon, the 'Queued' button is brown with a clock icon, and the 'Beta' button is outlined in green. Annotations indicate 'borderColor-{role}-emphasis' and 'bgColor-{role}-emphasis' for each button style.

Semantic foreground

Foreground semantic colors provide contrast against muted and default background colors and should be used for text and icons.

GitHub interface elements displaying in light and dark themes with foreground color roles. Tags include 'Sponsor' with a heart icon, 'Verified' with a checkmark, and language tags 'css' and 'ruby'. The colors of text and icons are adjusted according to the theme for optimal contrast, annotated with 'fgColor-{role}'.

Color roles

Color rolesUsage
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 references below for more information.