Harmony Library User Guide

The Harmony Library is the public browser for deterministic color-theory harmonies generated by Auric Artisan. It lives at /library/harmony/ and reads /data/harmony-db/harmonies.json, a compact manifest generated from @auric-artisan/harmony-gen.

The page regenerates all 8,192 harmonies in the browser from that manifest when it loads and keeps only about a screenful of cards on the page at once. That keeps the library fast while making the full 8,192-harmony corpus searchable and exportable.

• Primary route: /library/harmony/.
• Main data: /data/harmony-db/harmonies.json.
• Current count: 8,192 deterministic harmonies.
• Method count: 23 canonical color-theory schemes.
• Families: complementary, polyadic, analogous, monochromatic and compound.
• Common uses: color theory study, brand exploration, UI palette selection, illustration palettes, accessibility review and design-token export.

Open Harmony Library. All seven tabs are available from the start: Library, Inspect, Theory, Accessibility, Stats, Export and Saved.

1. Scroll through the generated harmonies.
2. Click any harmony card to inspect it.
3. Use search and filters to explore ids, HEX values, schemes, hue, chroma and families.
4. Open Theory to compare scheme distribution and adherence.
5. Export a selected harmony or the filtered results in the format your project needs.

Press / to focus search. Use Open a random harmony when you want a quick jump into the corpus.

Above the tabs, What harmony is this? names the scheme that colors you already use form.

The Library tab uses the same card model as the other Auric libraries. Each card shows a harmony strip, harmony id, scheme name and quick actions.

• Harmony id: ids use the form har_ plus the base-36 harmony index, such as har_0 or har_abc.
• Swatches: click a swatch to copy that color's HEX value.
• Copy: copies all harmony HEX values.
• Inspect: opens full metrics and theory details.
• Save: pins the harmony locally and mirrors it to the Library workspace.

There are no pages: the grid scrolls through every result and keeps only about a screenful of cards on the page at once. Back to top returns to the start.

Harmony Library searches, filters and sorts the full 8,192-harmony corpus.

• Exact id: entering har_... or a numeric index jumps to that exact harmony if it is in range.
• HEX search: matches colors across every harmony.
• Scheme search: matches the method assigned to each harmony.
• Method filter: keeps only the harmonies of the chosen scheme, across all 8,192.

Inspect turns a harmony card into a full technical and theoretical report.

• Harmony strip: shows every color with role and generated OKLCH name.
• Summary: shows harmony id, global index, scheme, family, color count, base hue, average OKLCH lightness, average chroma, hue span, Delta E average, adherence, entropy, minimum pair contrast and maximum pair contrast.
• Theory card: explains the scheme, canonical angles, color roles and base HSL.
• Per-color cards: show role, HEX, RGB, HSL, OKLCH, CIE L*a*b*, WCAG vs white and WCAG vs black.
• Pair contrast list: shows WCAG contrast between every color pair.
• Quick export: provides copy, download, Coolors, save, share and design token actions.

Use the role labels to understand how each color participates in the scheme. Use pair contrast before treating two harmony colors as text and background.

The Theory panel is specific to the Harmony Library. It summarizes the filtered results by scheme, family, hue bucket, color count, adherence and chroma/lightness profile.

• Scheme distribution: counts visible harmonies by method.
• Family distribution: groups schemes into complementary, polyadic, analogous, monochromatic and compound.
• Dominant hue bucket: shows how visible harmonies cluster around the color wheel.
• Color count: separates 2-color through 7-color schemes.
• Adherence: groups harmonies by high, medium or low adherence to canonical angles.
• Stats: shows histograms for lightness, chroma, hue spread, minimum pair contrast, adherence and colors per harmony.

The Accessibility panel summarizes WCAG-style contrast between every pair in every visible harmony.

• Any AA pair: harmonies where at least one internal pair reaches 4.5:1.
• Any AAA pair: harmonies where at least one internal pair reaches 7:1.
• Pair-level breakdown: counts AAA pairs, AA pairs and pairs below AA across the filtered results.
• All-pairs AA candidates: visible harmonies where every internal pair passes 4.5:1.
• White/black checks: per-color cards show contrast against white and black for practical foreground decisions.

A harmony can be visually strong while still failing text contrast in some pairings. Confirm real font size, weight, state and background before shipping.

Harmony Library supports selected-harmony exports and bulk exports of the filtered results: every harmony that matches the current search and filters.

Save pins a harmony in the current browser and mirrors it into the Auric Artisan Library workspace with an image preview.

• Local saved key: aa.harmony.saved.
• Local saved limit: 500 harmony ids.
• Workspace domain: harmony.
• Workspace tool id: library-harmony.
• Share type: harmony.
• Shared payload: harmony id, method, family, base and uppercase HEX colors.

Share links resolve by harmony id against the current deterministic manifest. If manifest seed, count, methods or generation logic changes, old ids may point to different colors.

The manifest also includes color_count_by_method, families_by_method, canonical_angles and method_descriptions. Those fields drive labels, theory cards and advanced filters.

The panel at the top of the page turns the library around. Give it colors you already use and it tells you which of the 23 schemes they form, how closely, and which schemes it cannot tell apart from that one.

• Colors: it opens with a triad, #E4572E, #2EE457 and #572EE4. Click a swatch to pick, or type any CSS color: hex, rgb(), hsl(), lab(), oklch(), color() or a name. A field that is not a color yet is matched with its last valid color.
• Add a colour: adds the inverse of the first color, up to 12 colors. The × on a swatch removes it while more than two remain.
• Identify it: runs the match. The answer also updates as you edit.
• How it matches: it compares the hue offsets between your colors with the canonical angles of every scheme that has the same number of colors, trying each of your colors as the base. The order you enter them in does not change the answer.
• Fit: 1 minus the average hue error divided by 60°, never below 0. At 0.85 or more the panel names the scheme, from 0.65 it says “Close to” that scheme, and below 0.65 it says “Not one of the 23”.
• Schemes it cannot separate: some schemes share a hue pattern and differ only in lightness or saturation. shades, tints and neutral use one hue, warm_cool has the complementary pattern and triad_shifted keeps the triadic angles. When another scheme fits within 0.01, the panel lists it as indistinguishable by hue.
• Readouts: Family, Base colour (the color the best fit was anchored on), Worst pair and Best pair (the lowest and highest WCAG contrast between two of your colors, with AA shown at 4.5:1 or more), and Also considered, the next four schemes with their fit.
• Color count: the schemes have two to seven colors. For any other count the panel says no scheme uses that many colors.

The Harmony Library API runs the same matcher at POST /v1/harmony/identify.

• Use exact harmony ids when you need to return to a known result.
• Use Method filtering when you want a specific color-theory scheme.
• Use Family filtering for broader browsing, such as all polyadic or monochromatic schemes.
• Remember that hue, chroma, lightness, family and HEX filters refine the full collection, not just the cards on screen.
• Use adherence as a theory signal, not as the only quality score.
• Check pair contrast before using two harmony colors as text and background.
• Use JSON or CSS for implementation, SVG or PNG for reviews and ASE for design software.
• Rename exported design tokens before shipping them in a production product system.

For generator internals, see the Harmony Gen Developer Reference. For this browser's implementation, see the Harmony Library Developer Reference.