Shade Gen Developer Reference

tool/shade-gen/package.json defines @auric-artisan/shade-gen, an ESM package that requires Node 20 or newer. It exposes the root entry plus subpath exports for every major layer.

The root entry exports generateShadeScale, generateShadeDataset, datasetShadeOptions, hydrateShadeManifest, evaluateShade, shadeCSS, shadeSCSS, shadeTailwind, shadeSVG, getAvailableMethods and getSupportedFormats.

src/api/api.js is a thin facade over algorithms, metrics, datasets and exporters.

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

const scale = generateShadeScale({
  base: "#006adc",
  method: "accessible-ui",
  steps: 11,
  seed: 20260526
});

const report = evaluateShade(scale);
const css = shadeCSS(scale, { prefix: "brand-blue" });

createShadeScale() in src/core/shade.js creates the core object. The base and each step are produced by colorRecord() from src/core/color.js.

{
  shade_id: "shade_000000",
  name: "Accessible Ui #006ADC #00001",
  base: {
    hex: "#006adc",
    rgb: [0, 106, 220],
    oklch: [0.543, 0.193, 257.01],
    luminance: 0.155,
    contrast: { white: 5.128, black: 4.095 },
    token: "500",
    index: 5
  },
  method: "accessible-ui",
  tokens: ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950"],
  steps: [
    {
      token: "50",
      index: 0,
      role: "tint",
      hex: "#f9fbff",
      rgb: [249, 251, 255],
      oklch: [0.988, 0.006, 264.533],
      luminance: 0.964,
      contrast: { white: 1.036, black: 20.271 },
      clipped: true,
      requested_oklch: [0.988, 0.027, 255.01],
      actual_chroma: 0.006
    }
  ],
  metadata: {
    base_index: 5,
    step_count: 11,
    preserve_base: true,
    generated: true,
    source: "@auric-artisan/shade-gen",
    seed: 20260526,
    dataset_index: 0,
    generator_method: "accessible-ui",
    analysis: {},
    score: 0.619
  }
}

Roles are tint, base and shade. clipped marks requested OKLCH colors whose chroma had to be reduced to fit sRGB.

src/core/color.js is focused on RGB, HEX, OKLab, OKLCH and WCAG contrast. It does not depend on browser APIs.

• hexToRgb(), rgbToHex() and normalizeRgb() handle web color input.
• rgbToOklab(), oklabToRgb(), rgbToOklch() and oklchToRgb() implement OK color conversion.
• oklchToRgbGamut() binary-searches chroma to keep the requested color in sRGB gamut.
• relativeLuminance() and contrastRatio() provide WCAG contrast values.
• deltaOklab() measures OKLab distance between adjacent shade steps.
• colorRecord() normalizes a color into HEX, RGB, OKLCH, luminance and contrast fields.

Since every generated step uses colorRecord(), any change to contrast, normalization or OKLCH conversion affects exports, tests, dataset files and the Shade Library.

SHADE_TOKENS maps common step counts to design-token labels: 2, 3, 5, 7, 9, 10, 11 and 13. Any other count from 2 to 64 uses generated numeric tokens from 000 to 1000.

METHOD_SETTINGS defines each recipe with maxL, minL, chroma, edgeChroma and hueDrift. The current methods are:

• oklch-ramp
• brand-system
• accessible-ui
• neutral-system
• material-like
• tailwind-like
• vivid-product
• duotone-shift
• temperature-shift
• ink-paper

baseIndexForTokens() prefers token 500, then base, then 50, before falling back to the middle of the scale.

buildSteps() anchors the scale at the base index, then interpolates upward to maxL for tints and downward to minL for shades.

• Tint-side lightness uses easeInOutCubic().
• Shade-side lightness uses smootherstep().
• Chroma is tapered with a sine edge curve so extreme light and dark steps are less saturated.
• neutral-system and ink-paper cap chroma to keep scales subdued.
• Hue drift is applied around the base hue; temperature-shift reverses drift direction.
• preserveBase keeps the base token exact instead of recalculating it.

High-level generation in src/algorithms/generators.js adds deterministic base color creation. generateBaseColor() uses seed, index, optional hue and vividness to pick an OKLCH base, then converts it through gamut-safe sRGB.

src/metrics/metrics.js evaluates shade scales for consistency, contrast and gamut behavior.

The score formula weights uniformity at 0.28, monotonicity at 0.24, accessibility at 0.28, clipping safety at 0.12 and luminance range at 0.08.

src/dataset_engine/generator.js contains ShadeDatasetGenerator, datasetShadeOptions(), generateShadeDataset() and hydrateShadeManifest().

const generator = new ShadeDatasetGenerator({
  batchSize: 10000,
  seed: 20260514,
  includeMetrics: true,
  method: "mixed",
  steps: "mixed"
});

const result = await generator.generateDataset({
  shadeCount: 8192,
  outputPath: "./output",
  fileName: "shades.json",
  format: "json",
  mode: "compact"
});

• DATASET_STEP_WEIGHTS favors 11-step scales, then 9, 7 and 13-step scales.
• datasetShadeOptions() deterministically chooses method and step count from seed and index.
• generateDataset() writes through StreamingShadeWriter and reports progress.
• hydrateShadeManifest() rehydrates compact manifest slices by offset and limit.

API note: the shade-dataset job in api/lib/handlers/jobs.js does not call generateShadeDataset(), which writes to a file and reads shadeCount. It builds the requested count (1-10,000) in memory with hydrateShadeManifest().

src/dataset_engine/streaming.js defines the compact, full and CSV record shapes.

format: "compact" writes a deterministic manifest with schema: "aa.shade-db.compact.v1", source, description, count and generation options. format: "json" writes a JSON array of records (compact records unless mode: "full"), which is what the current public data/shade-gen/shades.json uses.

src/export/exporters.js provides string helpers and file-writing exporters.

API export support is narrower than package export support. POST /v1/shade/export currently allows CSS, SCSS, Tailwind and SVG only.

scripts/generate-data.js writes the public data/shade-gen folder. It accepts --output, --count, --seed, --format, --method, --steps, --batch, --metrics and --progress.

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

library/shades/index.html is the page shell and library/shades/shade-library.js is the runtime. The page includes the Auric Artisan cursor, scroll and loader layers, preloads /data/shade-gen/shades.json and exposes Library, Inspect, Harmony, Accessibility, Stats, Export and Saved panels.

The runtime accepts either arrays of compact records or objects with shades or samples. normalizeShade() maps each record to:

• shade_id, index, name, base, method, tokens and colors.
• Per-color HEX, RGB, Lab, OKLCH and contrast.
• Derived average lightness, chroma, hue bucket, hue spread, token count and score.
• Search text, AA auto-text count, white AA count, black AA count and minimum adjacent contrast.

Saved items are mirrored to the Library workspace with domain shades and tool id library-shades. Share links use the share router type shade.

• api/lib/handlers/shade.js imports shadeScale for /v1/shade/scale.
• api/lib/handlers/export.js imports shade exporters for /v1/shade/export.
• api/lib/handlers/meta.js imports getAvailableMethods for /v1/methods/shade.
• api/lib/handlers/graphql.js exposes shadeScale(args).
• api/lib/handlers/jobs.js builds shade-dataset jobs with hydrateShadeManifest().

The request handler parses color (or base), passed on as the base colour, and method, seed and steps. generateShadeScale() has no hue option, so when no colour is sent the handler turns hue into a base colour with generateBaseColor().

tests/shade.test.js uses Node's built-in test runner. It covers:

• 11-step brand generation and exact base preservation.
• 2-step and 32-step generation.
• Contrast coverage, uniformity and score from evaluateShade().
• CSS and Tailwind snippet exports.
• Deterministic batches with repeated seeds.
• Compact manifest hydration by offset and limit.

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

Use benchmark results as relative performance signals after changing conversion, metrics, generation or streaming behavior.

• Keep METHOD_SETTINGS, METHOD_WEIGHTS, docs, API metadata and library filters aligned.
• Update tests when changing token presets, base-index rules, score weights or contrast thresholds.
• Regenerate data/shade-gen when compact record shape, seed, method weights or public count changes.
• Keep compactShade(), normalizeShade() and bulk exports synchronized.
• Validate hydrateShadeManifest() whenever compact manifest fields change.
• Review API routes after adding high-level options such as explicit base, tokens or preserveBase.
• Run package tests, root validation, docs discovery, RSS, sitemap, PWA cache and search-index generation before publishing docs or data.

For workflow-level usage, see the Shade Gen User Guide.