css/docs/content/utilities/colors.mdx

---
title: Colors
description: 'Immutable, atomic CSS classes to rapidly build product'
status: Stable
status_issue: 'https://github.com/github/design-systems/issues/97'
---

import {Box, BorderBox} from '@primer/components'
import {palettes, allColors} from '../../src/color-variables'
import {PaletteTable, PaletteTableFragment, PaletteHeading, PaletteCell, PaletteValue} from '../../src/color-system'

Use color utilities to apply color to the background of elements, text, and borders.

## Text colors

Use text color utilities to set text to a specific color. Color contrast must pass a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). This ensures that viewers who cannot see the full color spectrum are able to read the text. To customize outside of the suggested combinations below, we recommend using this [color contrast testing tool](https://colorable.jxnblk.com/). For more information, read our [accessibility standards](../principles/accessibility).

> ⚠️ The `.text-warning` currently doesn't pass accessibility standards, but will be updated in the future. **Use with caution**.

```html live
<div class="text-primary mb-2">.text-primary</div>
<div class="text-secondary mb-2">.text-secondary</div>
<div class="text-tertiary mb-2">.text-tertiary</div>
<div class="text-success mb-2">.text-success</div>
<div class="text-warning mb-2">.text-warning <span class="tooltipped tooltipped-n" aria-label="Does not meet accessibility standards">⚠️</span></div>
<div class="text-danger mb-2">.text-danger</div>
```

You can set the color inheritance on an element by using the `text-inherit` class.

```html live
<div class="text-success">This text is purple, <a href="#" class="text-inherit">including the link</a></div>
```

## Icon colors

Use icon color utilities to set [Octicons](https://primer.style/octicons) to a specific color.

```html live
<div class="mb-2">
  <!-- <%= octicon "octoface", :height => 16, :class => "icon-primary mr-1" %> -->
  <svg class="icon-primary mr-1 octicon octicon-octoface" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M1.326 1.973a1.2 1.2 0 011.49-.832c.387.112.977.307 1.575.602.586.291 1.243.71 1.7 1.296.022.027.042.056.061.084A13.22 13.22 0 018 3c.67 0 1.289.037 1.861.108l.051-.07c.457-.586 1.114-1.004 1.7-1.295a9.654 9.654 0 011.576-.602 1.2 1.2 0 011.49.832c.14.493.356 1.347.479 2.29.079.604.123 1.28.07 1.936.541.977.773 2.11.773 3.301C16 13 14.5 15 8 15s-8-2-8-5.5c0-1.034.238-2.128.795-3.117-.08-.712-.034-1.46.052-2.12.122-.943.34-1.797.479-2.29zM8 13.065c6 0 6.5-2 6-4.27C13.363 5.905 11.25 5 8 5s-5.363.904-6 3.796c-.5 2.27 0 4.27 6 4.27z"></path><path d="M4 8a1 1 0 012 0v1a1 1 0 01-2 0V8zm2.078 2.492c-.083-.264.146-.492.422-.492h3c.276 0 .505.228.422.492C9.67 11.304 8.834 12 8 12c-.834 0-1.669-.696-1.922-1.508zM10 8a1 1 0 112 0v1a1 1 0 11-2 0V8z"></path></svg>
  .icon-primary
</div>
<div class="mb-2">
  <!-- <%= octicon "octoface", :height => 16, :class => "icon-secondary mr-1" %> -->
  <svg class="icon-secondary mr-1 octicon octicon-octoface" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M1.326 1.973a1.2 1.2 0 011.49-.832c.387.112.977.307 1.575.602.586.291 1.243.71 1.7 1.296.022.027.042.056.061.084A13.22 13.22 0 018 3c.67 0 1.289.037 1.861.108l.051-.07c.457-.586 1.114-1.004 1.7-1.295a9.654 9.654 0 011.576-.602 1.2 1.2 0 011.49.832c.14.493.356 1.347.479 2.29.079.604.123 1.28.07 1.936.541.977.773 2.11.773 3.301C16 13 14.5 15 8 15s-8-2-8-5.5c0-1.034.238-2.128.795-3.117-.08-.712-.034-1.46.052-2.12.122-.943.34-1.797.479-2.29zM8 13.065c6 0 6.5-2 6-4.27C13.363 5.905 11.25 5 8 5s-5.363.904-6 3.796c-.5 2.27 0 4.27 6 4.27z"></path><path d="M4 8a1 1 0 012 0v1a1 1 0 01-2 0V8zm2.078 2.492c-.083-.264.146-.492.422-.492h3c.276 0 .505.228.422.492C9.67 11.304 8.834 12 8 12c-.834 0-1.669-.696-1.922-1.508zM10 8a1 1 0 112 0v1a1 1 0 11-2 0V8z"></path></svg>
  .icon-secondary
</div>
<div class="mb-2">
  <!-- <%= octicon "octoface", :height => 16, :class => "icon-tertiary mr-1" %> -->
  <svg class="icon-tertiary mr-1 octicon octicon-octoface" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M1.326 1.973a1.2 1.2 0 011.49-.832c.387.112.977.307 1.575.602.586.291 1.243.71 1.7 1.296.022.027.042.056.061.084A13.22 13.22 0 018 3c.67 0 1.289.037 1.861.108l.051-.07c.457-.586 1.114-1.004 1.7-1.295a9.654 9.654 0 011.576-.602 1.2 1.2 0 011.49.832c.14.493.356 1.347.479 2.29.079.604.123 1.28.07 1.936.541.977.773 2.11.773 3.301C16 13 14.5 15 8 15s-8-2-8-5.5c0-1.034.238-2.128.795-3.117-.08-.712-.034-1.46.052-2.12.122-.943.34-1.797.479-2.29zM8 13.065c6 0 6.5-2 6-4.27C13.363 5.905 11.25 5 8 5s-5.363.904-6 3.796c-.5 2.27 0 4.27 6 4.27z"></path><path d="M4 8a1 1 0 012 0v1a1 1 0 01-2 0V8zm2.078 2.492c-.083-.264.146-.492.422-.492h3c.276 0 .505.228.422.492C9.67 11.304 8.834 12 8 12c-.834 0-1.669-.696-1.922-1.508zM10 8a1 1 0 112 0v1a1 1 0 11-2 0V8z"></path></svg>
  .icon-tertiary
</div>
<div class="mb-2">
  <!-- <%= octicon "octoface", :height => 16, :class => "icon-info mr-1" %> -->
  <svg class="icon-info mr-1 octicon octicon-octoface" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M1.326 1.973a1.2 1.2 0 011.49-.832c.387.112.977.307 1.575.602.586.291 1.243.71 1.7 1.296.022.027.042.056.061.084A13.22 13.22 0 018 3c.67 0 1.289.037 1.861.108l.051-.07c.457-.586 1.114-1.004 1.7-1.295a9.654 9.654 0 011.576-.602 1.2 1.2 0 011.49.832c.14.493.356 1.347.479 2.29.079.604.123 1.28.07 1.936.541.977.773 2.11.773 3.301C16 13 14.5 15 8 15s-8-2-8-5.5c0-1.034.238-2.128.795-3.117-.08-.712-.034-1.46.052-2.12.122-.943.34-1.797.479-2.29zM8 13.065c6 0 6.5-2 6-4.27C13.363 5.905 11.25 5 8 5s-5.363.904-6 3.796c-.5 2.27 0 4.27 6 4.27z"></path><path d="M4 8a1 1 0 012 0v1a1 1 0 01-2 0V8zm2.078 2.492c-.083-.264.146-.492.422-.492h3c.276 0 .505.228.422.492C9.67 11.304 8.834 12 8 12c-.834 0-1.669-.696-1.922-1.508zM10 8a1 1 0 112 0v1a1 1 0 11-2 0V8z"></path></svg>
  .icon-info
</div>
<div class="mb-2">
  <!-- <%= octicon "octoface", :height => 16, :class => "icon-success mr-1" %> -->
  <svg class="icon-success mr-1 octicon octicon-octoface" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M1.326 1.973a1.2 1.2 0 011.49-.832c.387.112.977.307 1.575.602.586.291 1.243.71 1.7 1.296.022.027.042.056.061.084A13.22 13.22 0 018 3c.67 0 1.289.037 1.861.108l.051-.07c.457-.586 1.114-1.004 1.7-1.295a9.654 9.654 0 011.576-.602 1.2 1.2 0 011.49.832c.14.493.356 1.347.479 2.29.079.604.123 1.28.07 1.936.541.977.773 2.11.773 3.301C16 13 14.5 15 8 15s-8-2-8-5.5c0-1.034.238-2.128.795-3.117-.08-.712-.034-1.46.052-2.12.122-.943.34-1.797.479-2.29zM8 13.065c6 0 6.5-2 6-4.27C13.363 5.905 11.25 5 8 5s-5.363.904-6 3.796c-.5 2.27 0 4.27 6 4.27z"></path><path d="M4 8a1 1 0 012 0v1a1 1 0 01-2 0V8zm2.078 2.492c-.083-.264.146-.492.422-.492h3c.276 0 .505.228.422.492C9.67 11.304 8.834 12 8 12c-.834 0-1.669-.696-1.922-1.508zM10 8a1 1 0 112 0v1a1 1 0 11-2 0V8z"></path></svg>
  .icon-success
</div>
<div class="mb-2">
  <!-- <%= octicon "octoface", :height => 16, :class => "icon-warning mr-1" %> -->
  <svg class="icon-warning mr-1 octicon octicon-octoface" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M1.326 1.973a1.2 1.2 0 011.49-.832c.387.112.977.307 1.575.602.586.291 1.243.71 1.7 1.296.022.027.042.056.061.084A13.22 13.22 0 018 3c.67 0 1.289.037 1.861.108l.051-.07c.457-.586 1.114-1.004 1.7-1.295a9.654 9.654 0 011.576-.602 1.2 1.2 0 011.49.832c.14.493.356 1.347.479 2.29.079.604.123 1.28.07 1.936.541.977.773 2.11.773 3.301C16 13 14.5 15 8 15s-8-2-8-5.5c0-1.034.238-2.128.795-3.117-.08-.712-.034-1.46.052-2.12.122-.943.34-1.797.479-2.29zM8 13.065c6 0 6.5-2 6-4.27C13.363 5.905 11.25 5 8 5s-5.363.904-6 3.796c-.5 2.27 0 4.27 6 4.27z"></path><path d="M4 8a1 1 0 012 0v1a1 1 0 01-2 0V8zm2.078 2.492c-.083-.264.146-.492.422-.492h3c.276 0 .505.228.422.492C9.67 11.304 8.834 12 8 12c-.834 0-1.669-.696-1.922-1.508zM10 8a1 1 0 112 0v1a1 1 0 11-2 0V8z"></path></svg>
  .icon-warning
</div>
<div class="mb-2">
  <!-- <%= octicon "octoface", :height => 16, :class => "icon-danger mr-1" %> -->
  <svg class="icon-danger mr-1 octicon octicon-octoface" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M1.326 1.973a1.2 1.2 0 011.49-.832c.387.112.977.307 1.575.602.586.291 1.243.71 1.7 1.296.022.027.042.056.061.084A13.22 13.22 0 018 3c.67 0 1.289.037 1.861.108l.051-.07c.457-.586 1.114-1.004 1.7-1.295a9.654 9.654 0 011.576-.602 1.2 1.2 0 011.49.832c.14.493.356 1.347.479 2.29.079.604.123 1.28.07 1.936.541.977.773 2.11.773 3.301C16 13 14.5 15 8 15s-8-2-8-5.5c0-1.034.238-2.128.795-3.117-.08-.712-.034-1.46.052-2.12.122-.943.34-1.797.479-2.29zM8 13.065c6 0 6.5-2 6-4.27C13.363 5.905 11.25 5 8 5s-5.363.904-6 3.796c-.5 2.27 0 4.27 6 4.27z"></path><path d="M4 8a1 1 0 012 0v1a1 1 0 01-2 0V8zm2.078 2.492c-.083-.264.146-.492.422-.492h3c.276 0 .505.228.422.492C9.67 11.304 8.834 12 8 12c-.834 0-1.669-.696-1.922-1.508zM10 8a1 1 0 112 0v1a1 1 0 11-2 0V8z"></path></svg>
  .icon-danger
</div>
```


## Background colors

Background colors are most commonly used for filling large blocks of content or areas with a color. When selecting a background color, make sure the foreground color contrast passes a minimum WCAG accessibility rating of [level AA](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html). Meeting these standards ensures that content is accessible by everyone, regardless of disability or user device. You can [check your color combination with this demo site](https://colorable.jxnblk.com/). For more information, read our [accessibility standards](../principles/accessibility).

```html live
<div class="bg-canvas mb-2">.bg-canvas</div>
<div class="bg-primary mb-2">.bg-primary</div>
<div class="bg-secondary mb-2">.bg-secondary</div>
<div class="bg-tertiary mb-2">.bg-tertiary</div>
<div class="bg-info mb-2">.bg-info</div>
<div class="bg-success mb-2">.bg-success</div>
<div class="bg-warning mb-2">.bg-warning</div>
<div class="bg-danger mb-2">.bg-danger</div>
```

## Inversed colors

⚠️ WIP: Don't use in produciton. They might still change.

You can inverse some of the background colors to add more emphasis. Be sure to also inverse the text color (`.text-inverse`) to give enough contrast. An exception is the `.bg-warning-inverse` where the default text color should be used.

```html live
<div class="bg-canvas-inverse text-inverse mb-2">.bg-canvas-inverse .text-inverse</div>
<div class="bg-info-inverse text-inverse mb-2">.bg-info-inverse .text-inverse</div>
<div class="bg-success-inverse text-inverse mb-2">.bg-success-inverse .text-inverse</div>
<div class="bg-warning-inverse mb-2">.bg-warning-inverse</div>
<div class="bg-danger-inverse text-inverse mb-2">.bg-danger-inverse .text-inverse</div>
```

## Link colors

By default `<a>` elements already use a text color that is blue and apply an underline on hover. If you need to make other elements behave like a link and perhaps use JS to trigger navigating to another page, use the `.link-primary` class.

```html live
<span class="link-primary">link-primary</span>
```

If you like to override the default link styles you can do so with text color utilities and the following link utilities. **Bear in mind that link styles are easier for more people to see and interact with when the changes in styles do not rely on color alone.**

Use `.link-secondary` to turn the link color to blue only on hover.

```html live
<a class="link-secondary" href="#url">link-secondary</a>
```

Use `.link-tertiary` for a more subtle link color that turns blue on hover.

```html live
<a class="link-tertiary" href="#url">link-tertiary</a>
```

Use `.muted-link` for a more subtle color, that turns blue on hover but with **no underline**.

```html live
<a class="muted-link" href="#url">muted-link</a>
```

Use `.link-hover-blue` to make any text color used with links to turn blue on hover. This is useful when you want only part of a link to turn blue on hover.

```html live
<a class="text-primary no-underline" href="#url">
  A link with only part of it is <span class="link-hover-blue">blue on hover</span>.
</a>
```

## Border colors

Border colors are documented on the [border utilities page](../utilities/borders#border-width-style-and-color-utilities).


<!-- TODO: Remove? -->
<!--
<PaletteTable>
  {palettes.map(({name, title, value}) => (
    <PaletteTableFragment name={name} type="bg" sparse key={name}>
      <tr>
        <PaletteHeading indicatorColor={value} colSpan="4">
          {title}
        </PaletteHeading>
      </tr>
    </PaletteTableFragment>
  ))}
</PaletteTable>
-->

<!-- TODO: Remove? -->
<!--
<PaletteTable columns={[
  {
    title: 'Alias',
    Cell: props => <PaletteCell.Alias {...props} style={{borderBottom: `1px solid ${props.value} !important`}} />
  },
  'variable',
  {title: 'Value', Cell: PaletteCell.Background, Value: PaletteValue.Value}
]}>
  {palettes.map(({name, title, value}) => (
    <PaletteTableFragment name={name} key={name} type="text" sparse prefix="color" columns={[
  {
    title: 'Alias',
    Cell: props => <PaletteCell.Alias {...props} style={{borderBottom: `1px solid ${props.value} !important`}} />
  },
  'variable',
  {title: 'Value', Cell: PaletteCell.Background, Value: PaletteValue.Value}
]}>
      <tr>
        <PaletteHeading indicatorColor={value} colSpan="4">
          {title}
        </PaletteHeading>
      </tr>
    </PaletteTableFragment>
  ))}
</PaletteTable>
-->