Gradients

Create linear, radial, conic, repeating, and layered backgrounds. Gradients use the same color system as other visual utilities, including tones, alpha values, and semantic color tokens.

Syntax

Gradient utilities map to background-image. Start with a gradient type, separate each part with a pipe |, and use underscores wherever the CSS value would normally contain spaces.

Utility

CSS Function

Example

bgimg-linear|*

linear-gradient()

bgimg-linear|to_right|red|blue

bgimg-radial|*

radial-gradient()

bgimg-radial|circle|white|transparent

bgimg-conic|*

conic-gradient()

bgimg-conic|from_45deg|primary|secondary

bgimg-rlinear|*

repeating-linear-gradient()

bgimg-rlinear|45deg|red_0|blue_10%

bgimg-rradial|*

repeating-radial-gradient()

bgimg-rradial|circle|red_0|blue_10%

bgimg-rconic|*

repeating-conic-gradient()

bgimg-rconic|red_0|blue_10deg

Reading Gradient Classes

Pipes separate gradient arguments, underscores become spaces inside an argument, and commas combine multiple background layers. For example, to_bottom becomes to bottom, while primary_0 becomes a color stop at 0%.

Linear Gradients

Use bgimg-linear|* for directional color transitions. Add a direction as the first part when you need control over the gradient angle or flow.

aqua|blue

to_right|aqua|blue

135deg|aqua|blue


<!-- Default direction -->
<div class="bgimg-linear|aqua|blue"></div>

<!-- Direction keyword -->
<div class="bgimg-linear|to_right|aqua|blue"></div>

<!-- Angle -->
<div class="bgimg-linear|135deg|aqua|blue"></div>

Color Stops

Add stop positions after a color with an underscore. Colors can use Maple tones and alpha suffixes, so gradients can stay tied to your semantic palette instead of hard-coded values.

color stops

alpha colors

tones


<!-- Stops use underscores -->
<div class="bgimg-linear|to_bottom|aqua_0|blue_%"></div>

<!-- Alpha suffixes work inside gradients -->
<div class="bgimg-linear|to_right|aqua/50|blue/80"></div>

<!-- Tones and stop positions can be combined -->
<div class="bgimg-linear|to_right|aqua-700|aqua-100|aqua-700"></div>

Radial Gradients

Use bgimg-radial|* when the color should expand from a point. Shape and position arguments are written before the color stops.

radial

circle

circle_at_top


<!-- Basic radial gradient -->
<div class="bgimg-radial|aqua|blue"></div>

<!-- Circular shape -->
<div class="bgimg-radial|circle|aqua|blue"></div>

<!-- Shape and position -->
<div class="bgimg-radial|circle_at_top|aqua|blue"></div>

Conic Gradients

Use bgimg-conic|* for color transitions around a center point. Conic gradients are useful for wheels, pie slices, angular highlights, and patterned backgrounds.

rainbow

from_45deg

multiple stops


<!-- Color wheel -->
<div class="bgimg-conic|red|yellow|green|blue|red"></div>

<!-- Start angle -->
<div class="bgimg-conic|from_45deg|aqua|blue"></div>

<!-- Multiple stop positions -->
<div class="bgimg-conic|aqua-200_0.25turn|aqua-400_0.25turn_0.5turn|aqua-600_0.5turn_0.75turn|aqua-800_0.75turn"></div>

Repeating Gradients

Add the r prefix to create repeating gradients. Repeating gradients rely on explicit stop positions, which define the size of each stripe, ring, or wedge.

rlinear

rradial

rconic


<!-- Repeating linear stripes -->
<div class="bgimg-rlinear|45deg|aqua-400|aqua-400_8px|aqua-600_8px|aqua-600_16px"></div>

<!-- Repeating radial rings -->
<div class="bgimg-rradial|circle|aqua-400|aqua-400_8px|aqua-600_8px|aqua-600_16px"></div>

<!-- Repeating conic wedges -->
<div class="bgimg-rconic|aqua-400|aqua-400_10deg|aqua-600_10deg|aqua-600_20deg"></div>

Layers and Background Settings

Combine gradients with commas to create multiple background layers. Use a double underscore __ when a gradient also needs background position, size, or repeat settings.

layered overlay

position/size/repeat


<!-- Multiple gradient layers -->
<div class="bgimg-linear|to_top|transparent|black/60,radial|circle_at_top|blue/60|transparent bgc-aqua"></div>

<!-- Background position, size, and repeat -->
<div class="bg-conic|aqua-400_0.25turn|aqua-600_0.25turn_0.5turn|aqua-400_0.5turn_0.75turn|aqua-600_0.75turn__top_left/25%_25%_repeat"></div>

Background Images

The same background-image utility can load URLs. Wrap absolute URLs in brackets when they contain characters like colons, then append __position/size_repeat when the image needs background shorthand settings.


<!-- Absolute URL, wrapped because it contains a colon -->
<div class="bgimg-url|[https://example.com/image.jpg]"></div>

<!-- Relative path -->
<div class="bgimg-url|/images/hero.jpg"></div>

<!-- URL with background settings -->
<div class="bg-url|/images/pattern.png__center/cover_no-repeat"></div>

Refer to the underlying CSS properties for granular background control.