Harmony Library Developer Reference

Harmony Library is a static page plus an ESM browser runtime. The page shell declares SEO, structured data, application containers, filters, tabs and shared Auric Artisan UI chrome. The runtime fetches a compact deterministic manifest, regenerates all harmonies on load, enriches them with color science data and powers Inspect, Theory, Accessibility, Stats, Export and Saved.

• Page shell: library/harmony/index.html.
• Runtime: library/harmony/harmony-library.js.
• Data URL: /data/harmony-db/harmonies.json.
• Saved key: aa.harmony.saved.
• Identify script: library/harmony/harmony-identify.js.
• Share type: harmony.
• Workspace domain: harmony.

• Canonical: https://auricartisan.com/library/harmony/.
• Preload: /data/harmony-db/harmonies.json.
• Structured data: ImageObject, CollectionPage and BreadcrumbList.
• Shared styles: main, unified, dark-mode and harmony-library CSS.
• Route script: /js/generated-inline/f89b771545ccd909c69c.js.
• Chrome: header, time, announcement, custom cursor, scroll rail, loader, eye-rest panel, footer, idle layer and generated inline scripts.
• Application panels: Library, Inspect, Theory, Accessibility, Stats, Export and Saved.

loadData() fetches DATA_URL with cache: "force-cache". Expanded arrays are rejected because this route is designed as a compact virtual viewer.

{
  "schema": "aa.harmony-db.compact.v1",
  "format": "deterministic-harmony-gen-manifest",
  "source": "@auric-artisan/harmony-gen",
  "count": 8192,
  "seed": 137,
  "batch_size": 1024,
  "batch_seed_stride": 2654435761,
  "methods": ["complementary", "split_complementary", "triadic"],
  "color_count_by_method": {},
  "families_by_method": {},
  "canonical_angles": {},
  "method_descriptions": {}
}

Production data must include all 23 methods plus family, color count, canonical angle and description maps. Those maps drive UI labels, filters and theory details.

• nextXor() advances a xorshift integer state.
• batchSeed(batch) computes seed + batch * batch_seed_stride.
• harmonyId(index) returns har_ plus the base-36 index.
• indexFromHarmonyId(id) accepts har_... ids or numeric strings.
• methodForIndex(index) assigns methods by index % methods.length.
• baseSeedForIndex(index) derives base hue, saturation, lightness and method.
• SCHEMES contains the browser-side implementations for all harmony methods.
• enrichHarmony() computes roles, HEX, RGB, HSL, Lab, OKLCH, family, base data, Delta E, entropy, contrast matrix and adherence score.

loadData() materializes all 8,192 harmonies into state.all; the lookup cache state.harmonyCache keeps up to 1,200 of them for id lookups.

{
  dataset: null,
  count: 0,
  page: 0,
  all: [],
  filteredCount: 0,
  visibleHarmonies: [],
  activeHarmony: null,
  exactSearchIndex: null,
  harmonyCache: new Map(),
  panelsRendered: {
    theory: false,
    stats: false,
    accessibility: false,
    export: false,
    saved: false
  },
  progress: {
    browse: false,
    inspect: false,
    theory: false,
    accessibility: false,
    export: false
  }
}

1. Resolve DOM ids into els.
2. Attach event listeners for search, filters, cards, exports, tabs and the back-to-top button.
3. Call loadData().
4. Fetch and normalize the deterministic manifest.
5. Populate method filter options.
6. Materialize every harmony into state.all and render the virtual grid.
7. Render saved panel state and register the harmony share handler.

• hslToRgb() and rgbToHsl() bridge scheme geometry and rendered color data.
• rgbToLab() computes CIE Lab values for inspection and Delta E average.
• rgbToOklab() and rgbToOklch() compute perceptual lightness, chroma and hue.
• contrastRatio() computes WCAG-style contrast between colors.
• dominantHue(), hueSpread(), avgLightness() and avgChroma() drive filters and stats.
• deltaEAvg(), paletteEntropy() and adherenceScore() drive Inspect, Theory and Stats panels.
• roleForIndex() and roleLabel() convert scheme position into human-facing labels.

Search is debounced at 90 ms. Filter and sort changes call applyFilters(), which calls renderPage().

• harmonyCardInner() builds cards with swatches, harmony id, scheme badge, Inspect, Copy and Save controls.
• Clicking a swatch copies that swatch HEX.
• Clicking Copy copies all harmony HEX values.
• Clicking Save toggles local saved state and workspace mirroring.
• Clicking the card body or Inspect calls openInspect(harmony).
• Keyboard Enter or Space on a focused card opens Inspect.
• Pressing / focuses search unless an input or textarea is already active.

• stripHarmony() returns id, method, family, base, colors and metadata.
• buildAse() creates an Adobe Swatch Exchange binary using RGB records.
• buildSvg() creates a 720 x 240 SVG strip with HEX and role labels.
• buildPng() creates a 960 x 360 canvas strip and downloads a PNG.
• Selected CSS export writes a :root block with --{harmony_id}-{role} variables.
• Bulk CSV writes harmony_id, method, family, color_count, base_hex and colors.
• Bulk Tailwind export writes a module.exports config fragment.

{
  "harmony_id": "har_abc",
  "method": "triadic",
  "family": "polyadic",
  "base": {
    "hue": 210,
    "saturation": 0.7,
    "lightness": 0.55,
    "hex": "#3388cc"
  },
  "colors": [
    {
      "role": "base",
      "hex": "#3388cc",
      "rgb": [51, 136, 204],
      "hsl": [205, 0.6, 0.5],
      "oklch": [0.62, 0.13, 245.1],
      "lab": [55.2, -4.1, -42.5]
    }
  ],
  "metadata": {
    "method": "triadic",
    "family": "polyadic",
    "color_count": 3,
    "canonical_angles": [120, 240],
    "adherence": 0.98
  }
}

• getSaved() reads aa.harmony.saved.
• setSaved() stores up to 500 harmony ids.
• toggleSaved(id) updates local saved state and mirrors workspace changes.
• mirrorSave() stores domain harmony, asset type palette, tool id library-harmony, description, colors and payload.
• shareHarmonyLink() calls shareViaDialog() with type harmony.
• registerShareHandler("harmony", hydrateFromSharedHarmony) opens a matching deterministic harmony from a shared id.
• openTokensDialog() uses the slugged method as default prefix and tokensFromSwatchList().

Shared payloads include id, method, family, base and uppercase colors. Hydration resolves by id against the current deterministic manifest.

• The app container uses role="application" and the search input is labelled aria-label="Search harmonies".
• Tabs use role="tablist", role="tab", aria-selected and aria-controls.
• Panels use role="tabpanel" with matching labels.
• The grid uses aria-live="polite" so result changes can be announced.
• The toast uses role="status" and aria-live="polite".
• Cards support keyboard activation with Enter and Space.
• All seven tabs are always available; there is no Simple or Advanced mode to hide them.
• The result counter hlib-page-info uses role="status" and aria-live="polite".

• Keep manifest count, hero count, page metadata and docs aligned.
• Do not change seed, batch_size, batch_seed_stride or method order without treating harmony ids as migrated data.
• Keep package algorithm logic and browser SCHEMES implementations synchronized.
• Update docs when hue buckets, chroma thresholds, lightness thresholds, families or sort modes change.
• Validate clipboard, ASE, SVG, PNG and URL object cleanup when changing exports.
• Check localStorage migration before changing SAVED_KEY or saved id format.
• After documentation changes, regenerate documentation discovery, feeds, sitemaps, PWA cache and search index.

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

For user-facing workflow details, see the Harmony Library User Guide. For generator internals, see the Harmony Gen Developer Reference.