About semantic colors
Semantic colors are what you should use most of the time. Only use a base color when you can't seem to find a semantic color for your use case. If that happens, let us know!
Semantic colors are defined by a combination of:
- target: what the color is being applied to
- role: what meaning the color is meant to convey
- emphasis level: how much you want the color to stand out from its surroundings
- interactive state: how the user is currently interacting with the element being colored
Let's break these down a little bit...
Targets
- Backgrounds (BG)
- Used for surfaces on which content or interactions will live; or for non-interactive, decorative content. No specific color contrast requirements.
- Interactions (UI)
- Backgrounds for things that are interactive—buttons, form controls, etc. To adhere to WCAG guidelines, color contrasts against typical background colors (e.g. white and gray 100) will be >= 4.5:1.
- Text
- Text and non-decorative icons. To adhere to WCAG guidelines, color contrasts against typical background colors (e.g. white and gray 100) will be >= 4.5:1.
- Borders
- Borders for interactive UI elements. To adhere to WCAG guidelines, color contrasts against typical background colors (e.g. white and gray 100) will be >= 3:1.
- Lines
- Separators between non-interactive elements. No specific WCAG color contrast requirements.
Roles
- Neutral
- For default text, and lower-priority UI elements.
- Brand
- For primary UI elements, or elements that are meant to tie into Justworks branding.
- Danger
- For destructive actions or error states.
- Inverse
- The opposite of neutral, for use on strong backgrounds.
- Disabled
- For elements that the user temporarily can't interact with (other than perhaps to see a message explaining why).
- Success
- For a favorable outcome, or completion of a task.
- Warning
- For when a user should take caution, to possibly prevent an error from occurring.
- New
- For highlighting content or functionality that is new to the current user.
- Info
- For particularly important content that you want to draw users' attention.
Emphasis
Emphasis can be expressed on one of two scales (least to most):
- subtle, default, strong
- tertiary, secondary, primary
Interactive states
- Resting
- When the user is not interacting with the element.
- Hover
- When the user's mouse cursor intersects with the element.
- Pressed
-
While the user is clicking, tapping, or otherwise activating the element, but hasn't let go yet.
In CSS, this is called
active, but we call it "pressed" to disambiguate it from another common use of the term "active": when something has been selected, or is associated with a previous selection.
Semantic color palette
Backgrounds
Neutral
Brand
Danger
Inverse
Success
Warning
New
Info
Interactions
Neutral
Primary
Secondary
Tertiary
Brand
Primary
Secondary
Tertiary
Danger
Primary
Secondary
Tertiary
Inverse
Primary
Secondary
Tertiary
Disabled
Success
Primary
Secondary
Tertiary
Warning
Primary
Secondary
Tertiary
Text
Neutral
Brand
Danger
Inverse
Disabled
Success
Warning
New
Info
Border
Neutral
Brand
Danger
Inverse
Disabled
Line
Neutral
Inverse
About base colors
Base colors are simply our way of saying: out of all the colors out there in the world, we want to use these ones. You should only use them directly if there isn't a semantic color definition that matches your use case.
They've been set up to meet certain key color contrast ratios for accessibility purposes, on a white or gray 100 background:
- 500s (and up) will be at least 3:1 against white (or black, in dark mode) or gray 100
- 600s (and up) will be at least 4.5:1 against white (or black, in dark mode) or gray 100