Colors: add new function chooseHigherContrast

src/css-colors/CHANGELOG.md

@@ -1,6 +1,7 @@
 # Unreleased
 
 - Added experimental function `convertToRGBTriplet`. Purpose of this function is to get any supported [color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) and convert it to the internal RGB triplet value.
+- Added a new function `chooseHigherContrast` that can help you to choose the best color compared to the given background (in terms of contrast).
 
 # 2.1.0
 

src/css-colors/README.md

@@ -61,6 +61,20 @@ isAccessible([64, 32, 17], [201, 120, 136], 'GRAPHICAL_OBJECTS'); // true
 
 Note on colors accessibility: it can happen that some backgrounds are never accessible under **AAA** criteria. For example [`#FF1A1A`](https://webaim.org/resources/contrastchecker/?fcolor=000000&bcolor=FF1A1A) always fails "normal text" test for **AAA** criteria (no matter whether you choose completely white or completely black font).
 
+## What color is the best for this background?
+
+```js
+import { chooseHigherContrast } from '@adeira/css-colors';
+
+chooseHigherContrast(
+  [255, 255, 255], // foreground color 1 ✅
+  [128, 128, 128], // foreground color 1 ❌
+  [0, 0, 0], // background
+);
+```
+
+The function above returns `[255, 255, 255]` because white is better on a black background than grey.
+
 ## Normalize colors
 
 ```js

src/css-colors/src/__tests__/chooseHigherContrast.test.js

@@ -0,0 +1,33 @@
+// @flow strict
+
+import calculateContrastRatio from '../calculateContrastRatio';
+import chooseHigherContrast from '../chooseHigherContrast';
+
+// HELP:
+// [0, 0, 0], // black
+// [255, 255, 255], // white
+
+it('works when there is no good choice', () => {
+  expect(chooseHigherContrast([0, 0, 0], [0, 0, 0], [0, 0, 0])).toStrictEqual([0, 0, 0]);
+  expect(chooseHigherContrast([255, 255, 255], [255, 255, 255], [255, 255, 255])).toStrictEqual([
+    255, 255, 255,
+  ]);
+});
+
+it('picks white color on black background', () => {
+  expect(chooseHigherContrast([255, 255, 255], [128, 128, 128], [0, 0, 0])).toStrictEqual([
+    255, 255, 255,
+  ]);
+});
+
+it('chooses the first foreground when contrasts are identical', () => {
+  const fgA = [0, 0, 245];
+  const fgB = [125, 28, 123];
+  const bg = [133, 133, 133];
+
+  expect(calculateContrastRatio(fgA, bg)).toBe(2.45);
+  expect(calculateContrastRatio(fgB, bg)).toBe(2.45);
+
+  expect(chooseHigherContrast(fgA, fgB, bg)).toStrictEqual(fgA);
+  expect(chooseHigherContrast(fgB, fgA, bg)).toStrictEqual(fgB);
+});

src/css-colors/src/chooseHigherContrast.js

@@ -0,0 +1,19 @@
+// @flow strict
+
+import calculateContrastRatio from './calculateContrastRatio';
+
+/**
+ * This function takes 2 possible foreground colors and returns the one which would create larger
+ * contrast against the specified background. It can be used when you are deciding about the best
+ * color for accessibility purposes (the one with higher contrast is better).
+ */
+export default function chooseHigherContrast(
+  rgbForegroundA: [number, number, number],
+  rgbForegroundB: [number, number, number],
+  rgbBackground: [number, number, number],
+): [number, number, number] {
+  const foregroundAContrastRatio = calculateContrastRatio(rgbForegroundA, rgbBackground);
+  const foregroundBContrastRatio = calculateContrastRatio(rgbForegroundB, rgbBackground);
+
+  return foregroundAContrastRatio >= foregroundBContrastRatio ? rgbForegroundA : rgbForegroundB;
+}

src/css-colors/src/index.js

@@ -1,6 +1,7 @@
 // @flow strict
 
 export { default as calculateContrastRatio } from './calculateContrastRatio';
+export { default as chooseHigherContrast } from './chooseHigherContrast';
 export { default as convertToRGBTriplet } from './convertToRGBTriplet';
 export { default as cssColorNames } from './cssColorNames';
 export { default as hex3ToHex6 } from './hex3ToHex6';