Skip to content
Recursica

Colors

Recursica’s colors are design tokens. Each color has a name, such as palette-1/400, and components use that name instead of a hex value. The default palettes meet WCAG AA contrast, and any palette can be changed or added to in Theme Forge.

Color tokens use the W3C Design Tokens Community Group format. They’re created and checked in Theme Forge, stored in the three token files, and exported as DTCG JSON and CSS variables.

Palettes

A Recursica theme can have as many color palettes as it needs, and every palette can be changed in Theme Forge. The default theme starts with three:

  • Palette 1 is the main brand color. It’s used for the most important actions and highlights.
  • Palette 2 is a second brand color, for accents and visual interest.
  • Neutral is a gray scale from near-white to near-black. It’s used for backgrounds, borders, dividers, and text.

Tones in a palette

Each palette has 12 tones, from 000 (lightest) to 1000 (darkest).

  • Default tone: one tone in each palette is marked as its default. In the default theme, that’s tone 400.
  • On-tone: every tone comes with an on-tone, the color for text and icons placed on top of it. On-tones are checked so they meet WCAG AA contrast.

Core colors

Besides the palettes, a theme defines core colors. Each core color has a fixed job, whatever the palettes look like, and each one can be customized in Theme Forge. The default theme has six:

  • High contrast: the strongest surface the theme has, near-black in light mode and near-white in dark mode. Use it for banners that need to stand out from everything around them.
  • Low contrast: the opposite of high contrast, the quietest surface. Each one uses the other’s tone for its text, so the pair is always readable.
  • Interactive: the color of things a person can click or select, like buttons, links, focus rings, and selected items.
  • Alert: errors, failed actions, form problems, and actions that delete something.
  • Success: finished actions and confirmations.
  • Warning: cautions that don’t stop the person, and details worth a second look.

Tones and on-tones

Every color in a Recursica theme comes as a pair:

  • tone is the color itself, used to fill a surface, a solid button, or a badge.
  • on-tone is the color for anything that sits on top of that tone, such as the label on a solid button or an icon in a badge. Theme Forge checks each on-tone against its tone for WCAG AA contrast.

Core colors add a third property:

  • interactive is the color for a link that sits on top of the tone. A link inside a red alert banner needs a different color than a link on the page, and interactive is that color. The interactive core color itself has only a tone and an on-tone.

An alert banner shows all three at work. The alert tone fills the banner, the alert on-tone colors the banner’s text, and the alert interactive colors the “Learn more” link inside it. All three are checked against each other, so the banner needs no custom styling.

Each layer also has its own text and link colors, such as layer_1_elements_text_color and layer_1_elements_interactive_color. Text and links that sit directly on a card or a page use these, because they’re checked against that layer’s surface.

The most common color mistake in Recursica is coloring text with a tone. A link colored with interactive_tone, for example, takes on the solid button’s color, which is often too pale or too bright to read as text. Text belongs in an on-tone, or in a layer’s text or link color.

High and low emphasis for text

Recursica doesn’t use extra colors to make some text look less important. It uses opacity instead. Each theme has exactly two levels:

  • High emphasis is fully opaque. Use it for headings, body text, and anything people need to read.
  • Low emphasis is slightly see-through. Use it for captions, dates, and other supporting text.

There’s no third level. A design that seems to need a third level is usually inventing a color instead of using one from the theme. Because emphasis is an opacity applied to the layer’s own text color, it stays correct when the background changes.

Color in the three token files

Color is split across the three token files, so each part can change without touching the others:

  1. The tokens file gives raw hex values a name. For example, #DD2C56 becomes ruby-red.
  2. The brand file gives those names a job. For example, it makes ruby-red the default tone of the alert color. Light and dark mode use the same job names here and point them at different colors.
  3. The UI kit file connects each component to a job. A button’s background points at the interactive color, not at a specific palette tone.

As a result, what a color is (in the tokens file) and what a color is for (in the brand file) can each change without changing any component or CSS class. All three files are edited in Theme Forge and export them together.

Colors also change with depth. The same color job can give a different value depending on which layer an element is in. That keeps each surface visible against the one behind it, and keeps text readable at every depth.