Harmony Gen Developer Reference

tool/harmony-gen/package.json defines @auric-artisan/harmony-gen, an ESM package requiring Node 20 or newer. It is dependency-free at runtime and exposes subpath exports matching the sibling generation packages.

src/api/api.js is the stable high-level API used by application code and API handlers.

src/index.js also re-exports lower-level modules, so consumers can import HarmonyDatasetGenerator, exporters, metrics and visualization helpers directly.

Harmony objects are produced by generateOneHarmony(), HarmonyDatasetGenerator.generateOne() and the lower-level createHarmony() helper.

{
  harmony_id: "har_...",
  method: "triadic",
  family: "polyadic",
  base: {
    hue: 210,
    saturation: 0.7,
    lightness: 0.5,
    hex: "#267fd9"
  },
  colors: [
    {
      role: "base",
      hex: "#267fd9",
      rgb: [38, 127, 217],
      hsl: [210, 0.7, 0.5],
      oklch: [0.59, 0.15, 253.2],
      lab: [...]
    }
  ],
  metadata: {
    method: "triadic",
    family: "polyadic",
    color_count: 3,
    canonical_angles: [120, 240],
    description: "Three hues spaced 120 deg apart.",
    global_index: 42,
    seed: 137
  }
}

roleForIndex() provides user-facing roles such as base, complement, triad-1, accent, shade-2 or tint-4. familyForMethod() maps method ids into broad families.

src/harmony_algorithms/registry.js is the canonical source of method ids, functions, color counts, families, descriptions and canonical angle arrays.

Current registry methods:

complementary
split_complementary
triadic
tetradic
square
analogous_3
analogous_5
analogous_7
monochromatic_3
monochromatic_5
monochromatic_7
double_complementary
accented_analogous
hexadic
neutral
compound
shades
tints
warm_cool
triad_shifted
pentadic
golden_ratio
fibonacci_hue

Adding a method should start in the registry because the API, dataset engine, Harmony Library filters, classification, manifest generation and docs all depend on registry metadata.

Algorithm functions accept (h, s, l) and return arrays of RGB triples. The registry wraps them into harmony objects through the dataset and API layers.

src/core/color-spaces.js is a pure function conversion module using D65 reference white for XYZ and Lab. It supports:

• RGB, RGBA and HEX.
• HSL, HSV and HSB.
• CMYK.
• CIE XYZ, CIELAB and CIELCH.
• OKLab and OKLCH.
• HCL, YUV and YCbCr.

convert(value, from, to) routes through RGB. rgbToAll() returns every supported representation for a single RGB input. Harmony color records currently store HEX, RGB, HSL, OKLCH and Lab.

src/color_wheel/geometry.js provides angular helpers used in filtering, summaries and scoring:

• normalizeHue(), hueDistance() and hueDelta().
• maxHueGap() and hueSpread().
• vectorMeanHue() and hueSymmetry().
• hueBucket() for red, orange, yellow, green, cyan, blue, purple and pink buckets.

src/color_wheel/wheel.js exposes RGB and RYB wheel slots, plus RYB-to-RGB and RGB-to-RYB hue mapping for traditional artist-wheel interpretation.

src/color_science/metrics.js includes perceptual, accessibility and harmony-specific metrics.

• deltaE76(), deltaE94(), deltaE2000() and deltaERgb().
• relativeLuminance(), contrastRatio() and contrastMatrix().
• paletteAvgDeltaE() and paletteMinDeltaE().
• paletteEntropy(), colorDiversityIndex() and perceptualUniformity().
• chromaStats(), luminanceStats() and hueDistribution().
• harmonyAdherence(), which compares observed hue rotations to canonical angles.

evaluateHarmony() combines those into one JSON-compatible report, except that the contrast matrix rows are Float64Array values before dataset generation rounds them into plain arrays.

src/accessibility/accessibility.js is WCAG 2.x focused. It defines thresholds for AA normal, AA large, AAA normal, AAA large and UI components.

• pairAccessibility() emits every pair and pass/fail booleans.
• bestInkRecommendations() chooses white or near-black text for each color.
• accessibilityScore() summarizes AA and AAA pair share into a 0-to-1 score.
• harmonyAccessibilityReport() returns pairs, ink recommendations, score and summary counts.

This module does not perform APCA or color-vision-deficiency simulation. Use the accessibility generation package for deeper accessibility standards.

src/dataset_engine/deterministic.js defines the deterministic stream. Defaults are:

• seed: 137.
• count: 8192.
• batchSize: 1024.
• batchSeedStride: 2654435761.

baseForIndex(index) uses xorshift32, batch seed stride and three RNG advances per local index to derive hue, saturation and lightness. methodForIndex() cycles methods in registry order.

buildManifest() creates the compact manifest consumed by the Harmony Library. The checked-in manifest is data/harmony-db/harmonies.json.

HarmonyDatasetGenerator accepts seed, count, batchSize, includeMetrics and methods. It exposes generateOne(index), generateAll() and generateDataset().

StreamingHarmonyWriter writes JSON, NDJSON and CSV. It attempts to use Node filesystem streams, and falls back to an in-memory buffer when filesystem APIs are unavailable.

The writer accepts a compress option but does not currently pipe compression. Treat that flag as reserved until gzip or another compression path is implemented.

src/export/exporters.js includes single-harmony and bulk exporters.

src/visualization/visualization.js wraps strip SVG generation and adds renderHueWheelSvg(), a self-contained hue wheel diagram with swatch dots.

src/research/research.js provides dataset-level analytics for generated harmony arrays:

• bucketByMethod(), bucketByFamily(), bucketByDominantHue() and bucketByColorCount().
• summarise() for totals, method distribution, family distribution, hue buckets, average lightness, chroma and color count.
• histogram() for scalar chart bins.
• topAccessible() for sorting harmonies by accessibility score.
• fullAnalysis() for re-running metrics across a dataset.

library/harmony/harmony-library.js mirrors key package logic in the browser. It loads /data/harmony-db/harmonies.json, regenerates harmonies on demand, caches visible items, filters by hue, chroma, lightness, method and family, and supports exact id search.

The viewer provides Library, Inspect, Theory, Accessibility, Stats, Export and Saved panels. It supports per-harmony export, bulk export of the filtered results, share links, token dialog integration and mirrorSave() to the Library workspace with image previews.

Because runtime generation is duplicated in the browser viewer, changes to registry methods, deterministic seeding or harmony object shape must be updated in both the package and the viewer.

• api/lib/handlers/harmony.js imports generateHarmony and classifyHarmonyAPI.
• api/lib/handlers/meta.js imports getAvailableMethods for method discovery.
• api/lib/handlers/jobs.js imports generateHarmonyDataset for background harmony jobs.
• api/lib/handlers/export.js imports the exporter module for /v1/harmony/export.
• api/lib/handlers/graphql.js exposes the harmony resolver.

Current adapter caveats: /v1/harmony/export allows hex, css, scss, tailwind, json, ase, svg and csv. The direct package also lists json-compact. The API JSON branch stringifies toJsonFull(), which already returns a JSON string, and the ASE branch returns bytes with an application/json content type. Review those branches before relying on them for external binary export contracts.

The package currently defines examples and generation scripts but no test script. Practical validation commands are:

cd tool/harmony-gen
node -e "import('./src/index.js').then(m => console.log(m.getAvailableMethods().length))"
npm run example:basic
npm run example:export
node scripts/generate-dataset.js 32 ndjson ./output-smoke

Root API and site validation should also run after package, data or docs changes:

npm test
node scripts/generate-discovery.mjs
node scripts/generate-pwa-cache-manifest.mjs
node search/client/build-index.js

• Update HARMONY_REGISTRY, compact manifest metadata, docs and UI filters when adding or renaming a method.
• Keep package algorithm logic and library/harmony/harmony-library.js browser regeneration logic synchronized.
• Update color_count_by_method, families_by_method, canonical_angles and descriptions when method behavior changes.
• Add or update validation coverage before changing Delta E, contrast, adherence or accessibility scoring.
• Review API export content types when changing binary exporters.
• Implement and test real compression before documenting compress as active writer behavior.
• Regenerate discovery files whenever documentation registry entries change.

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