GradientSpector

GradientSpector 2.0 is a dependency-free collection of reusable CSS gradients. Download the generated files, copy a declaration, or consume the structured JSON data. No package installation, CDN, runtime JavaScript, account, or backend is required for users.

The release contains 328 canonical gradients and compatibility names for the complete collection.

Quick start

Download or copy dist/gradients.min.css into your project and host it with your own assets:

<link rel="stylesheet" href="./dist/gradients.min.css" />

<section class="gs-blue-lagoon">Gradient background</section>

The gs- prefix is the stable public naming convention. The generated CSS includes a background-color fallback followed by a standard linear-gradient declaration.

Copy one gradient

The equivalent declarations for blue-lagoon are:

background-color: #0052d4;
background-image: linear-gradient(90deg, #0052d4 0%, #4364f7 100%);

Use these declarations anywhere CSS is accepted. The collection does not require a framework or a JavaScript helper.

Download the library

The generated distribution files are available in dist/:

File	Use it for
gradients.css	Readable CSS classes
gradients.min.css	Smallest CSS class build
variables.css	Readable CSS custom properties
variables.min.css	Smallest custom-property build
gradients.json	Full records, tags, positions, and provenance
colors.json	Compact ID-to-hex-color mapping
gradients.csv	Spreadsheet and design-tool import

All files are intended to be downloaded and self-hosted. The CSS and variable files contain generated-file notices; edit the source data and regenerate the distribution rather than editing those files directly.

CSS variables

Load the variable build when the gradient value needs to be composed into another rule:

<link rel="stylesheet" href="./dist/variables.min.css" />

.hero {
  background-image: var(--gs-blue-lagoon);
}

.swatch-start {
  background-color: var(--gs-blue-lagoon-color-1);
}

Each canonical record provides one complete --gs-{id} gradient variable and one --gs-{id}-color-{n} variable per color stop.

JSON and hex values

The full JSON export is suitable for tools that need names, angles, tags, and source metadata:

const gradients = await fetch("./dist/gradients.json").then((response) =>
  response.json(),
);
const blueLagoon = gradients.find((gradient) => gradient.id === "blue-lagoon");

For a smaller color-only mapping, use dist/colors.json:

{
  "blue-lagoon": ["#0052D4", "#4364F7"]
}

Build from source

Consumers do not need a JavaScript runtime. Maintainers who edit the dataset need Bun 1.x:

bun install
bun run check
bun run build

data/gradients.json is the single source of truth. scripts/build.js generates every file in dist/ in a stable order. Repeated builds are deterministic and do not include timestamps.

Build the landing page

After adding or editing a gradient in data/gradients.json, rebuild the generated files and refresh the static website with:

bun run build:landing-page

This regenerates dist/ first, then refreshes the landing page's optional local data fallback.

Browser compatibility

The output uses standard CSS gradients supported by current browsers and includes a solid-color fallback for older browsers. It does not add vendor-specific runtime code. The fallback is the first color stop and should be treated as a graceful degradation, not as a contrast guarantee.

Compatibility names

Earlier releases used unprefixed names, underscores, spaces, and a few selectors that do not target a single class correctly. Prefer canonical IDs in new code:

Earlier selector	Canonical class
.blu	.gs-blue-steel
.bluelagoon	.gs-blue-lagoon
.80s_purple	.gs-eighties-purple
.black_rosé	.gs-black-rose
.deep purple	.gs-deep-purple

Valid compatibility selectors remain in the CSS build. Names that cannot be represented as one CSS class should be replaced with their canonical class. The complete alias map is available in data/aliases.json.

Contributing

Add or update gradients only in data/gradients.json. Every contribution needs a stable kebab-case ID, at least two valid colors, tags, source information, and permission to redistribute the work. Run bun run check before opening a pull request. Read CONTRIBUTING.md for the data rules and review checklist.

Attribution and license

The repository and its records are distributed under GNU GPL-3.0 while source and rights information is maintained. The generated CSS credits Salman Hossain Saif saif71.com; special thanks to uiGradients. See docs/licensing.md for the attribution and provenance policy.