HTML & CSS

Use CSS Gradients as Reusable Background Values

Add gradient color in CSS with image-valued custom properties, reuse a palette across components, and keep text colors separate from background gradients.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Use a gradient where CSS accepts an image

To add gradient color in CSS, assign a gradient function to background-image or the background shorthand. A gradient is an image value, so color: linear-gradient(...) and background-color: linear-gradient(...) are not valid substitutes. Keep the foreground text color as a separate solid color unless you intentionally use text background clipping.

For a reusable design, store the gradient value in a CSS custom property and reference it from the components that need that surface. Store its endpoint colors separately if they are also used elsewhere. This lets a palette change update several related surfaces without copying slightly different gradient strings throughout a stylesheet.

Separate endpoint colors, the surface and the text

The example defines two color values, a background-image value and a foreground color. A card and a small decorative stripe share the same gradient. The card’s text remains white; the stripe has no textual content. These are separate uses of one image-valued token rather than an attempt to assign the gradient to every color property.

<section class="palette-demo">
  <div class="palette-stripe" aria-hidden="true"></div>
  <article class="palette-card">
    <h2>One palette, two surfaces</h2>
    <p>The gradient is a background value.</p>
  </article>
</section>

.palette-demo {
  --surface-start: #1e3a8a;
  --surface-end: #581c87;
  --surface-gradient: linear-gradient(135deg, var(--surface-start), var(--surface-end));
  --surface-text: #ffffff;
  max-width: 40rem;
  margin: 1rem auto;
}
.palette-stripe {
  height: .75rem;
  margin-bottom: .75rem;
  background-color: var(--surface-start);
  background-image: var(--surface-gradient);
}
.palette-card {
  box-sizing: border-box;
  padding: 2rem;
  color: var(--surface-text);
  background-color: var(--surface-start);
  background-image: var(--surface-gradient);
  overflow-wrap: anywhere;
}
.palette-demo.teal {
  --surface-start: #134e4a;
  --surface-end: #1e3a8a;
}

Add the teal class to .palette-demo to change both surfaces. The new endpoint values are resolved where the shared gradient custom property is defined. Both the stripe and card inherit the resulting value from that palette container, so they stay coordinated when the variant changes.

Define variables at the scope that owns the variant

Custom properties participate in the cascade and inherit by default. If a gradient token is defined on an ancestor using other variables, changing those endpoint variables only on a distant descendant may not rebuild the inherited token as you expect. Define the composite gradient at the scope where its endpoint values are meant to vary.

In this recipe, the palette class and its variant both live on the same container. That makes the relationship explicit. If a single card needs its own endpoints, either move the composite gradient definition into that card’s rule or override the complete gradient value there. Avoid scattering overrides until the current scope is clear.

Move a generated gradient into the custom property

Open the CSS Gradient Generator, select Linear, angle 135, and colors #1e3a8a and #581c87. Its output includes a background property name and a semicolon. To store only the image value, copy the linear-gradient(...) portion into --surface-gradient, or use the variable-based version in the example.

The tool does not export a token system or decide which ancestor should own a variant. It previews one two-color gradient at a time. Compare the second palette with #134e4a and #1e3a8a, then apply those values to the same container’s endpoint variables in your stylesheet.

Choose foreground colors as a separate decision

Changing a gradient’s endpoints can change the text contrast even when the foreground token is unchanged. Review the brightest part behind the card’s wording for every palette variant. If one variant includes a pale endpoint, it may need a dark foreground or a solid inner reading panel rather than the same white text.

For actual gradient-filled letters, use CSS Gradient Text Color and text clipping instead of assigning the background token to color. That is a different painting technique with its own fallback requirements. A background design token should not silently turn normal body text transparent.

Inspect the resolved component values

Switch the palette class and inspect the computed background-image of both components. They should change together while their dimensions and text stay the same. Test at a narrow width and with increased text size to separate a palette change from a layout regression.

MDN’s custom-property guide explains inheritance and value substitution. Keep the token names descriptive of their role, retain a useful solid background beneath the image, and test the components where the values are consumed rather than validating only the variable declarations in isolation.