overview.md

permalink	layout	title	category	lead	type	redirect_from	subnav
/style/color/overview/	styleguide	Overview	Style	Color is a practical and emotional tool. It conveys personality, sets a tone, attracts attention, and indicates importance.	docs	/components/colors/ /style/color/ /colors/	text href Introduction #introduction text href Color and accessibility #color-and-accessibility text href USWDS color wheels #uswds-color-wheels text href Using color #using-color

Introduction

USWDS organizes its colors into two related palettes: the [project theme palette]({{ site.baseurl }}/style/color/theme-palette/) and the [system palette]({{ site.baseurl }}/style/color/system-palette/). The project theme palette is a subset of the broader system palette — your project’s theme should reflect your project’s individual identity, tone, and needs. It will use only a few color families from the broader set of 23 color families available to all users of the system.

{:.measure-5 .margin-top-5} 

{:.font-sans-2xs} Above: The 26 color families of the USWDS system palette, including all grades and variants. Together, they form a broad, expressive, and practical palette designed to encourage a diversity of tone as well as overall consistency and coherence.

Use USWDS colors and avoid custom colors whenever possible. In the long run, it’s a better user experience across government when there’s coherence across sites and services. Of course, your mission, project needs, and user needs always come first, but if you plan to contribute your work back into the system — which helps the system learn, adapt, and improve — that work will need to conform to system standards and use system colors.

<style>code {mix-blend-mode: multiply;}</style>

{:.font-sans-xs} ### COLOR, COLOR FAMILY, AND GRADE

Throughout our documentation and guidance, we’ll use use the terms color, color family, and grade, but what do we mean when we use them?

Color is any specific swatch in our palettes, like red 50, primary base, or indigo warm 60v.

Color family is a group of colors that all have the same hue on a color wheel (See USWDS color wheels below). They contain a number of individual colors, distinguished by the brightness or saturation of each individual color. A color family is typically a conventional color name like red or blue warm, or could be a use-based name in the project theme palette, like primary.

Grade is a way to express how light or dark a color is. USWDS uses a 100-point scale to communicate the grade, where 0 is pure white and 100 is pure black. We’ve regularized these grades across color families: a color of grade 50 in one color family should be the same level of lightness as a color of grade 50 in another color family. This has important color contrast and accessibility implications that we’ll discuss later.

Color and accessibility

Color is powerful but unreliable — its effects are neither consistent nor predictable across a population. Approximately 8–9% of adults have some kind of color insensitivity. Color insensitivity can make it difficult to distinguish hues (red/green color blindness is the most common form), and some rare conditions prevent the perception of hue altogether. Commonplace vision problems like short- and near-sightedness and astigmatism (among others) also affect how well folks perceive color and contrast.

Section 508, which aligns with WCAG 2.0 Level AA, sets a legal standard for the contrast level necessary between text and its background. The baseline AA contrast standard is 4.5:1 for most text and 3:1 for large text (19px+ bold or 24px+ normal text).

Accessible color pairings

USWDS helps teams choose accessible colors with a color grade system. Let’s look at the gray color family, in grades 5-90 (grade 0 is white):

{% capture gray-grade %}

Gray

5

10

20

30

40

50

60

70

80

90

{% endcapture %} {{ gray-grade }}

{:.font-sans-2xs} Above: Each color family has ten grades, from 5-90. Pure white is the equivalent of grade 0, and pure black is the equivalent of grade 100. Across families, grades have the same gray value — that is, when seen in grayscale any color of the same grade will look the same.

Magic number

We call the difference in grade between any two colors the magic number. Magic numbers have important contrast implications:

• A magic number of 40 or higher achieves WCAG 2.0 AA Large Text contrast (example: between gray 90 and indigo warm 50v).
• A magic number of 50 or higher achieves WCAG 2.0 AA contrast or AAA Large Text contrast(example: between gray 90 and red 40).
• A magic number of 70 or higher achieves WCAG 2.0 AAA contrast (example: between gray 10 and red 80).
• Colors of grade 50 achieve Section 508 AA contrast against both pure white (grade 0) and pure black (grade 100).

Use USWDS magic numbers to choose accessible color combinations from any palette and color family.

Accessible color combination examples

{:.measure-5} 

{:.font-sans-2xs} Above: Since 90 – 50 = 40, on a background of gray 90 use grades of 40 and below to assure Section 508 AA contrast. Grades of 50 and below are acceptable for large text.

{:.measure-5 .margin-top-5} 

{:.font-sans-2xs} Above: The color grade system works across color families.

{:.measure-5 .border .border-radius-small .padding-4 .margin-top-5} 

{:.font-sans-2xs} Above: This data visualization shows the ten standard grades of a USWDS color family, as well as grade 0 (white) and grade 100 (black). Lightness is the lightness level of gray in the HSL color model. The delta column shows the difference in gray level between grades. The bars on the right show minimum conformant color pairs. Grade 50 will be WCAG 2.0 AA conformant against both pure black and pure white.

There should be no need for additional manual checking, but this system is relatively new, and it’s worth confirming contrast using a tool like Colorable to assure system integrity. If you find any problems, file an issue in the USWDS Github repo.

USWDS color wheels

The following color wheels are a way to visualize the entire [USWDS system palette]({{ site.baseurl }}/style/color/system-palette/) and its color family naming rubric. The color wheels are arranged around the 360° of the HSL color model. Each color family is labelled with its position (in degrees) on this model. In general, colors within color families stay close to the hue value listed, but it is a custom palette, not generated by an algorithm. Hue variation within color families is intentional — we are trying to find good colors, not just those that fit a function.

The vivid palette is incomplete. We’ve added vivid variants as we’ve found a project need. This number will continue to grow and we welcome new suggetions in our Github repo for vivid variants where none currently exist.


---


Using color

If we use color intentionally, consistently, and sensitively, it can make a big difference in the way people understand and connect with our pages, our products and services, and our message. Color is an important component of visual and emotional cognition, and that’s precisely what makes it difficult to use well — what’s strong and confident to one person can be jarring or alarming to another.

Start in black and white. Start with your core message and use type scale and heierarchy to test and refine its effectiveness. Then introduce color to support that message. Color can overwhelm interpretation, and since approximately 8–9% of the population has some kind of color insensitivity, it’s important not to rely on color to convey information critical to your message.

Put the practical before the emotional. Because color can do so much, it can be smart to be focused. Limit the complexity of color by concentrating on functional requirements (like status states or directions) first. Then, use color as progressive enhancement to reinforce or balance the emotional needs of the content. Even so, bear in mind that the effects of color are often personal and cultural as much, or more so, than physiological. Understand that using color to optimize for tone necessarily exludes in in subtle and not-so-subtle ways.

Use mood boards for guidance. It can be challenging to derive appropriate color palettes, and it makes sense to let existing colors and palettes be your guide. Collect images from other sources that evoke the desired tone to find commonalities. Then, find close matches in the system palette to help build your theme.

Ask visual designers. Your group or agency may have visual designers either on staff or available as contractors. They can be an invaluable resource for building palettes or getting feedback on existing ones. USWDS benefits from the collective experience of visual designers across agencies to build our system palette, and to provide a range of prebuilt project theme palettes. If you have visual design resources, use them.

Don’t use color exclusively to convey meaning. Even Section 508 conformant contrast doesn’t ensure that colors are distinguishable for a significant percentage of your audience. Approximately 8–9% of the population has some kind of color insensitivity, especially between red and green. Color should only be used as progressive enhancement — if color is the only signal, that signal won’t get through as intended to everyone.