Shade Gen User Guide

Shade Gen creates tokenized shade systems from a base color or deterministic seed. It works in OKLCH, clips chroma back into displayable sRGB, preserves the requested base token by default and reports WCAG contrast against black and white for every generated shade.

• Package: @auric-artisan/shade-gen.
• Main entry: tool/shade-gen/src/index.js.
• High-level API: tool/shade-gen/src/api/api.js.
• Public library: Shade Library.
• Site data: data/shade-gen/shades.json, preview.json, preview.css and index.json.

Use Shade Gen when you need a design-token scale, not just a list of colors. It is tuned for UI palettes where light tokens, base tokens, dark tokens, contrast and export formats all need to line up.

Shade Gen is an ESM package and requires Node 20 or newer.

cd tool/shade-gen
npm run example:basic
npm test

generateShadeScale() accepts method, base, steps, seed, index, tokens, preserveBase and includeMetrics.

Pass method: "mixed" for deterministic datasets. Mixed mode chooses methods by weighted probability, favoring brand-system, accessible-ui and tailwind-like.

Shade Gen supports 2 to 64 colors per scale. Built-in token presets are optimized for common design systems.

By default the base color is placed at token 500, base or 50 if one exists, otherwise near the middle of the scale. Override with baseIndex on createShadeScale() or pass custom tokens when integrating with an existing design system.

import {
  generateShadeScale,
  evaluateShade,
  shadeCSS,
  shadeTailwind
} from "./src/index.js";

const scale = generateShadeScale({
  base: "#d3af37",
  method: "brand-system",
  steps: 11,
  seed: 20260526
});

console.log(scale.steps.map((step) => `${step.token}: ${step.hex}`));
console.log(evaluateShade(scale).score);
console.log(shadeCSS(scale, { prefix: "auric-gold" }));
console.log(shadeTailwind(scale, { name: "auricGold" }));

A generated scale contains shade_id, name, base, method, tokens, steps and metadata. Every step includes HEX, RGB, OKLCH, luminance, contrast against white and black, token, index, role and gamut-clipping metadata.

{
  "shade_id": "shade_000000",
  "name": "Brand System #D3AF37 #00001",
  "base": { "hex": "#d3af37", "token": "500" },
  "method": "brand-system",
  "tokens": ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950"],
  "steps": [
    {
      "token": "50",
      "hex": "#fff6e3",
      "rgb": [255, 246, 227],
      "oklch": [0.975, 0.027, 85.664],
      "contrast": { "white": 1.075, "black": 19.544 },
      "role": "tint"
    }
  ],
  "metadata": {
    "base_index": 5,
    "step_count": 11,
    "preserve_base": true,
    "score": 0.5687
  }
}

evaluateShade(scale) returns a quality report for the scale.

Treat score as a sorting and QA signal. Still check the actual token pair you plan to use, especially for UI text, state colors and data visualization labels.

The public Shade Library browses the generated shade dataset with the same interaction model as the Palette Library. It loads /data/shade-gen/shades.json and normalizes compact records in the browser.

• Browse 8,192 generated shade systems.
• Search by shade id, name, base, method, token or HEX.
• Filter by method, hue bucket, chroma and lightness.
• Sort by original order, lightness, chroma, hue, score, token count or random order.
• Inspect token colors with HEX, RGB, OKLCH, CIE Lab and WCAG contrast.
• Use Harmony, Accessibility and Stats tabs for analytics on the filtered results.
• Export selected scales as HEX, CSS, SCSS, Tailwind, JSON, SVG, PNG or design tokens.
• Export the filtered results as JSON, compact JSON, CSV, CSS, SCSS, HEX list or Tailwind fragments.
• Save shade systems to browser storage and the Auric Artisan Library workspace mirror.

Current site data uses expanded compact records like { id, n, b, m, t, c, s }, where n is name, b is base, m is method, t is tokens, c is colors and s is score. The dataset index file describes count, seed, format and available methods.

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

const scales = generateShadeBatch(8, {
  seed: 20260526,
  method: "mixed",
  steps: 11
});

await exportDataset(scales, "./output/shades.json", "json", { pretty: true });
await exportDataset(scales, "./output/shades.ndjson", "ndjson");
await exportDataset(scales, "./output/shades.csv", "csv");
await exportDataset(scales, "./output/shades.css", "css");
await exportDataset(scales, "./output/shades.scss", "scss");
await exportDataset(scales, "./output/shades.tailwind.js", "tailwind");
await exportDataset(scales, "./output/shades.svg", "svg");

Use ShadeDatasetGenerator or generateShadeDataset() to write deterministic datasets without holding every scale in memory.

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

const result = await generateShadeDataset({
  shadeCount: 8192,
  outputPath: "./output",
  format: "json",
  mode: "compact",
  method: "mixed",
  steps: "mixed",
  seed: 20260514,
  batchSize: 10000,
  includeMetrics: true
});

The site data script writes the public data files:

cd tool/shade-gen
node scripts/generate-data.js --count 8192 --format json
node scripts/generate-data.js --count 8192 --format compact
node scripts/generate-data.js --count 50000 --format ndjson --progress true

• shades.json is the main public shade dataset or manifest, depending on format.
• preview.json contains the first 64 site-friendly shade systems.
• preview.css contains CSS variables for preview shades.
• index.json records count, seed, format, method, steps and available methods.
• README.md documents the generated data folder.

Compact manifest mode writes only deterministic settings and count. Rehydrate slices with hydrateShadeManifest(manifest, { offset, limit }). Expanded JSON mode writes the current { id, n, b, m, t, c, s } records consumed by the Shade Library.

The API layer imports Shade Gen directly for generation, metadata, GraphQL and export routes.

• POST /v1/shade/scale returns a generated shade scale.
• POST /v1/shade/export exports a scale as CSS, SCSS, Tailwind or SVG.
• GET /v1/methods/shade returns shade methods and step presets.
• POST /v1/graphql exposes the shadeScale resolver.
• shade-dataset jobs route to the dataset API for bounded job generation.

The HTTP scale endpoint currently accepts method, seed, steps and hue. The package API also supports base, index, custom tokens and preserveBase, so prefer direct package usage for full control.

• Use brand-system or tailwind-like for general product scales.
• Use accessible-ui when text contrast coverage matters most.
• Use neutral-system or ink-paper for surfaces, text, borders and subtle UI scaffolding.
• Use preserveBase: true when a brand color must remain exact at the base token.
• Use custom tokens when integrating with an existing naming scheme.
• Review gamut.clipped_steps if a vivid base color produces dull edge colors.
• Use includeMetrics: false for faster bulk generation when score data is not needed.
• Run tests after changing token presets, OKLCH conversion, method settings, exports or dataset shape.

For implementation details, see the Shade Gen Developer Reference.