Let’s say you want to detect some grayscale colors:

A color is grayscale if the color’s red, green, blue (RGB) component values are exactly equal. A really common format for colors on the web is a 6 digit hexidecimal representation of the RGB component values: # + RRGGBB.

• #FFFFFF
• #000000
• #808080
• #FF0000
• #00FF00
• #0000FF

Knowing the above, detecting grayscale colors is simple:

function isGrayscale(color) {
  const { r, g, b } = parseColor(color);

  return r === g && r === b;
}

function parseColor(color) {
  const match = color.match(/#((?:[0-9A-F]{1,2}){3})/i);
  if (!match) {
    throw new Error('invalid color format');
  }
  const [r, g, b] = match[1]
    .repeat(2)
    .slice(-6)
    .match(/.{2}/g)
    .map(hex => parseInt(hex, 16));
  return {r, g, b};
}

Be aware that there are a boatload of valid formats for web colors. For production use you are better off using a library like d3-color to parse untrusted color values.

Anyway, the above code works great! I guess we are done. Hope you learned something! I should blog more often. See you next time!

Wait, what was that? You plugged some Bootstrap 4 gray colors into the function like isGrayscale('#adb5bd') and you got false? Well, I would indeed consider those Bootstrap grays to be “grayish” colors. However, those colors are not strictly grayscale colors according to the definition we agreed upon above. So yeah, it’s actually a good thing our function doesn’t match them. Closed as wontfix.

What? This blog post sucks? Okay, fine, there’s more we can do here. I’m no stranger to scope creep.

Classifying colors as “grayish”

A color is generally considered “grayish”, neutral, achromatic if all of its red, green, blue (RGB) component values are a close distance to each other. Makes sense: we know from earlier that a color is strictly grayscale if it has uniform RGB values. A distance of zero is about as close as you can get.

Let’s define our test cases. We can use those pesky Bootstrap 4 gray colors as colors we want to positively match.

• gray-100: #f8f9fa
• gray-200: #e9ecef
• gray-300: #dee2e6
• gray-400: #ced4da
• gray-500: #adb5bd
• gray-600: #6c757d
• gray-700: #495057
• gray-800: #343a40
• gray-900: #212529

As a sanity check let’s use ColorBrewer 2 as colors we want to negatively match.

Let’s visualize the RGB values of our test cases and check if we see the pattern we expect.

Okay, so we can clearly see the pattern we expect. The colors we want to match have equidistant RGB components. The ColorBrewer colors are off doing their own thing because they are clearly not gray colors.

If we want to classify these colors in code: we need a way to measure the degree to which the RGB components are close to each other. The range of the RGB components should measure this nicely.

const RANGE_LIMIT = 17;

function isGray(color) {
  const { r, g, b } = parseColor(color);
  const rgb = [r, g, b];
  return Math.max(...rgb) - Math.min(...rgb) <= RANGE_LIMIT;
}

This matches the original desired Bootstrap colors:

Similar “grayish” colors will be matched as well:

Great! Looks good to me so far. Now, how can we exhaustively prove that this function matches only the colors we want? The best way to spot check our function is probably to visualize what it considers to be “grayish”.

Checking our work

RGB is a nice and simple color model that is easy for machines to deal with. However, for our purposes here it would be nice to use a human-friendly color model. I will choose the hue, saturation, value (HSV) color model to make a simple 2D plot of the colors matched by our function.

HSV has some useful geometry for detecting and visualizing grayish colors. The HSV color model can be represented as a cylinder where the central vertical axis comprises neutral, achromatic, or gray colors. Those colors range, from top to bottom, white at value 1 and black at value 0.

By HSV_color_solid_cylinder.png: SharkDderivative work: SharkD  Talk - HSV_color_solid_cylinder.png, CC BY-SA 3.0, wiki

I’m not smart enough to do math in 3D: so let’s just chart 2D slices of this cylinder at different hues and see how far we get. We are mostly concerned with the interaction between saturation and value right now anyway. Let’s fix the hue to 210°. since all those Bootstrap grays tend to hover around that hue.

Great! Not perfect, but it’s definitely clear to me that we are on the right track.

Let’s check another hue to see what our function matches there. Let’s check the 120° hue.

Uhoh. Yeah, this isn’t working at all. Most all of these matched colors look downright green to me on all my devices. At best, it seems to be matching greens that look like olive drab.

If you are not familiar with color spaces: you might be wondering how #f0f7ff and #f0fff0 can have the same saturation (6) and value (100) yet #f0fff0 is disproportionately offensive. Due to the way color vision works, we are naturally more sensitive to colors in the greenish-yellow area of the color spectrum. So we need to use a perceptually uniform color model that accounts for this.

Perceiving colors in code

Let’s tighten up our terminology in the hopes of finding a good color model for our problem. Classifying colors as “grayish” can be more accurately stated as classifying:

• neutral colors
• colors with low colorfulness
• colors with low saturation
• achromatic colors, colors with a low chroma value

If we are looking for achromatic colors, we have the CIELCh_ab perceptual color model at our disposal. This is a cylindrical representation of the CIELAB color space with a channel for Lightness, Chroma, and hue. The chroma channel is what we will use to determine if a color is achromatic enough to be matched. #6c757d from our bootstrap colors has the highest chroma value at 6.05. Let’s use that as our threshold.

import { lch } from 'd3-color';

const CHROMA_THRESHOLD = 6.05;

function isGray(color) {
  let chroma = lch(color).c;
  return isNaN(chroma) || chroma <= CHROMA_THRESHOLD;
}

Let’s chart it at the 210° hue:

Let’s chart it at the 120° hue:

For completeness let’s try Let’s chart it at the 0° hue:

Let’s sample the edge case colors:

We are definitely getting somewhere. At this point I’m beginning to doubt my monitor calibration/eyes. Regardless, I’m gonna go ahead and judge that most people would struggle to classify the above colors as “gray”. If I asked people to name those colors I’m guessing they would say things like “pale blue”, “olive drab”, “dark blue”.

Here’s an example of me manually tweaking these colors in an LCh color picker until I personally would call them “gray”.

That is the best I could do in 10 minutes or so. I’m hesitant to tweak further as there are so many equipment and biological factors that could cause me to waste a ton of time with diminising returns. The limitations of human vision could certainly trip me up.

Anyway, the above exercise of manually finding the chroma threshold for those example colors was useful. Let’s encode my common sense judgement above into an algorithm.

Coding common sense

When determining a chroma threshold for our algorithm, we should consider these findings from above:

• Blue colors should be given lots of leeway. Blues with a low chroma look like “cool grays” to me.
• Orange colors should be given lots of leeway. Orange is a gateway to brown. Oranges with low chroma look like “warm grays” to me.
• Red colors should be judged somewhere in the middle.
• Green colors should be scrutinized closely.

Let’s slice up our 3D problem into 2D projections and apply some shader functions to our classifier curves to approximate our desired result.

function _clamp(x, min, max) {
  if (x < min) {
    x = min
  } else if (x > max) {
    x = max
  }
  return x
}

function _smoothstep(a, b, x) {
  const t = _clamp((x - a) / (b - a), 0.0, 1.0);
  return t * t * (3.0 - 2.0 * t);
}

const hueToleranceStopsV1 = [
  [0, 3.1], // red
  [20, 3.1], // orange
  [61.8, 8], // orange
  [66, 7.49], // orange
  [75, 6.8], // orange
  [100, 2], // yellow-green
  [180, 2], // green
  [240, 5.4], // blue
  [262, 14], // blue
  [263, 14], // blue
  [290, 6.5],
  [310, 3.1], // red
  [360, 3.1],
];

function _buildCurve(stops) {
  return function (value) {
    let a, b, from, to;
    for (const [x, y] of stops) {
      if (value >= x) {
        a = x;
        from = y;
      }
      if (value <= x) {
        b = x;
        to = y;
        break;
      }
    }
    if (a === b) {
      return to;
    }
    return _smoothstep(a, b, value) * (to - from) + from;
  }
}

const hueCurveLCh = _buildCurve(hueToleranceStopsV1);

function isGray(color) {
  const {l: lightness, c: chroma, h: hue} = lch(color);
  // black and white
  if ([0, 100].includes(lightness)) {
    return true;
  }
  // grayscale
  if (chroma === 0) {
    return true;
  }
  return chroma <= hueCurveLCh(hue)
}

Below is a visualization of hueCurveLCh:

Let’s dump all the edge case values this function matches. The following table shows the most chromatic colors matched for a given hue and lightness. These colors sit at the threshold of what this function considers “gray”.

Looking pretty good to me!

Color palettes classified as gray

Bootstrap grays ✅

• gray-100: #f8f9fa
• gray-200: #e9ecef
• gray-300: #dee2e6
• gray-400: #ced4da
• gray-500: #adb5bd
• gray-600: #6c757d
• gray-700: #495057
• gray-800: #343a40
• gray-900: #212529

PANTONE cool grays ✅

• 1C: #d9d9d6
• 2C: #d0d0ce
• 3C: #c8c9c7
• 4C: #bbbcbc
• 5C: #b1b3b3
• 6C: #a7a8a9
• 7C: #97999b
• 8C: #888b8d
• 9C: #75787b
• 10C: #63666a
• 11C: #53565a

PANTONE warm grays ✅

• 1C: #d7d2cb
• 2C: #cbc4bc
• 3C: #bfb8af
• 4C: #b6ada5
• 5C: #aca39a
• 6C: #a59c94
• 7C: #968c83
• 8C: #8c8279
• 9C: #83786f
• 10C: #796e65
• 11C: #6e6259

CSS Colors ✅

• black #000000
• silver #c0c0c0
• gray #808080
• white #ffffff
• dimgray #696969
• dimgrey #696969
• darkgray #a9a9a9
• darkgrey #a9a9a9
• grey #808080
• lightgray #d3d3d3
• lightgrey #d3d3d3
• aliceblue #f0f8ff
• gainsboro #dcdcdc
• ghostwhite #f8f8ff
• snow #fffafa
• whitesmoke #f5f5f5
• seashell #fff5ee
• linen #faf0e6

(I slightly disagree with aliceblue but gonna leave it for now)

Color palettes not classified as gray

A lot of these are blues with chroma values way above what I’m willing to match with the current implementation of the function. I could treat blues as special, but I’m gonna leave it be for now.

CSS “Slate Gray” ❌

I would like to match these guys eventually.

• lightslategray: #778899
• lightslategrey: #778899
• slategray: #708090
• slategrey: #708090

Light CSS Colors ❌

• azure #f0ffff
• ivory #fffff0
• floralwhite #fffaf0
• honeydew #f0fff0
• bisque #ffe4c4
• blanchedalmond #ffebcd
• burlywood #deb887
• cornsilk #fff8dc
• beige #f5f5dc
• antiquewhite #faebd7

Tailwind CSS “grays” ❌

Matching these made my blue hue edge cases kinda bogus looking. I tend to agree with my function above. These look like blue colors to me: not gray.

• 100: #F7FAFC ✅
• 200: #EDF2F7 ✅
• 300: #E2E8F0 ✅
• 400: #CBD5E0 ❌
• 500: #A0AEC0 ❌
• 600: #718096 ❌
• 700: #4A5568 ❌
• 800: #2D3748 ❌
• 900: #1A202C ❌

If you wanted to match these guys you would need to lax your tolerances for blue hues.

const hueToleranceStopsV2 = [
  [0, 3.1], // red
  [20, 3.1], // orange
  [61.8, 8], // orange
  [66, 7.49], // orange
  [75, 6.8], // orange
  [100, 2], // yellow-green
  [180, 2], // green
  [240, 5.4], // blue
  [262, 14], // blue
  [263, 14], // blue
  [290, 6.5],
  [310, 3.1], // red
  [360, 3.1],
];

Which looks like a much different curve:

What is this useful for?

You could use this as a post-processing step to classify things as “gray”.

roots/palette-webpack-plugin uses a simplified version of this technique to automatically sort colors in a color palette picker.

Further Reading

• David Briggs. “Dimensions of Colour”
• Alexei Boronine. “Color Spaces for Human Beings”
• Charlie Loyd. “On Rainbows”
• Perceptual Science Group @ MIT
  • Adelson, E.H. “Checkershadow Illusion”
  • Adelson, E.H. Lightness Perception and Lightness Illusions. (2000).