Colors

For re-theming a whole app, see Creating a theme.

Semantic colors

colors is an open group. Each key becomes a valid value of the color prop on every component that has one.

colors: {
  primary: { light: '#c21a5e', dark: '#e04f9a' },
  success: { light: '#15803d', dark: '#4ade80' },
  danger:  { light: '#dc2626', dark: '#f87171', on: '#ffffff' },
},

primary

neutral

success

warning

danger

info

Each color has a value per color scheme. Lighter, more saturated values usually work better on dark backgrounds.

Foreground (`on`)

The text drawn on top of a color (a solid button’s label, for example) is computed at build time: black or white, whichever has more contrast, separately for light and dark. Set on to choose it yourself, either as one value or per scheme:

warning: { light: '#b45309', dark: '#fbbf24', on: { light: '#ffffff', dark: '#1c1917' } },

Automatic foregrounds need hex values. For oklch(), hsl() or other formats, set on explicitly.

Text shade (`text`)

Outline, soft and ghost variants, colored Text, Link and menu items draw the color as text, often on a light tint of itself. Mid-tone colors like green, amber and red can fall below 4.5:1 there.

So the build also computes a text shade per color and scheme: the color itself when it already has enough contrast against the page background, the surface and the tinted backgrounds, otherwise the color mixed toward the neutral text color, in small steps, until it does. Colors that pass are left untouched; backgrounds and borders always use the exact color.

success: { light: '#15803d', dark: '#4ade80' },
// generated: --yarcl-color-success-text: light-dark(#146b39, #4ade80)

Set text to choose it yourself, as one value or per scheme:

success: { light: '#15803d', dark: '#4ade80', text: { light: '#0f5c2e', dark: '#4ade80' } },

Contrast warnings

The plugin checks every color’s foreground against its background in both schemes. Anything below 4.5:1 (WCAG AA for normal text) is reported when you build or run the dev server:

[yarcl] colors.warning: light foreground contrast 3.12:1 is below 4.5:1

Neutrals

neutrals holds the colors that aren’t a color prop value: page and surface backgrounds, text and borders. The library requires five keys and accepts any extra ones.

Key	Used for
`bg`	page background (for your own `body` styles)
`surface`	inputs, cards, menus, dialogs
`text`	default text
`muted`	secondary text, placeholders, descriptions
`border`	default borders and dividers

Light and dark mode

Every color is emitted as a CSS light-dark() pair, and the generated stylesheet sets color-scheme: light dark on :root. The page follows the operating system’s setting with no JavaScript.

To force a scheme, set color-scheme on any element. It applies to everything inside:

Only this card is dark

Every color is a light-dark() pair, so setting color-scheme on an element switches everything inside it.

Active

document.documentElement.style.colorScheme = 'dark'; // whole page
<div style={{ colorScheme: 'light' }}>…</div>         // one region

Error and focus colors

Two settings reference a color key instead of defining one:

defaults.errorColor: invalid fields, error messages and the required marker.
focusRing.color: the keyboard focus outline.

Your color keys are your own, so the library never assumes a danger or primary exists.

Using colors in your own CSS

Every color is also a CSS variable:

.highlight {
  color: var(--yarcl-color-primary);
  background: color-mix(in oklab, var(--yarcl-color-primary) 12%, transparent);
}

See generated CSS for the full list.