Custom output color names option

packages/contrast-colors/README.md

@@ -36,19 +36,16 @@ let myTheme = generateAdaptiveTheme({
     {
       name: 'gray',
       colorKeys: ['#cacaca'],
-      colorspace: 'HSL',
       ratios: [1, 2, 3, 4.5, 8, 12]
     },
     {
       name: 'blue',
       colorKeys: ['#5CDBFF', '#0000FF'],
-      colorspace: 'HSL',
-      ratios: [3, 4.5]
+      ratios: [3, 4.5],
     },
     {
       name: 'red',
       colorKeys: ['#FF9A81', '#FF0000'],
-      colorspace: 'HSL',
       ratios: [3, 4.5]
     }
   ],
@@ -76,11 +73,26 @@ myTheme(brightness, contrast);
 #### `colorScales` *[array of objects]*:
 Each object contains the necessary parameters for [generating colors by contrast](#generateContrastColors) with the exception of the `name` parameter.
 
+Example of `colorScales` object with all options:
+
+```js
+  {
+    name: 'blue',
+    colorKeys: ['#5CDBFF', '#0000FF'],
+    colorSpace: 'LCH',
+    ratios: [3, 4.5],
+    swatchNames: ['blue--largeText', 'blue--normalText']
+  }
+```
+
 #### `baseScale` *string (enum)*:
 String value matching the `name` of a `colorScales` object to be used as a [base scale](#generateBaseScale) (background color). This creates a scale of values from 0-100 in lightness, which is used for `brightness` parameter. Ie. `brightness: 90` returns the 90% lightness value of the base scale.
 
 #### `name` *string*:
-Unique name for each color scale. This value will be used for the output color keys, ie `blue100: '#5CDBFF'`
+Unique name for each color scale. This value refers to the entire color group _(eg "blue")_ and will be used for the output color keys, ie `blue100: '#5CDBFF'`
+
+#### `swatchNames` *array*:
+This option is for specifying the exact names of your theme's generated colors. By default, names are incremented in `100`s such as `blue100`, `blue200`. This can be overridden by specifying an array of desired output names, such as `['Blue_1', 'Blue_2']`.
 
 #### `brightness` *number*:
 Optional value from 0-100 indicating the brightness of the base / background color. If undefined, `generateAdaptiveTheme` will return a function
@@ -201,8 +213,8 @@ List of numbers to be used as target contrast ratios.
 #### `colorspace` *string*:
 The colorspace in which the key colors will be interpolated within. Below are the available options:
 
-- [Lch](https://en.wikipedia.org/wiki/HCL_color_space)
-- [Lab](https://en.wikipedia.org/wiki/CIELAB_color_space)
+- [LCH](https://en.wikipedia.org/wiki/HCL_color_space)
+- [LAB](https://en.wikipedia.org/wiki/CIELAB_color_space)
 - [CAM02](https://en.wikipedia.org/wiki/CIECAM02)
 - [HSL](https://en.wikipedia.org/wiki/HSL_and_HSV)
 - [HSLuv](https://en.wikipedia.org/wiki/HSLuv)

packages/contrast-colors/index.js

@@ -13,6 +13,7 @@ governing permissions and limitations under the License.
 const d3 = require('./d3.js');
 
 const { catmullRom2bezier, prepareCurve } = require('./curve.js');
+const { color } = require('./d3.js');
 
 function smoothScale(ColorsArray, domains, space) {
   const points = space.channels.map(() => []);
@@ -450,6 +451,16 @@ function generateAdaptiveTheme({colorScales, baseScale, brightness, contrast = 1
   if (!Array.isArray(colorScales)) {
     throw new Error('colorScales must be an array of objects');
   }
+  for (let i=0; i < colorScales.length; i ++) {
+    if (colorScales[i].swatchNames) { // if the scale has custom swatch names
+      let ratioLength = colorScales[i].ratios.length;
+      let swatchNamesLength = colorScales[i].swatchNames.length;
+
+      if (ratioLength !== swatchNamesLength) {
+        throw new Error('`${colorScales[i].name}`ratios and swatchNames must be equal length')
+      }
+    }
+  }
 
   if (brightness === undefined) {
     return function(brightness, contrast) {
@@ -480,6 +491,7 @@ function generateAdaptiveTheme({colorScales, baseScale, brightness, contrast = 1
       let name = colorScales[i].name;
       let ratios = colorScales[i].ratios;
       let smooth = colorScales[i].smooth;
+      let swatchNames = colorScales[i].swatchNames;
       let newArr = [];
       let colorObj = {
         name: name,
@@ -508,9 +520,22 @@ function generateAdaptiveTheme({colorScales, baseScale, brightness, contrast = 1
         smooth: smooth
       });
 
+      let customNamedSwatches;
+      if(!colorScales[i].swatchNames) {
+        customNamedSwatches = false;
+      } else {
+        customNamedSwatches = true;
+      }
+
       for (let i=0; i < outputColors.length; i++) {
-        let rVal = ratioName(ratios)[i];
-        let n = name.concat(rVal);
+        let n;
+        if(!customNamedSwatches) {
+          let rVal = ratioName(ratios)[i];
+          n = name.concat(rVal);
+        }
+        else {
+          n = swatchNames[i];
+        }
 
         let obj = {
           name: n,
@@ -520,6 +545,7 @@ function generateAdaptiveTheme({colorScales, baseScale, brightness, contrast = 1
         newArr.push(obj)
       }
       arr.push(colorObj);
+
     }
 
     return arr;

packages/contrast-colors/test/generateAdaptiveTheme.test.js

@@ -415,6 +415,77 @@ test('should generate dark theme with increased contrast', function() {
 });
 
 
+test('should generate colors with user-defined names', function() {
+  let theme = generateAdaptiveTheme({
+    baseScale: 'gray',
+    colorScales: [
+      {
+        name: "gray",
+        colorKeys: ['#cacaca'],
+        colorspace: 'HSL',
+        ratios: [-1.8, -1.2, 1, 1.2, 1.4, 2, 3, 4.5, 6, 8, 12, 21],
+        swatchNames: ['GRAY_1', 'GRAY_2', 'GRAY_3', 'GRAY_4', 'GRAY_5', 'GRAY_6', 'GRAY_7', 'GRAY_8', 'GRAY_9', 'GRAY_10', 'GRAY_11', 'GRAY_12']
+      },
+      {
+        name: "blue",
+        colorKeys: ['#0000ff'],
+        colorspace: 'LAB',
+        ratios: [2, 3, 4.5, 8, 12],
+        swatchNames: ['BLUE_LOW_CONTRAST', 'BLUE_LARGE_TEXT', 'BLUE_TEXT', 'BLUE_HIGH_CONTRAST', 'BLUE_HIGHEST_CONTRAST']
+      },
+      {
+        name: "red",
+        colorKeys: ['#ff0000'],
+        colorspace: 'RGB',
+        ratios: [2, 3, 4.5, 8, 12],
+        swatchNames: ['red--lowContrast', 'red--largeText', 'red--text', 'red--highContrast', 'red--highestContrast']
+      }
+    ]});
+    let themeLight = theme(20, 1.5);;
+
+    expect(themeLight).toEqual([
+      { background: "#303030" },
+      {
+        name: 'gray',
+        values: [
+          {name: "GRAY_1", contrast: -2.2, value: "#000000"},
+          {name: "GRAY_2", contrast: -1.3, value: "#1c1c1c"},
+          {name: "GRAY_3", contrast: 1, value: "#303030"},
+          {name: "GRAY_4", contrast: 1.3, value: "#414141"},
+          {name: "GRAY_5", contrast: 1.6, value: "#4f4f4f"},
+          {name: "GRAY_6", contrast: 2.5, value: "#6b6b6b"},
+          {name: "GRAY_7", contrast: 4, value: "#8e8e8e"},
+          {name: "GRAY_8", contrast: 6.25, value: "#b3b3b3"},
+          {name: "GRAY_9", contrast: 8.5, value: "#d0d0d0"},
+          {name: "GRAY_10", contrast: 11.5, value: "#efefef"},
+          {name: "GRAY_11", contrast: 17.5, value: "#ffffff"},
+          {name: "GRAY_12", contrast: 31, value: "#ffffff"}
+        ]
+      },
+      {
+        name: 'blue',
+        values: [
+          {name: "BLUE_LOW_CONTRAST", contrast: 2.5, value: "#6f45ff"},
+          {name: "BLUE_LARGE_TEXT", contrast: 4, value: "#9d73ff"},
+          {name: "BLUE_TEXT", contrast: 6.25, value: "#c3a3ff"},
+          {name: "BLUE_HIGH_CONTRAST", contrast: 11.5, value: "#f4edff"},
+          {name: "BLUE_HIGHEST_CONTRAST", contrast: 17.5, value: "#ffffff"}
+        ]
+      },
+      {
+        name: 'red',
+        values: [
+          {name: "red--lowContrast", contrast: 2.5, value: "#da0000"},
+          {name: "red--largeText", contrast: 4, value: "#ff4b4b"},
+          {name: "red--text", contrast: 6.25, value: "#ff9494"},
+          {name: "red--highContrast", contrast: 11.5, value: "#ffebeb"},
+          {name: "red--highestContrast", contrast: 17.5, value: "#ffffff"}
+        ]
+      }
+    ]);
+});
+
+
 // Should throw errors
 test('should throw error, not valid base scale option', function() {
   expect(
@@ -446,3 +517,30 @@ test('should throw error, not valid base scale option', function() {
     }
   ).toThrow();
 });
+
+test('should throw error, ratios and names unequal length arrays', function() {
+  expect(
+    () => {
+      let theme = generateAdaptiveTheme({
+        baseScale: 'blue',
+        colorScales: [
+          {
+            name: "blue",
+            colorKeys: ['#0000ff'],
+            colorspace: 'LAB',
+            ratios: [2, 3, 4.5, 8],
+            swatchNames: ['blue1', 'blue2', 'blue3']
+          },
+          {
+            name: "red",
+            colorKeys: ['#ff0000'],
+            colorspace: 'RGB',
+            ratios: [2, 3, 4.5, 8, 12],
+            swatchNames: ['red1', 'red2', 'red3', 'red4', 'red5']
+          }
+        ],
+        brightness: 97
+      });
+    }
+  ).toThrow();
+});