feat(colors): adds colors and colors schemes to pattern library

re #147

.gitignore

@@ -9,6 +9,8 @@ src/styleguide/_meta/*.mustache
 # Exclude generated files
 src/styleguide/_patterns/_generated/*.njk
 src/styleguide/_patterns/00-particles/05-logos-and-icons/00-svg-symbols.json
+src/styleguide/_patterns/00-particles/00-color/01-color-palettes.json
+src/styleguide/_patterns/00-particles/00-color/02-color-schemes.json
 
 
 ######### App / OS-specific guff ##########

gulp/color-scheme-tables.js

@@ -0,0 +1,66 @@
+const Color = require('color');
+const kebabCase = require('lodash.kebabcase');
+const { colorSchemes } = require('@buildit/gravity-particles');
+
+
+
+function wcagRating(contrastRatio) {
+  if (contrastRatio > 7) {
+    return 'AAA';
+  }
+  if (contrastRatio > 4.5) {
+    return 'AA';
+  }
+  if (contrastRatio > 3) {
+    return 'A';
+  }
+  return 'Fail';
+}
+
+function gravityCssCustomPropName(group, colorName) {
+  return `--grav-co-grp-${group}-${kebabCase(colorName)}`;
+}
+
+
+function generateColorSchemeTableData(colorScheme) {
+  const groupAColorNames = Object.keys(colorScheme.groupA);
+  const groupBColorNames = Object.keys(colorScheme.groupB);
+
+  const tableData = [];
+  const headerRow = [null].concat(groupAColorNames.map((name) => gravityCssCustomPropName('a', name))); // top-left cell is empty
+  tableData.push(headerRow);
+
+  // Loop "down" the rows of the table, one for each group B color
+  for (let groupBColorName of groupBColorNames) {
+    const row = [gravityCssCustomPropName('b', groupBColorName)]; // left-most cell has color name
+
+    // Loop "across" the current row, adding one cell for each group A color
+    for (let groupAColorName of groupAColorNames) {
+      const colorPair = {
+        colorA: colorScheme.groupA[groupAColorName],
+        colorB: colorScheme.groupB[groupBColorName]
+      };
+
+      const colorA = new Color(colorPair.colorA);
+      const colorB = new Color(colorPair.colorB);
+
+      colorPair.contrastRatio = colorA.contrast(colorB);
+      colorPair.wcagRating = wcagRating(colorPair.contrastRatio);
+
+      row.push(colorPair);
+    }
+
+    tableData.push(row);
+  }
+
+  return tableData;
+}
+
+
+const colorSchemeTables = {};
+Object.keys(colorSchemes).forEach(colorSchemeName => {
+  const colorScheme = colorSchemes[colorSchemeName];
+  colorSchemeTables[colorSchemeName] = generateColorSchemeTableData(colorScheme);
+});
+
+module.exports = colorSchemeTables;

gulp/patternlab.js

@@ -12,11 +12,14 @@ const gulp = require('gulp');
 const sass = require('gulp-sass');
 const eyeglass = require('eyeglass');
 const rename = require("gulp-rename");
+const file = require('gulp-file');
 const path = require('path');
 const argv = require('minimist')(process.argv.slice(2));
+const { colors } = require('@buildit/gravity-particles');
 
 const uiLibPaths = require('../build-api.js');
 const pkgPaths = require('./paths.js');
+const colorSchemeTables = require('./color-scheme-tables.js');
 
 const taskNamePrefix = 'patternlab:';
 
@@ -66,7 +69,34 @@ preSvgSymbolsInfoTask.displayName = taskNamePrefix + 'pre:symbols-info';
 preSvgSymbolsInfoTask.description = 'Copies Gravity\'s symbols.json file to the patterns folder.';
 
 
-const preBuildTask = gulp.parallel(preSvgSymbolsTask, preSvgSymbolsInfoTask);
+const generatedColorPalettesDataFilename = '01-color-palettes.json';
+const generatedColorPalettesDataDir = pkgPaths.srcPatternsPath('00-particles', '00-color');
+generatedFileGlobs.push(path.join(generatedColorPalettesDataDir, generatedColorPalettesDataFilename));
+
+function preColorPaletteDataTask () {
+  const colorPalettesData = {};
+  colorPalettesData.colors = colors;
+
+  return file(generatedColorPalettesDataFilename, JSON.stringify(colorPalettesData, null, 2), { src: true })
+    .pipe(gulp.dest(generatedColorPalettesDataDir));
+}
+
+
+const generatedColorSchemeDataFilename = '02-color-schemes.json';
+const generatedColorSchemeDataDir = pkgPaths.srcPatternsPath('00-particles', '00-color');
+generatedFileGlobs.push(path.join(generatedColorSchemeDataDir, generatedColorSchemeDataFilename));
+
+function preColorSchemeTableDataTask () {
+  const colorSchemeTableData = {};
+  colorSchemeTableData.colorSchemes = colorSchemeTables;
+
+  return file(generatedColorSchemeDataFilename, JSON.stringify(colorSchemeTableData, null, 2), { src: true })
+    .pipe(gulp.dest(generatedColorSchemeDataDir));
+}
+
+
+
+const preBuildTask = gulp.parallel(preSvgSymbolsTask, preSvgSymbolsInfoTask, preColorSchemeTableDataTask, preColorPaletteDataTask);
 
 /******************************************************
  * STYLEGUIDE CSS TASKS

src/styleguide/_patterns/00-particles/00-color/01-color-palettes.njk

@@ -0,0 +1,26 @@
+
+{% macro colorSwatch(name, value) %}
+<div class="sg-color-swatch">
+  <div class="sg-color-swatch__preview">
+    <span style="background-color: {{ value }};"></span>
+  </div>
+  <div class="sg-color-swatch__details">
+    <strong>{{ name }}</strong>
+    <code>{{ value }}</code>
+  </div>
+</div>
+{% endmacro -%}
+
+<p><strong>Note:</strong> The following color palettes are shown for reference only. Color values should never be hard-coded in the SASS/CSS and <code>gravity-ui-web</code>'s SASS code therefore does <em>not</em> provide variables for these colors. Instead, <em>only</em> the CSS custom properties provided Gravity's color system should be referenced when applying colors to UI elements. This ensures that all UI elements work with all available color schemes.</p>
+
+{%- for brand, palettes in colors %}
+  <h4>{{ brand }}</h4>
+  {% for palette, colors in palettes %}
+    <h5>{{ palette }}</h5>
+    <div class="sg-color-palette">
+      {% for colorName, colorValue in colors %}
+        {{ colorSwatch(colorName, colorValue) | safe }}
+      {% endfor %}
+    </div>
+  {% endfor %}
+{% endfor -%}

src/styleguide/_patterns/00-particles/00-color/02-color-schemes.njk

@@ -0,0 +1,59 @@
+{%- macro colorProp(varName) %}
+<span class="sg-color-prop">
+  <span style="background-color: var({{ varName }});"></span>
+  <code>{{ varName }}</code>
+</span>
+{% endmacro -%}
+
+{%- macro colorContrast(contrastRatio, wcagRating, colorA, colorB) %}
+<span class="sg-color-contrast">
+  <span class="sg-color-contrast__sample" style="color: {{ colorA }}; background-color: {{ colorB }};">Xyz</span>
+  <span class="sg-color-contrast__sample" style="color: {{ colorB }}; background-color: {{ colorA }};">Xyz</span>
+  <span class="sg-color-contrast__ratio">{{ contrastRatio | round(3) }}</span>
+  <span class="sg-color-contrast__score sg-color-contrast__score--{{ wcagRating | lower }}">{{ wcagRating }}</span>
+</span>
+{% endmacro -%}
+
+{%- macro colorSchemeTable(tableData) %}
+<table>
+  {% for row in tableData %}
+    <tr>
+      {% if loop.first %}
+        {# header row #}
+        {% for cell in row %}
+          {% if loop.first %}
+            {# top-left cell is blank #}
+            <td></td>
+          {% else %}
+            <th>
+              {{ colorProp(cell) | safe }}
+            </th>
+          {% endif %}
+        {% endfor %}
+      {% else %}
+        {# normal row #}
+        {% for cell in row %}
+          {% if loop.first %}
+            {# first cell is row header #}
+            <th>
+              {{ colorProp(cell) | safe }}
+            </th>
+          {% else %}
+            <td>
+              {{ colorContrast(cell.contrastRatio, cell.wcagRating, cell.colorA, cell.colorB) | safe }}
+            </td>
+          {% endif %}
+        {% endfor %}
+      {% endif %}
+    </tr>
+  {% endfor %}
+</table>
+{% endmacro -%}
+
+{% for schemeName, schemeTableData in colorSchemes %}
+<section class="sg-color-scheme grav-u-color-scheme-{{ schemeName }}">
+  <h4>{{ schemeName | title }} color scheme</h4>
+  <p>Can be applied to containers using the <code>grav-u-color-scheme-{{ schemeName }}</code> utility class.</p>
+  {{ colorSchemeTable(schemeTableData) | safe }}
+</section>
+{% endfor %}