Use when building linear, conic, or radial gradient backgrounds, picking an interpolation colour space (oklab default, oklch, srgb, hsl, longer-hue, shorter-hue), placing color stops at specific positions, or migrating a v3 `bg-gradient-to-r from-X to-Y` markup to v4's expanded gradient API with `bg-linear-*`, `bg-radial-*`, and `bg-conic-*`. Prevents the rename-trap (every v3 `bg-gradient-*` class is renamed to `bg-linear-*` in v4), the muddy-middle trap (sRGB interpolation produces a gray midpoint between saturated complementary colours where oklch keeps it vivid), the conic-without-from trap (`bg-conic` without a `from-{color}` produces an invisible gradient), and the v3-radial-by-arbitrary trap (v3 has no native bg-radial-* and forces `bg-[radial-gradient(...)]`). Covers every linear direction utility, the angle-based form (bg-linear-45), the conic and radial families, every from-/via-/to- color and position stop, and the seven interpolation modifiers. Keywords: tailwind gradient, bg-linear, bg-linear-to-
Use when building linear, conic, or radial gradient backgrounds, picking an interpolation colour space (oklab default, oklch, srgb, hsl, longer-hue, shorter-hue), placing color stops at specific positions, or migrating a v3 `bg-gradient-to-r from-X to-Y` markup to v4's expanded gradient API with `bg-linear-*`, `bg-radial-*`, and `bg-conic-*`. Prevents the rename-trap (every v3 `bg-gradient-*` class is renamed to `bg-linear-*` in v4), the muddy-middle trap (sRGB interpolation produces a gray midpoint between saturated complementary colours where oklch keeps it vivid), the conic-without-from trap (`bg-conic` without a `from-{color}` produces an invisible gradient), and the v3-radial-by-arbitrary trap (v3 has no native bg-radial-* and forces `bg-[radial-gradient(...)]`). Covers every linear direction utility, the angle-based form (bg-linear-45), the conic and radial families, every from-/via-/to- color and position stop, and the seven interpolation modifiers. Keywords: tailwind gradient, bg-linear, bg-linear-to-r, bg-linear-45, bg-radial, bg-radial-[at_top_left], bg-conic, bg-conic-90, from-, via-, to-, from-10%, via-30%, to-90%, color stops, gradient position, interpolation modifier, oklab, oklch, srgb, hsl, longer-hue, shorter-hue, in_oklab, bg-gradient-to-r v3, bg-gradient renamed, gradient migration v3 to v4, conic gradient tailwind, radial gradient tailwind, vivid gradient, muddy gradient, gray midpoint, gradient middle gray, rainbow gradient, angle gradient.
license
MIT
compatibility
Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
Tailwind CSS Gradients
v4 expanded the gradient API from v3's eight linear directions to a full
three-family system (linear, radial, conic) with seven interpolation
colour spaces, angle-based linear gradients, and percentage stop positions.
v3 stays linear-only with the legacy bg-gradient-* prefix.
Companion skills :
tailwind-syntax-utility-classes : the broader background utility surface
tailwind-core-v3-vs-v4 : the v4-renamed utilities table (bg-gradient -> bg-linear)
tailwind-impl-migration-v3-v4 : codemod that handles the rename
ALWAYS run npx @tailwindcss/upgrade on v3-to-v4 migration : it renames
every to automatically. NEVER hand-edit
the rename across a large codebase ; the codemod is exhaustive.
linear-gradient({N}deg in oklab, var(--tw-gradient-stops))
-bg-linear-{N}
negative angle (e.g. -45deg)
bg-linear-(--my-angle)
reads from CSS variable
bg-linear-[25deg,red_5%,yellow_60%,lime_90%,teal]
fully arbitrary
Angle utilities REPLACE the v3 arbitrary-only pattern
bg-[linear-gradient(45deg,#A,#B)]. NEVER use the arbitrary form in v4
for simple angle gradients ; the utility is shorter and uses the configured
interpolation space.
ALWAYS include from-{color} AND to-{color} (and typically via-{color})
on a bg-conic. NEVER use bg-conic with only one stop : the gradient
collapses to a single colour and the conic effect is invisible.
ALWAYS pair from- with to-. NEVER ship a gradient with only from- ;
the to- defaults to transparent, which means the gradient fades to
nothing.
Color Stops : Position Utilities (v4)
<!-- from at 10%, via at 30%, to at 90% --><divclass="bg-linear-to-r
from-blue-500 from-10%
via-purple-500 via-30%
to-pink-500 to-90%"></div><!-- start the gradient OUTSIDE the box for a partial visible band --><divclass="bg-linear-to-r
-from-10% from-blue-500
to-pink-500"></div>
Utility
Sets
from-{N%}
--tw-gradient-from-position
via-{N%}
--tw-gradient-via-position
to-{N%}
--tw-gradient-to-position
-from-{N%}
negative starting position (gradient begins outside box)
v3 has NO native position utilities. Use arbitrary
bg-[linear-gradient(to_right,#A_10%,#B)] or stay on v3.
DEFAULT in v4 ; perceptually uniform, no muddy midpoints
/oklch
OKLCh
Polar variant of OKLab ; produces VERY vivid hue paths
/srgb
sRGB
Legacy CSS default ; produces gray midpoints between complementaries
/hsl
HSL
Polar; vivid rotation around hue wheel
/longer
(hue-based) longer-hue arc
Rainbows, full-circle conic gradients
/shorter
(hue-based) shorter-hue arc
Smooth two-colour transitions
/increasing
hue increasing
Forward hue rotation
/decreasing
hue decreasing
Reverse hue rotation
Source : https://tailwindcss.com/blog/tailwindcss-v4 ("Using polar color
spaces like OKLCH or HSL can lead to much more vivid gradients when the
from-* and to-* colors are far apart on the color wheel. We're using OKLAB
by default in v4.0").
NEVER use /srgb for a saturated red to saturated green gradient unless
you actively want the gray midpoint. The default /oklab and the polar
/oklch both keep the midpoint vivid.
Decision Tree : Which Interpolation?
Are the two colours close on the hue wheel (e.g. blue and purple)?
├── YES → default /oklab works
│ (no special modifier needed)
│
└── NO → Far apart (red and green, blue and orange)?
├── Smooth perceptual blend → /oklch
├── Vivid hue rotation through wheel → /hsl
├── Full circle through every hue → /longer
└── Want legacy CSS look (gray midpoint) → /srgb (explicit opt-in)
ALWAYS test /oklch against the default /oklab for complementary-colour
gradients ; the difference is dramatic. NEVER ship a red-to-green gradient
on /srgb by accident : you get a muddy gray middle.
Arbitrary Values
Every utility supports the [value] and (--var) escape hatches :
<!-- Full arbitrary linear gradient --><divclass="bg-linear-[25deg,red_5%,yellow_60%,lime_90%,teal]"></div><!-- Conic with explicit from + center + colour stops --><divclass="bg-conic-[from_45deg_at_50%_25%,red,blue,red]"></div><!-- Reading angle from CSS variable --><divclass="bg-linear-(--my-angle) from-blue-500 to-purple-500"></div>
Underscores convert to spaces in arbitrary values : bg-linear-[to_right]
emits linear-gradient(to right, ...).
v3 Pattern : Linear-Only With Arbitrary For Everything Else
<!-- v3 simple linear : utility available --><divclass="bg-gradient-to-r from-blue-500 to-purple-500"></div><!-- v3 angle gradient : MUST be arbitrary --><divclass="bg-[linear-gradient(45deg,theme(colors.blue.500),theme(colors.purple.500))]"></div><!-- v3 radial : MUST be arbitrary --><divclass="bg-[radial-gradient(circle,theme(colors.white),theme(colors.zinc.900))]"></div><!-- v3 conic : MUST be arbitrary --><divclass="bg-[conic-gradient(from_45deg,theme(colors.red.500),theme(colors.blue.500))]"></div><!-- v3 stop positions : arbitrary --><divclass="bg-[linear-gradient(to_right,theme(colors.blue.500)_10%,theme(colors.pink.500)_90%)]"></div>
theme(colors.blue.500) resolves the configured Tailwind colour at build
time in v3. v4 dropped this in favour of var(--color-blue-500).
