The harmony score requires at least 2 colors. A single color shows
— and the message “add more colors to score harmony”. An empty palette hides the panel entirely.Score and label
The score is displayed asnn/100 next to a human-readable label. The label is color-coded:
| Score range | Color |
|---|---|
| 80–100 | Green |
| 55–79 | Yellow |
| 35–54 | Orange |
| 0–34 | Red |
How the label is assigned
If a named color relationship is detected (see below), the label is the relationship name:complementary, analogous, triadic, tetradic, split‑complementary, or monochromatic.
If no named relationship is detected, the label is assigned by score and lightness range:
| Condition | Label |
|---|---|
| Lightness range > 70 | high contrast |
| Score ≥ 80 | balanced |
| Score ≥ 60 | varied |
| Score ≥ 40 | inconsistent |
| Score < 40 | discordant |
Three metrics
Expanding the panel reveals three individual metrics shown as block bar graphs:Hue quality — 45% of score
Hue quality — 45% of score
Measures how well the hues in your palette fit a recognized harmony template. The algorithm (
Low score: hues are scattered without a recognizable pattern.
bestFitHueScore in src/helpers/colorTheory.ts) tries every possible number of evenly-spaced hue positions from 1 to N (where N is the number of colors) and every possible rotation. It scores each color by how close it falls to the nearest template position, then takes the best-fitting combination.This approach rewards both tight hue clusters (monochromatic, analogous) and evenly-distributed hues (complementary, triadic, tetradic). A palette where colors cluster around two complementary hues can score just as well as a palette where all colors share a single hue.High score: colors sit on predictable hue positions — tight cluster or even spacing.Low score: hues are scattered without a recognizable pattern.
Saturation consistency — 25% of score
Saturation consistency — 25% of score
Measures how similar the saturation values are across all colors. Calculated as
Low score: saturation varies widely — some vivid, some nearly gray.
max(0, 100 - stdDev * 2), where stdDev is the standard deviation of HSL saturation values.A palette where all colors have roughly the same saturation feels more cohesive than one that mixes highly saturated colors with nearly gray ones.High score: saturation values are close together (low standard deviation).Low score: saturation varies widely — some vivid, some nearly gray.
Lightness range — 30% of score
Lightness range — 30% of score
Measures how wide the spread of lightness values is across the palette. Calculated as
Low score: all colors clustered at a similar lightness — often means the palette lacks contrast.
min(100, (max_L - min_L) / 50 * 100). A 50-point spread (e.g., lightness 20 to 70) scores 100.A palette with both light and dark colors is more versatile — it can be used for backgrounds, text, accents, and borders without needing to add extra neutrals.High score: wide spread from dark to light (at least 50 points of HSL lightness).Low score: all colors clustered at a similar lightness — often means the palette lacks contrast.
Weighted formula
Relationship detection
The harmony score also runsdetectRelationship to check whether the hues match a known color theory template. Detection uses a ±22° tolerance for all angle-based comparisons.
| Relationship | Detection rule |
|---|---|
| Monochromatic | All pairwise hue gaps < 20° |
| Analogous | All pairwise hue gaps < 60° |
| Complementary | 2 colors, hue gap ≈ 180° |
| Triadic | 3 colors, all consecutive hue gaps ≈ 120° |
| Split-complementary | 3 colors, one small gap (< 110°), two large equal gaps (> 120°, within 40° of each other) |
| Tetradic | 4 colors, all consecutive hue gaps ≈ 90° |
null for 5+ color palettes unless they happen to satisfy the monochromatic or analogous rules.
Edge cases
- 1 color: score is 0, label is
—, no metrics are shown. Expand the panel and you’ll see “add more colors to score harmony”. - 2 colors: all three metrics are calculated, but only complementary can be detected as a named relationship. Monochromatic and analogous are still possible if hues are close enough.
- Very desaturated colors: near-gray colors have a hue value of 0 in HSL regardless of their actual tint. This can inflate or deflate hue quality scores for palettes that mix chromatic and achromatic colors.
Using the score to improve your palette
Check which metric is lowest
Expand the panel and compare the three bar graphs. If hue quality is low, your hues are scattered — try using the color relationships generator to build from a template. If saturation consistency is low, edit individual colors to align their saturation. If lightness range is low, push some colors lighter and others darker.
Aim for a named relationship
The +15 bonus for a named relationship reflects the fact that palettes organized around color theory principles tend to feel more deliberate. Use the color relationships guide to generate palettes with built-in structure.
Balance harmony with contrast
A high harmony score does not guarantee accessibility. A monochromatic palette can score very high on hue quality and saturation consistency but fail contrast requirements entirely. Use the contrast checker alongside the harmony score.
Keyboard shortcut
| Shortcut | Action |
|---|---|
| Y | Toggle harmony score panel open / closed |
Related
Color relationships
Generate palettes based on complementary, triadic, and other color theory schemes.
Contrast checker
Check WCAG contrast ratios alongside your harmony score.
Color editing
Fine-tune individual colors to improve specific metrics.