Gradient Gen User Guide

Gradient Gen is the advanced gradient generation package in tool/gradient-gen. It creates two-color, multi-stop and procedural gradients, samples them into color records, scores their perceptual behavior and exports them as design assets or datasets.

Use it when you need more than a visual CSS ramp: token-ready steps, generated gradient collections, machine-readable metadata, CIEDE2000 analysis, luminance and chroma summaries, compact SVG strips, API-ready JSON, or large NDJSON datasets for search and recommendation.

• Package: @auric-artisan/gradient-gen.
• Runtime: ESM Node package requiring Node 20 or newer.
• Main entry: tool/gradient-gen/src/index.js.
• Site data: data/gradient-gen/gradients.json, gradients.ndjson and index.json.
• Best fit: perceptual design ramps, generative palettes, data visualization ramps, theme exploration and gradient search datasets.

Work from the package directory when running examples, tests, generation scripts or benchmarks.

cd tool/gradient-gen
npm install
npm run example:basic
npm run example:export
npm test

Pass colors for evenly spaced stops or stops for explicit positions. The generator normalizes each stop into HEX, RGB, HSL, Lab, LCH, OKLab, OKLCH and luminance fields, then samples the ramp.

import { generateGradient, gradientCSS } from "./src/index.js";

const gradient = generateGradient({
  name: "Editorial launch ramp",
  colors: ["#0f172a", "#06b6d4", "#a3e635", "#f59e0b", "#be123c"],
  steps: 96,
  interpolationSpace: "oklch-short",
  easing: "smootherstep",
  angle: 120
});

console.log(gradient.colors.length);
console.log(gradient.metadata.analysis.score);
console.log(gradientCSS(gradient, { maxStops: 8 }));

For explicit placement, use stops:

const gradient = generateGradient({
  stops: [
    { color: "#030712", position: 0, label: "ink" },
    { color: "#38bdf8", position: 0.42, label: "signal" },
    { color: "#fef3c7", position: 1, label: "paper" }
  ],
  steps: 128,
  interpolationSpace: "oklab"
});

The package requires at least two colors. steps is clamped to the range from 2 to 65,536 inside createGradient().

If you omit colors and stops, generateGradient() creates a procedural recipe with generateComplexGradient(). The recipe chooses stop colors, stop positions, recommended sample count and metadata from the requested method and complexity.

const gradient = generateGradient({
  method: "aurora",
  complexity: "extreme",
  steps: 256,
  seed: 20260514,
  interpolationSpace: "oklch-long",
  easing: "sine-in-out"
});

Complexity profiles control default stop count and sample count. simple uses 2 to 4 stops, detailed uses 5 to 12 stops and extreme uses 16 to 64 stops.

Interpolation decides how colors move between stops. Easing decides how sample positions travel through the gradient.

• Fast device-space ramps: srgb and linear-rgb.
• Hue-wheel ramps: hsl-short and hsl-long.
• CIELAB ramps: lab, lch-short and lch-long.
• Modern perceptual ramps: oklab, oklch-short and oklch-long.

The short and long variants change hue direction. Short follows the shortest path around the hue circle. Long intentionally travels the other way and can create expressive color motion.

Easing options include linear, ease-in, ease-out, ease-in-out, sine-in, sine-out, sine-in-out, cubic-in, cubic-out, cubic-in-out, quart-in-out, exponential-in-out, smoothstep, smootherstep, step-8 and step-16.

Every gradient stores topology metadata used by gradientCSS() and gradientToCss().

const linear = generateGradient({ colors: ["#111827", "#f59e0b"], angle: 45 });
const radial = generateGradient({
  colors: ["#020617", "#38bdf8", "#fef3c7"],
  topology: "radial",
  radialShape: "circle"
});
const conic = generateGradient({
  colors: ["#ef4444", "#22c55e", "#3b82f6", "#ef4444"],
  topology: "conic",
  conicFrom: 30
});

The CSS export can downsample long gradients with maxStops, which is useful when a 1,024-sample ramp would produce an impractically long CSS declaration.

Metrics are enabled by default through includeMetrics. They live at gradient.metadata.analysis.

Disable metrics with includeMetrics: false when creating very large batches and you only need colors or CSS.

Use exportDataset() for file outputs and gradientCSS() for direct CSS.

import { generateGradientBatch, exportDataset } from "./src/index.js";

const gradients = await generateGradientBatch(12, {
  method: "mixed",
  complexity: "detailed",
  steps: 96,
  seed: 9001
});

await exportDataset(gradients, "./output/gradients.json", "json", { pretty: true });
await exportDataset(gradients, "./output/gradients.css", "css", { maxStops: 16 });
await exportDataset(gradients, "./output/gradients.svg", "svg");

• JSON: compact gradient objects with stops, sampled HEX colors and metadata.
• NDJSON: one compact gradient per line for streaming pipelines.
• CSV: one row per gradient with identity, stop count, sample count, interpolation, easing and CSS.
• CSS: class rules with background gradients.
• SVG: horizontal gradient strips with reusable linear gradient definitions.
• Binary: raw RGB sample bytes through createBinaryGradient() and dataset binary writers.

generateDataset() streams generated gradients through GradientDatasetGenerator and StreamingGradientWriter. It is designed for large counts without holding every gradient in memory.

import { generateDataset } from "./src/index.js";

const result = await generateDataset({
  gradientCount: 1000,
  outputPath: "./output",
  format: "ndjson",
  method: "mixed",
  complexity: "detailed",
  steps: 64,
  batchSize: 100,
  seed: 2026,
  onProgress: (p) => console.log(`${p.generated}/${p.total} at ${p.rate}/sec`)
});

Supported streaming formats are JSON, NDJSON, CSV and binary. Gzip compression is available in the streaming writer through compress: true, which writes a .gz file.

Site-compatible generation is handled by scripts/generate-data.js. It writes data/gradient-gen/gradients.json, gradients.ndjson, index.json and a short README.

cd tool/gradient-gen
npm run generate:data
node scripts/generate-data.js --count 512 --steps 80 --seed 20260525

The package is imported by the Auric Artisan API layer for JSON, PNG and GraphQL workflows.

• POST /v1/gradient/generate returns a gradient object and CSS.
• POST /v1/gradient/png renders a generated gradient as a PNG response.
• POST /v1/graphql exposes a gradient resolver.
• GET /v1/methods/gradient returns methods, profiles, spaces, easing methods and formats.

For direct package usage, prefer generateGradient(), gradientCSS() and getAvailableMethods(). The API layer is a transport wrapper around those functions.

• Use OKLCH or OKLab for perceptual ramps where evenness matters.
• Use linear RGB or sRGB when you need familiar browser-like interpolation behavior.
• Set seed on procedural gradients and datasets when you need reproducible color choices.
• Keep steps modest for CSS and SVG exports, then use higher values for analysis or image sampling.
• Disable includeMetrics for high-throughput generation when scores are not needed.
• Downsample CSS exports with maxStops before pasting into design systems.
• Use data/gradient-gen/index.json to confirm generated count, seed, methods and score ranges.
• Run tests after changing interpolation, metrics, exporters, dataset writers or generated site data.

For implementation details, see the Gradient Gen Developer Reference.