Harmony Gen User Guide

Harmony Gen is the color-theory generation package in tool/harmony-gen. It creates structured palettes from base HSL values using classic, extended, shifted and exotic harmony methods. Each output includes roles, HEX, RGB, HSL, OKLCH, Lab and metadata.

It is the engine behind the public Harmony Library. The library loads /data/harmony-db/harmonies.json, a compact manifest describing 8,192 deterministic harmonies, then regenerates visible harmonies in the browser from seed and index.

• Package: @auric-artisan/harmony-gen.
• Runtime: ESM Node package requiring Node 20 or newer.
• Main entry: tool/harmony-gen/src/index.js.
• Primary API: generateHarmony(), generateHarmonyDataset(), evaluateHarmony(), classifyHarmony().
• Library data: data/harmony-db/harmonies.json.

Run examples from the package directory:

cd tool/harmony-gen
npm install
npm run example:basic
npm run example:theory
npm run example:export
npm run example:research

The package currently has examples and generation scripts but no npm test script. Use package smoke commands and root site validation when changing it.

The shortest workflow is generateHarmony(method, hue, saturation, lightness). Hue is 0 to 360. Saturation and lightness are 0 to 1.

import { generateHarmony, getAvailableMethods } from "./src/index.js";

console.log(getAvailableMethods());

const harmony = generateHarmony("triadic", 210, 0.7, 0.5);

console.log(harmony.harmony_id);
console.log(harmony.method);
console.log(harmony.colors.map((color) => color.hex));

Harmony objects use palette-style fields:

• harmony_id: generated identifier.
• method: selected scheme, such as triadic.
• family: broad grouping, such as polyadic.
• base: source hue, saturation, lightness and base HEX.
• colors: role, HEX, RGB, HSL, OKLCH and Lab for each generated color.
• metadata: method, color count, angles, description, index or seed details.

The registry contains 23 methods grouped into families. Method names use snake case.

Use getColorTheoryDescription(method) when you need a one-line explanation for labels, tooltips or generated reports.

The first color is always base. Other role names depend on the method:

• complement for complementary pairs.
• split-low and split-high for split complementary schemes.
• triad-1 and triad-2 for triadic schemes.
• ally, complement and complement-ally for tetradic schemes.
• analogous-1 and onward for analogous variants.
• shade-* and tint-* for monochromatic tonal systems.
• warm-shift, cool-shift and accent for compound systems.

These roles are exported into CSS, SCSS and Tailwind keys, so they are useful names for design tokens and UI handoff.

Use evaluateHarmony(harmony) from the public API, or call lower-level metrics from src/color_science/metrics.js. The report includes:

Accessibility helpers are in src/accessibility/accessibility.js. They score color pairs against WCAG 2.x contrast thresholds and recommend readable text colors.

import {
  harmonyAccessibilityReport,
  accessibilityScore
} from "./src/index.js";

const rgb = harmony.colors.map((color) => color.rgb);
const report = harmonyAccessibilityReport(rgb);

console.log(accessibilityScore(rgb));
console.log(report.summary.AA_normal_pass);
console.log(report.inks.map((ink) => ink.best_ink));

The report includes every pair, AA and AAA booleans for normal and large text, UI component contrast, best white or black ink recommendations and summary counts.

classifyHarmony() compares an arbitrary RGB palette against registry methods with the same color count. It scores hue rotation distance against canonical angles.

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

const result = classifyHarmony([
  [255, 0, 0],
  [0, 255, 0],
  [0, 0, 255]
]);

console.log(result.method);
console.log(result.confidence);
console.log(result.family);

Classification is a lightweight hue-geometry estimate. It is useful for sorting and labeling, but palettes with unusual lightness or chroma intent may still need human review.

Text and binary exporters live in src/export/exporters.js. They return strings or a Uint8Array for ASE.

import {
  toHexList,
  toCss,
  toScss,
  toTailwind,
  toJsonFull,
  toCsvRow,
  toAse,
  toSvg
} from "./src/index.js";

console.log(toHexList(harmony));
console.log(toCss(harmony));
console.log(toTailwind(harmony));

• HEX: newline-separated uppercase HEX colors.
• CSS: :root custom properties using harmony id and role names.
• SCSS: role-based Sass variables.
• Tailwind: JSON or module fragment color map.
• JSON: compact or full harmony payloads.
• CSV: harmony id, method, family, count, base and colors.
• ASE: Adobe Swatch Exchange bytes.
• SVG: strip preview with labels.

Browser-side Harmony Library export also includes PNG strip rendering, Coolors links, share links and design-token dialog integration.

generateHarmonyDataset() creates an in-memory array by default. For file output, use HarmonyDatasetGenerator.generateDataset() or the CLI script.

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

const generator = new HarmonyDatasetGenerator({
  count: 8192,
  seed: 137,
  batchSize: 1024,
  includeMetrics: true
});

const result = await generator.generateDataset({
  outputPath: "./output",
  format: "ndjson",
  onProgress: (p) => console.log(`${p.generated}/${p.total}`)
});

From the package directory:

node scripts/generate-dataset.js
node scripts/generate-dataset.js 8192 ndjson ./output
node scripts/generate-dataset.js 8192 csv ./output

The public Harmony Library does not use the expanded output. It uses the compact manifest at data/harmony-db/harmonies.json, with schema, source, count, seed, batch_size, methods, color_count_by_method, families_by_method and canonical_angles.

Harmony Gen is imported by the Auric Artisan API layer.

• POST /v1/harmony/generate: generate a harmony from method, hue, saturation and lightness.
• POST /v1/harmony/classify: classify an array of colors into the closest harmony scheme.
• POST /v1/harmony/export: export a generated harmony as HEX, CSS, SCSS, Tailwind, JSON, ASE, SVG or CSV.
• GET /v1/methods/harmony: list available methods.
• POST /v1/jobs/harmony-dataset: run a bounded background dataset job.
• POST /v1/graphql: use the harmony resolver.

curl -X POST "$BASE/v1/harmony/generate" \
  -H "content-type: application/json" \
  -d '{"method":"triadic","hue":210,"saturation":0.7,"lightness":0.5}'

• Use complementary and split complementary schemes for deliberate contrast, not quiet UI systems.
• Use analogous and monochromatic schemes when you need coherent tonal systems.
• Use OKLCH and Lab values when comparing perceptual distance or building accessible ramps.
• Check pair contrast before using a harmony directly as foreground and background colors.
• Use deterministic seed and index flows for datasets that must be reproducible.
• Use the compact manifest for browser libraries and expanded JSON or NDJSON for offline analysis.
• Review generated harmonies by eye when using exotic methods for brand-critical decisions.
• Run examples, API contract tests and site validation after changing registry methods or output schemas.

For implementation details, see the Harmony Gen Developer Reference.