Palette Gen User Guide

Palette Gen is the scientific palette engine in tool/palette-gen. It creates palette objects from harmony geometry, mathematical hue sampling, perceptual spacing, evolutionary search, simulated annealing or seeded random bytes. Each palette can carry color conversions, Delta E, entropy, contrast and mood metadata, so the output is usable for design systems, accessibility reviews, data generation and research experiments.

• Package: @auric-artisan/palette-gen.
• Main entry: tool/palette-gen/src/index.js.
• High-level API: tool/palette-gen/src/api/api.js.
• Public library: Palette Library.
• Site data: data/palette-db/palettes.json, a compact deterministic manifest for 5,000,000 palettes.

The engine is best used when you need more than a pleasing HEX list: it gives you reproducible palette generation, perceptual measurements, WCAG contrast information and export formats that fit both design tools and data pipelines.

Palette Gen is an ESM package and requires Node 20 or newer. The package already has its own package.json, lockfile and examples.

cd tool/palette-gen
npm install
npm run example:basic

Optional dependencies unlock heavier formats or acceleration: gpu.js for GPU.js kernels, apache-arrow for Arrow export and parquetjs-lite for Parquet export. The core API works without those optional packages because it has CPU fallback paths.

The high-level generatePalette() function accepts a method, count, hue, saturation, lightness and optional seed. Use getAvailableMethods() to list the current method groups.

Method names are case-sensitive. The public harmony list uses splitComplementary while the dataset manifest currently uses simpler method names such as complementary, triadic, analogous, tetradic, golden_ratio, random and monochromatic.

Import from the package entry when you want the public API and lower-level modules available in one place.

import {
  generatePalette,
  getAvailableMethods,
  evaluatePalette,
  simulateColorBlindness
} from "./src/index.js";

const methods = getAvailableMethods();

const palette = generatePalette({
  method: "triadic",
  count: 5,
  hue: 210,
  saturation: 0.7,
  lightness: 0.55,
  seed: 20260526
});

console.log(palette.palette_id);
console.log(palette.colors.map((color) => color.hex));
console.log(palette.metadata.deltaE_avg);

const evaluation = evaluatePalette(palette);
const cvd = simulateColorBlindness(palette);

The result is a palette object with palette_id, colors[] and metadata. Each color includes hex, rgb, oklch and lab. Metadata includes method, color count, timestamp, average Delta E, entropy, contrast matrix and a primary mood label.

{
  "palette_id": "pal_lx0a9abc_1",
  "colors": [
    {
      "hex": "#3399d6",
      "rgb": [51, 153, 214],
      "oklch": [0.65, 0.13, 239.8],
      "lab": [60.9, -8.4, -42.7]
    }
  ],
  "metadata": {
    "method": "triadic",
    "color_count": 5,
    "deltaE_avg": 63.41,
    "entropy": 0.86,
    "mood": "balanced"
  }
}

Palette Gen measures palettes in color-science terms so you can compare generated sets instead of judging by thumbnail alone.

evaluatePalette(palette) returns metrics, accessibility, mood and an overall score. The score uses diversity, uniformity, contrast and entropy weights, so it is a useful ranking signal but not a replacement for design intent.

Palette Gen includes WCAG contrast and color vision deficiency helpers. Use them before turning generated colors into text, charts, UI states or tokens.

const report = evaluatePalette(palette);

console.log(report.accessibility.wcag.summary.minPairContrast);
console.log(report.accessibility.wcag.colors[0].onWhite.AA_normal);
console.log(report.accessibility.cvdSafeScore);

const simulation = simulateColorBlindness(palette);
console.log(simulation.protanopia);
console.log(simulation.deuteranopia);
console.log(simulation.tritanopia);

• wcagCompliance() reports AA and AAA results for normal and large text.
• evaluatePaletteAccessibility() checks each color on white, on black and against other palette colors.
• simulateColorBlindness() returns protanopia, deuteranopia and tritanopia simulations.
• colorBlindnessSafeScore() estimates how separated palette colors remain after simulations.

The pairwise summary field named allPairsPassAA is based on the implementation's AA-large threshold for color pairs. For body text, inspect the normal text booleans on the exact foreground/background pair you plan to use.

The public Palette Library is the browser UI for Palette Gen output. It lets you browse, inspect, save and export palettes without downloading the full expanded dataset.

• Browse 5,000,000 deterministic palettes generated from data/palette-db/palettes.json.
• Search by palette id or HEX value, then filter by hue, chroma, lightness and method.
• Open the Harmony, Accessibility, Stats, Export and Saved tabs at any time; there is no simple or advanced mode.
• Inspect RGB, OKLCH, Lab, contrast, harmony label and palette stats for a selected palette.
• Save palettes to local storage and the Auric Artisan Library workspace mirror.
• Export a selected palette as HEX, CSS, SCSS, Tailwind, JSON, ASE, SVG or PNG.
• Export the analysis sample, up to 2,000 palettes that match the filters, as JSON, compact JSON, CSV, CSS variables, SCSS variables, HEX list or a Tailwind fragment.

The manifest stores schema, format, source, generated_at, count, colors_per_palette, seed, batch_size, batch_seed_stride and methods. The browser viewer materializes only the palettes in view (or the chunks a filter scans), a sample of up to 2,000 for the analytics panels, the selected palette and saved items.

The package-level export module writes file-based datasets. The Palette Library and API layer also provide in-memory exports for browser and HTTP workflows.

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

const palettes = [
  generatePalette({ method: "triadic", hue: 210, count: 5 }),
  generatePalette({ method: "golden_ratio", hue: 25, count: 5 }),
  generatePalette({ method: "uniform_perceptual", count: 7 })
];

await exportDataset(palettes, "./output/palettes.json", "json", { pretty: true });
await exportDataset(palettes, "./output/palettes.ndjson", "ndjson");
await exportDataset(palettes, "./output/palettes.csv", "csv");
await exportDataset(palettes, "./output/palettes.bin", "binary");

getSupportedFormats() returns the package export formats: json, ndjson, csv, binary, arrow and parquet.

generateDataset() streams palette objects without retaining the full dataset in memory. It creates batches with a deterministic xorshift CPU path, adds optional metrics and writes through StreamingPaletteWriter.

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

const result = await generateDataset({
  paletteCount: 100000,
  colorsPerPalette: 5,
  outputPath: "./output",
  format: "ndjson",
  method: "mixed",
  compress: false,
  includeMetrics: true,
  seed: 42,
  onProgress: (p) => console.log(`${p.generated}/${p.total} at ${p.rate}/sec`)
});

The command-line wrapper is designed for quick local generation:

cd tool/palette-gen
node scripts/generate-dataset.js 1000000 ndjson ./output
node scripts/generate-dataset.js 10000000 csv ./output
node scripts/generate-dataset.js 100000000 binary ./output

• The command-line binary format uses the optimized raw binary path and a 16-byte header.
• includeMetrics is useful for analysis but should be disabled for maximum throughput.
• method: "mixed" cycles deterministic method labels across the dataset manifest set.
• compress: true writes gzip output from the streaming writer.

The Auric Artisan API layer imports Palette Gen directly for generation, evaluation and metadata workflows; palette export uses the API's own in-memory exporter.

• POST /v1/palette/generate returns a generated palette object.
• POST /v1/palette/evaluate returns metrics, accessibility, mood and score for an input palette.
• GET /v1/methods/palette returns the method groups.
• POST /v1/palette/export exports a palette through in-memory API formats.
• POST /v1/graphql exposes palette generation through the GraphQL handler.

The HTTP handler validates count from 1 to 64, rejects HSL values outside their expected ranges and passes seed when provided. For bulk generation, use the package dataset API rather than the request handler.

• Use harmony methods when the palette needs a familiar color-theory shape.
• Use scientific methods when perceptual spacing matters more than color-theory labels.
• Use evolutionary or annealing methods when you want search-based optimization and can afford extra CPU cost.
• Use deltaE_spaced, kmeans, evolutionary and annealing with a seed for repeatable outputs.
• Do not assume every high-level method is seeded; the default and random branches use Math.random().
• Inspect real foreground/background pairs before using a palette for UI text.
• Keep includeMetrics off for giant datasets when metrics are not needed in the exported file.
• Use the compact manifest pattern for public web browsing instead of shipping expanded multi-GB JSON arrays.
• Run smoke imports, examples and root site validation after changing algorithms, exports, manifests or API adapters.

For implementation details, see the Palette Gen Developer Reference.