CORE UTILITY FAMILY

Backgrounds, gradients, and colors

Apply theme, inherited, current, transparent, or arbitrary colors; compose linear, radial, and conic gradients; and control every background image layer setting.

completeTarget v0.38 verified examplesRegistry JSON ↗

WHEN TO USE IT

Choose the right tool for the layout.

Prefer theme colors and named background-image tokens, compose gradients from an explicit direction plus from/via/to stops, and use typed arbitrary values when image, color, position, or size syntax could be ambiguous.

QUICK REFERENCE

Classes and generated CSS

These examples are resolved by the compiler when the registry manifest is generated. A broken example fails the test suite.

ClassGenerated declarations and keyframes

co-bg-black/50background-color: color-mix(in oklab, var(--co-color-black) 50%, transparent);

co-bg-[color:color(display-p3_1_0_0)]background-color: color(display-p3 1 0 0);

co-bg-linear-to-r/display-p3background-image: linear-gradient(to right in display-p3, var(--co-gradient-stops));

co-from-brand-500

--co-gradient-from: var(--co-color-brand-500) var(--co-gradient-from-position, 0%); --co-gradient-to: color-mix(in oklab, var(--co-color-brand-500) 0%, transparent) var(--co-gradient-to-position, 100%); --co-gradient-stops: var(--co-gradient-from), var(--co-gradient-to);

co-via-40%--co-gradient-via-position: 40%;

co-to-transparent--co-gradient-to: transparent var(--co-gradient-to-position, 100%);

co-bg-position-(--focus)background-position: var(--focus);

co-bg-size-[auto_12rem]background-size: auto 12rem;

VISUAL EXAMPLE · COLOR AND OPACITY

Apply theme colors with optional opacity

Named colors reference CSS-first theme tokens. Add slash opacity when the same semantic color needs a translucent treatment.

co-bg-brand-500

co-bg-black/70

co-bg-transparent

component.coord

<div class="co-grid co-grid-cols-3 co-gap-3">
  <div class="co-bg-brand-500 co-text-white">brand-500</div>
  <div class="co-bg-black/70 co-text-white">black/70</div>
  <div class="co-bg-transparent co-border">transparent</div>
</div>

VISUAL EXAMPLE · IMAGE POSITIONING

Control how an image fills its surface

Combine an image source with position, size, and repeat utilities. Cover is useful for hero surfaces, while explicit positioning protects the visual focal point.

Focused herocover · 70% center · no-repeat

component.coord

<section class="co-bg-[url(/hero.jpg)] co-bg-cover co-bg-position-[70%_center] co-bg-no-repeat">
  <div class="co-bg-black/45 co-p-8 co-text-white">Hero content</div>
</section>

VISUAL EXAMPLE · LINEAR GRADIENT

Compose gradient stops and interpolation

Choose a direction, then define from, via, and to colors separately. An interpolation modifier controls how colors travel between stops.

to-r / oklch

45deg / display-p3

component.coord

<div class="co-bg-linear-to-r/oklch co-from-brand-500 co-via-pink co-to-black">
  OKLCH gradient
</div>

<div class="co-bg-linear-45/display-p3 co-from-red co-to-blue">
  Display-P3 interpolation
</div>

VISUAL EXAMPLE · RADIAL AND CONIC

Choose a gradient shape for the composition

Radial gradients emphasize a focal point. Conic gradients rotate colors around a center and work well for progress, charts, and decorative color wheels.

component.coord

<div class="co-bg-radial-[at_35%_30%] co-from-white co-via-brand-300 co-to-brand-800"></div>
<div class="co-bg-conic/decreasing co-from-brand-500 co-via-pink co-to-brand-500"></div>

VISUAL EXAMPLE · REPEAT AND SIZE

Build controlled repeating patterns

Background size controls the pattern tile. Repeat utilities choose whether that tile repeats on both axes, one axis, or not at all.

24px repeat grid

component.coord

<div class="co-bg-[image:linear-gradient(90deg,#111_1px,transparent_1px)] co-bg-size-[24px_24px] co-bg-repeat"></div>
<div class="co-bg-[url(/stripe.svg)] co-bg-repeat-x co-bg-size-auto"></div>

BASIC USAGE

Apply a utility directly.

Keep the complete class string in your template so the plain-text scanner can discover it without evaluating application code.

component.coord

<div class="co-bg-black/50 co-bg-[color:color(display-p3_1_0_0)] co-bg-linear-to-r/display-p3 co-from-brand-500 co-via-40% co-to-transparent co-bg-position-(--focus) co-bg-size-[auto_12rem]">
  Your content
</div>

HOW IT WORKS

Core concepts

01
Theme colors compile through --co-color-* variables and named images through --co-background-image-* variables.
02
A paired --co-color-{name}--p3 token progressively overrides its fallback only when both Display-P3 syntax and a P3 output gamut are available.
03
Slash opacity uses color-mix in OKLab instead of duplicating palette entries.
04
Linear, radial, and conic gradients share composable from/via/to colors and percentage positions.
05
Gradient interpolation modifiers support sRGB, linear sRGB, HSL, Lab, LCH, OKLab, OKLCH, Display-P3, and OKLCH hue-path controls.
06
Position and size accept named values, CSS custom-property shorthand, and safe arbitrary values.

CSS PROPERTIES

What this family controls

background-colorbackground-imagebackground-attachmentbackground-clipbackground-originbackground-positionbackground-repeatbackground-sizeaccent-colorcaret-color--co-gradient-stops

VARIANTS

Responsive and state conditions

Prefix any supported utility with responsive or state variants. Variants compose from left to right and the compiler emits the required selector or at-rule.

component.coord

<div class="co-bg-black/50 md:co-bg-[color:color(display-p3_1_0_0)] hover:co-bg-black/50">
  Responsive and state-aware content
</div>

ARBITRARY VALUES

Escape the scale when necessary

Use square brackets for a one-off CSS value. Prefer theme tokens for values repeated across components so an AI agent and human reviewer can recognize design intent.

Arbitrary syntax

co-bg-*
co-[content-visibility:auto]

NEGATIVE VALUES

Reverse supported values

Place the minus sign before the framework prefix. Only properties where negative CSS values are meaningful accept this modifier.

Canonical negative syntax

-co-{utility}
-co-mt-4

SCOPE BOUNDARIES

Intentional boundaries

This family is implemented, documented, and tested. These notes define where a neighboring family or browser behavior takes over.

Always pair a P3 token with a normal --co-color-* fallback; the compiler intentionally ignores orphan or unsafe P3 metadata.
Background images referenced by URL remain application assets and are not bundled by the compiler.

Previous← Typography NextBorders, outlines, rings, and divide →