GradientAccessible color scales from one brand color, where the step number tells you the contrast. Light and dark mode, OKLCH, export for Tailwind and CSS.
npx @sweberdev/gradient "#e30613" --format tailwind --out app/gradient.cssGradient turns one brand color into eleven steps from 50 to 950, for light and dark mode, plus a grey tinted with your hue. Most palette generators space lightness evenly, so contrast depends on the hue: blue-600 passes on white, yellow-600 often does not. Gradient solves every step for a fixed contrast instead. Step 500 always reaches 3:1, step 600 4.5:1 and step 800 7:1 against the page, in dark mode against black, for every color you start from.
Colors are computed in OKLCH and brought into sRGB by lowering chroma only, so the contrast stays where it was solved. Every step comes with a readable text color for buttons and badges. Export the palette as a Tailwind CSS v4 theme, a Tailwind v3 config, CSS custom properties, W3C design tokens or JSON, from code or with one CLI command. No dependencies, MIT-licensed.
Example
A short exampleCopy it into your project.
scripts/colors.ts
import { checkPalette, createPalette, toTailwind } from "@sweberdev/gradient"
import { writeFileSync } from "node:fs"
const palette = createPalette({ brand: "#e30613", accent: "#0a84ff" })
writeFileSync("app/gradient.css", toTailwind(palette))
// bg-brand-50, text-brand-700, bg-brand-600 text-brand-on-600 …
console.log(checkPalette(palette).every((c) => c.pass)) // trueFeatures
What you getFree under MIT, with Pro on top.
Free, MIT
- A full shadcn/ui theme from one brand colour
- Eleven steps per colour with guaranteed contrast, light and dark
- Colour vision check and chart colours that stay apart
- Export as Tailwind v4, Tailwind v3 or CSS variables
- Contrast checks and a GitHub Action for CI
All features in detail
Free, MIT
- shadcn/ui theme from one color: all semantic variables for light and dark mode with the contrast promises intact
- Eleven steps from one color, with fixed contrast per step: 500 ≥ 3:1, 600 ≥ 4.5:1, 800 ≥ 7:1 on the page
- Dark mode with the same step numbers and the same promises, so one set of classes works in both modes
- OKLCH throughout, with gamut mapping that never moves lightness
- A neutral grey tinted with your brand hue, and a readable text color for every step
- Status colors on request: success, warning, danger and info that match your brand and keep the same contrast promises
- Color vision check: simulates protanopia, deuteranopia and tritanopia and flags colors that look alike
- Chart colors, up to eight, that stay apart with protanopia, deuteranopia and tritanopia
- Export as Tailwind CSS v4 theme, Tailwind v3 config, CSS variables (also with light-dark()), Sass, TypeScript, W3C design tokens or JSON
- Contrast checks for CI, also when you pin your exact brand color
- Check any two colors with gradient check: WCAG 2 levels, APCA, and the closest color that passes
- Audit an existing stylesheet with gradient audit: finds steps that break the contrast promises and suggests one fixing color per step
- Gradients between brand colors, blended in OKLCH so complementary colors do not turn grey, with a contrast check of your text on the worst stop
- Dominant colors from a logo or photo, and a pick for the brand color, from raw pixels without any dependency
- One gradient.config.json for every output: gradient build writes all files, gradient build --verify fails in CI when one is out of date, with a JSON schema for editor completion
- GitHub Action that checks pull requests for out-of-date color files and contrast problems and keeps one comment with the result
- Stability policy and tests that guard it: the exported API and every output format are snapshot-tested, so generated colors stay identical within a major version
- Guides for WCAG 2.2 and EAA coverage, recipes for Next.js, Vite and theme editors, and a migration guide from the Tailwind default colors
- Tested on Node.js 20 and 22, Bun and Deno in CI; the whole library is about 10 kB gzipped, tree-shakeable, and runs in browsers and edge runtimes
- CLI and a zero-dependency library that runs in Node.js and the browser
FAQ
QuestionsShort answers.
Does Gradient keep my exact brand color?
By default the closest step gets your hue and chroma, with lightness adjusted to the contrast of that step. Pass --pin to keep the exact color; the contrast check then tells you if that breaks a promise.
Why are the colors in OKLCH?
OKLCH is perceptually even: the same lightness looks equally bright in every hue, and chroma changes do not shift the hue. All browsers since 2023 support it. Use the hex export for older ones.
Does a passing contrast check make my site accessible?
It covers the contrast criteria of WCAG 2.2 (1.4.3, 1.4.6 and 1.4.11). It cannot tell whether information depends on color alone or how the colors are used. For checks of the whole site, see Surjection.
Is there a paid version?
No. Gradient is MIT-licensed and complete. It is also the color foundation of the upcoming UI library Lattice.
Can people with a color vision deficiency tell my colors apart?
Run gradient --check or checkDistinguishable(). It simulates protanopia, deuteranopia and tritanopia and lists the pairs that look alike at step 600. For those, add an icon or a label: color alone is never enough for status messages.
Does Gradient support APCA?
gradient check and checkPair() show the APCA value (Lc) next to the WCAG 2 ratio. Pass and fail follow WCAG 2.2, because that is the standard the European Accessibility Act refers to; APCA is part of the WCAG 3 draft and shown for information.
How do I use Gradient with shadcn/ui?
Run npx @sweberdev/gradient "#e30613" --format shadcn --out app/globals.css and replace the theme section of your globals.css. The file has the variables for :root and .dark and the @theme inline mapping for Tailwind v4. Text on background reaches 7:1, buttons and badges 4.5:1, form field borders 3:1.
Can I use Gradient for colors I already have?
Yes. gradient audit app/globals.css reads custom properties that end in a step number (--color-brand-600, --blue-500), from :root, a dark class or media query, or light-dark(), checks the pairs the step numbers promise and suggests a color that passes. It exits with 1 on a failing pair, so it works in CI.
Why does a gradient between blue and yellow look grey in CSS?
CSS blends in sRGB by default, and the average of two opposite colors there is a grey. gradient blend and createBlend() blend lightness, colorfulness and hue instead, so the middle stays as colorful as the ends. Current browsers can do the same with linear-gradient(in oklch, …); createBlend returns both strings.
Can Gradient read a color from my logo?
extractColors() takes the pixels of an image (RGBA, for example ImageData.data from a canvas) and returns the dominant colors with their share; pickBrand() chooses the one that works as a brand color. There is no command line version because the command line cannot decode images, and nothing is uploaded: the demo reads the image in your browser.
How do I keep generated color files up to date in CI?
Put your colors in gradient.config.json (gradient init writes a starter file) and run gradient build --verify in CI. It writes nothing and exits with 1 when a file is missing or differs, a contrast promise fails or an audited stylesheet fails. The GitHub Action Weber-Development/gradient@v0 does the same on pull requests and comments the result.
Will my generated files change when I update Gradient?
Not within a major version: for the same input and options the generated colors and files stay byte for byte the same, unless a release fixes a broken contrast promise, which the changelog names. The tests snapshot every output format to enforce this. Run gradient build --verify in CI to see whether committed files differ.
Is Gradient 1.0 stable?
Yes. From 1.0 the exported API, the command line, the config file and the generated files follow semantic versioning: within 1.x the same input gives byte-for-byte the same files and the contrast promises are never weakened. The tests snapshot the exported names and every output format, and CI runs the built package on Node.js 20 and 22, Bun and Deno. The stability page in the docs lists what may change in a minor version.
Articles