feat: adds color tokens, JS export and SCSS export

.gitignore

@@ -1,6 +1,6 @@
 # Exclude build Output
 dist/
-
+.tmp/
 
 ######### App / OS-specific guff ##########
 

README.md

@@ -1,25 +1,70 @@
 # Buildit Gravity Particles
-
 This is the "single source of truth" for design tokens and assets used throughout Buildit's Gravity design system.
 
 
-## Intro
+## Consuming exported design tokens (via NPM)
+Exports of the design tokens in various formats are published as an NPM package: `@buildit/gravity-particles`.
+
+### Setup
+Add the NPM package as a dependency (or dev dependency) to your project:
+```
+npm install --save @buildit/gravity-particles
+```
+
+### Usage: JavaScript / TypeScript
+The design tokens can be consumed in JavaScript (Node.js) applications. TypeScript type declarations are also published.
+
+In your code, you can `require` and use the tokens like so:
+
+```js
+const gravityParticles = require('@buildit/gravity-particles');
+```
+
+
+### Usage: SASS
+The design tokens are also published as SASS variables.
+
+We recommend using [Eyeglass SASS](https://github.com/linkedin/eyeglass) to simplify importing this library into your SASS code. Follow Eyeglass's instructions to integrate it with your SASS compilation options.
+
+Once setup, you can `@import` them into your SASS code like so:
 
-This project is still a work in progress. We are using [Amazon's Style Dictionary](https://amzn.github.io/style-dictionary/) to export our design tokens into various formats. Currently, it is only configured to export them as SASS variables (so that they can then be consumed by the  [`gravity-ui-sass`](https://github.com/buildit/gravity-ui-sass) library). However, in future we intend to also export them as JS modules, Adobe swatch files, Mac OS X swatch files and whatever else we might need.
+```scss
+@import 'gravity-particles';
+```
 
 
-## Setup
+## Development
 
+### Setup
 1. Clone this repo to your machine
 1. Run `npm install` to install the dependencies
 
 Congrats, you're all set!
 
+**TIP:** We recommend using [NVM](https://github.com/creationix/nvm) to ensure you have a compatible Node.js version (>= 8.11.1).
+
 
-## Build
+### Build
+To do a build, which exports the tokens in all the supported formats, run:
 
-```sh
+```
 npm run build
 ```
 
-This will create a `dist/` directory containing the exported tokens.
+This will create a `dist/` directory containing the exported tokens. (It will also create a `.tmp/` directory for intermediate build files)
+
+
+### Clean
+To remove any previous build output run:
+
+```
+npm run clean
+```
+
+
+### How it works
+The design tokens are expressed in JSON files under `src/tokens/`. We use Amazon's [Style Dictionary](https://amzn.github.io/style-dictionary/) to export them in various formats.
+
+The configuration, along with some Style Dictionary customisations, are kept under `build-scripts/`.
+
+Finally, we use [Gulp](https://gulpjs.com/) as our task runner to run Style Dictionary and perform other operations needed for the build.

build-api.js

@@ -0,0 +1,55 @@
+/**
+ * Provides programatic access to files that are published by the
+ * `gravity-particles` NPM package.
+ *
+ * This is so that consumers of this package can access those files
+ * in their own build processes (e.g. to copy them to their build dir)
+ * without needing to know the internal directory structure of this
+ * package or having to hard-code file paths in their own build
+ * scripts.
+ *
+ * @public
+ */
+
+// Note, since this file is included in the published NPM package, it
+// must not export paths or filenames that are excluded from the published
+// package. Refer to the 'files' section in package.json to see exactly
+// what gets published and what does not.
+
+const path = require('path');
+const pkgManifest = require('./package.json');
+const bldConsts = require('./build-consts.js');
+
+const pkgDir = __dirname;
+
+
+// Resolves the given path segments relative to the UI lib dist dir
+function distPath(...pathSegements) {
+  return path.resolve(pkgDir, bldConsts.distDirname, ...pathSegements);
+}
+
+
+module.exports = {
+  /**
+   * The Gravity UI SASS version.
+   *
+   * @public
+   */
+  version: pkgManifest.version,
+
+  // ==== Pre-compiled output: ====
+
+  /**
+   * Takes a sequence of path segments relative to the UI library's
+   * distributables directory and returns the absolute path.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the UI library's distributables directory.
+   *
+   * @return {string} Absolute file path to the specified
+   *        distributable directory or file.
+   *
+   * @public
+   */
+  distPath,
+};

build-consts.js

@@ -0,0 +1,22 @@
+/**
+ * Shared constants used by public build-api and private build scripts.
+ *
+ * Although this is shipped as part of the NPM package, it is considered an
+ * internal ("private") API and is therefore not monitored for breaking changes.
+ *
+ * External consumers MUST NOT include this module.
+ *
+ * @private
+ */
+
+module.exports = {
+  /**
+   * Name of root source directory.
+   */
+  srcDirname: 'src',
+
+  /**
+   * Name of root distributables directory.
+   */
+  distDirname: 'dist',
+};

build-scripts/build-paths.js

@@ -0,0 +1,73 @@
+/**
+ * Exports non-published file paths used by the build.
+ */
+
+const path = require('path');
+const bldConsts = require('../build-consts');
+
+// Resolves the given path segments relative to the package root
+function pkgPath(...pathSegements) {
+  return path.resolve(__dirname, '..', ...pathSegements);
+}
+
+
+// Resolves the given path segments relative to the source dir
+function srcPath(...pathSegements) {
+  return pkgPath(bldConsts.srcDirname, ...pathSegements);
+}
+
+// Resolves the given path segments relative to the source dir
+function tmpPath(...pathSegements) {
+  return pkgPath('.tmp', ...pathSegements);
+}
+
+module.exports = {
+  /**
+   * Takes a sequence of path segments relative to tokens source directory
+   * and returns the absolute path.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the tokens source directory.
+   *
+   * @return {string} Absolute file path to the specified source
+   *        directory or file.
+   */
+  srcTokensPath: (...pathSegments) => srcPath('tokens', ...pathSegments),
+
+  /**
+   * Takes a sequence of path segments relative to TypeScript source directory
+   * and returns the absolute path.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the TypeScript source directory.
+   *
+   * @return {string} Absolute file path to the specified source
+   *        directory or file.
+   */
+  srcTsPath: (...pathSegments) => srcPath('ts', ...pathSegments),
+
+  /**
+   * Takes a sequence of path segments relative to the temporary
+   * path for intermediate build output.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the tmp directory.
+   *
+   * @return {string} Absolute file path to the specified tmp
+   *        directory or file.
+   */
+  tmpPath,
+
+  /**
+   * Takes a sequence of path segments relative to the temporary TypeScript
+   * path.
+   *
+   * @param  {...string} pathSegements One or more path segments
+   *        relative to the TypeScript tmp directory.
+   *
+   * @return {string} Absolute file path to the specified tmp
+   *        directory or file.
+   */
+  tmpTsPath: (...pathSegments) => tmpPath('ts', ...pathSegments)
+
+};

build-scripts/style-dictionary/config.js

@@ -0,0 +1,71 @@
+/**
+ * Returns a configured StyleDictiory instance.
+ */
+const path = require('path');
+
+const bldApi = require('../../build-api');
+const bldPaths = require('../build-paths');
+const sdNameTransforms = require('./transforms-name');
+const sdFilters = require('./filters');
+const sdFormats = require('./formats');
+
+/**
+ * Configure StyleDictionary with ALL THE THINGS and
+ * export it.
+ */
+module.exports = require('style-dictionary')
+  .registerFilter(sdFilters.isColor)
+  .registerFilter(sdFilters.isColorScheme)
+  .registerTransform(sdNameTransforms.gravitySassVar)
+  .registerTransformGroup({
+    name: 'gravity-scss',
+    transforms: ['attribute/cti', sdNameTransforms.gravitySassVar.name, 'color/css']
+  })
+  .registerTransformGroup({
+    name: 'gravity-ts',
+    transforms: ['attribute/cti', 'name/cti/camel', 'color/css']
+  })
+  .registerFormat(sdFormats.colorSchemeScss)
+  .registerFormat(sdFormats.colorSchemeTs)
+  .extend({
+    source: [
+      bldPaths.srcTokensPath('**', '*.json')
+    ],
+    platforms: {
+      // SCSS output
+      scss: {
+        transformGroup: 'gravity-scss',
+        buildPath: `${bldApi.distPath('scss')}${path.sep}`,
+        files: [
+          {
+            filter: 'isColor',
+            destination: 'colors.scss',
+            format: 'scss/variables'
+          },
+          {
+            filter: 'isColorScheme',
+            destination: 'color-schemes.scss',
+            format: sdFormats.colorSchemeScss.name
+          }
+        ]
+      },
+
+      // TypeScript output
+      ts: {
+        transformGroup: 'gravity-ts',
+        buildPath: `${bldPaths.tmpTsPath()}${path.sep}`,
+        files: [
+          {
+            filter: 'isColor',
+            destination: 'colors.ts',
+            format: 'javascript/es6'
+          },
+          {
+            filter: 'isColorScheme',
+            destination: 'color-schemes.ts',
+            format: sdFormats.colorSchemeTs.name
+          }
+        ]
+      }
+    }
+  });

build-scripts/style-dictionary/filters.js

@@ -0,0 +1,22 @@
+/**
+ * Custom StyleDictionary filters that can be registered via
+ * `StyleDictionary.registerFilter()`.
+ */
+
+module.exports = {
+  /**
+   * Matches properties whose category is "colorScheme".
+   */
+  isColorScheme: {
+    name: 'isColorScheme',
+    matcher: prop => prop.attributes.category === 'colorScheme'
+  },
+
+  /**
+   * Matches properties whose category is "color".
+   */
+  isColor: {
+    name: 'isColor',
+    matcher: prop => prop.attributes.category === 'color'
+  }
+};

build-scripts/style-dictionary/formats.js

@@ -0,0 +1,30 @@
+/**
+ * Custom StyleDictionary formats that can be registered via
+ * `StyleDictionary.registerFormat()`.
+ */
+
+const path = require('path');
+const nunjucks = require('nunjucks');
+
+
+module.exports = {
+  colorSchemeScss: {
+    name: 'scss/color-scheme',
+    formatter: (dictionary, config) => {
+      return nunjucks.render(path.resolve(__dirname, 'formats/color-scheme-scss.nunj'), {
+        dictionary,
+        config
+      });
+    }
+  },
+
+  colorSchemeTs: {
+    name: 'ts/color-scheme',
+    formatter: (dictionary, config) => {
+      return nunjucks.render(path.resolve(__dirname, 'formats/color-scheme-ts.nunj'), {
+        dictionary,
+        config
+      });
+    }
+  }
+};

build-scripts/style-dictionary/formats/color-scheme-scss.nunj

@@ -0,0 +1,19 @@
+{% macro renderColorProperty(colorName, colorProp) -%}
+'{{colorProp.attributes.subitem}}': {{colorProp.value}},
+{%- endmacro %}
+
+{% for name, scheme in dictionary.properties.colorScheme %}
+$grav-co-scheme-{{ name }}: (
+  'group-a': (
+  {%- for colorName, colorProp in scheme.groupA %}
+    {{ renderColorProperty(colorName, colorProp) -}}
+  {% endfor %}
+  ),
+
+  'group-b': (
+  {%- for colorName, colorProp in scheme.groupB %}
+    {{ renderColorProperty(colorName, colorProp) -}}
+  {% endfor %}
+  )
+);
+{% endfor %}