CSS Magic Gradient
TypeScript library for generating CSS gradients — linear, radial, conic — with presets, color harmony generators, WCAG accessibility utilities, and Vue/React hooks.
When you'd reach for this
A gradient that looks smooth in a design mockup can show muddy transitions and visible banding in the browser — css-magic-gradient computes the transition through more accurate color spaces instead of a straight line between two colors, so no banding survives to the output.
A background needs to match brand colors
A brand's design system defines one accent color — the rest of the gradient is generated automatically as a harmonious scheme around it, instead of hunting for neighboring shades by eye.
Text over a gradient isn't readable everywhere
Light text reads fine on the dark end of a gradient and disappears on the light end — contrast can be checked across the whole transition at once, and the color stops shifted automatically so the text stays readable everywhere.
A social preview image is generated without a browser
An image for a shared link gets built on the server when an article is published, not painted by hand each time — the same gradient used on the site can be rendered straight into a plain image file, no browser and no designer required.
Only gradient generation is needed, no extra framework
The utility gets used in a plain TypeScript script or an entirely different framework — Vue and React stay out of the build, even if the rest of the project happens to use them for something else.
At a glance
All‑type gradient generation
Create linear, radial, and conic gradients with auto‑brightness, explicit color stops, or color harmony‑based stops. Support for CSS variables, CSS Color Level 4 interpolation (Oklch, Lab, HSL), and repeating variants. All settings are flexibly configurable for any task.
Harmonies, palettes, and presets
Instantly generate complementary, triadic, analogous, tetradic, and other harmonic schemes with Oklab/LCH interpolation. Build tints, shades, and tones palettes. Use 15 ready‑to‑use presets (sunset, ocean, aurora, and more) for a quick start.
WCAG accessibility
Analyze text contrast on gradients with 11‑point sampling, determine WCAG level, and locate problematic spots. The auto‑adjustment function fine‑tunes gradient stops to meet AA or AAA targets by adjusting lightness, saturation, or both.
Canvas export and CSS variable utilities
Render gradients to CanvasGradient, ImageData, or DataURL for image generation and Open Graph cards. Extract and substitute CSS variable values in gradient strings. All utilities work both in the browser and on the server (with canvas library support).
Vue 3 and React integration
Use 15 reactive hooks for Vue 3 (ComputedRef) and React (useMemo) — all SSR‑safe and auto‑update when inputs change. Vue hooks are available via a plugin, React hooks are imported from a separate subpath. The only runtime dependency is color‑value‑tools.
Isolated entry points
The core package never pulls Vue or React into your bundle — framework‑specific code lives in dedicated import subpaths, so using only gradient generation keeps that extra code out of your build. The library is fully tree‑shakeable and marked sideEffects: false.
See how it works
A gradient that doesn't wreck text readability
createAccessibleGradient adjusts the colors' lightness (or saturation) until white text stays readable across the whole gradient, not just at its ends — checked against real WCAG contrast.
import { createAccessibleGradient } from 'css-magic-gradient'
const gradient = createAccessibleGradient('#3498db', '#ffffff', {
targetLevel: 'AA',
})
// Adjusts lightness (or saturation) in small steps until white text stays
// readable across the whole gradient — not just at its two endpoints,
// checked against real WCAG contrast ratios.
