diff --git a/README.md b/README.md
index c86f4887..5a9cc39d 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,22 @@ A SASS UI library from the Buildit's Gravity design system.
---
+## Table of contents
+* [Using this library](#using-this-library)
+ * [Pre-requisites](#pre-requisites)
+ * [Installation](#installation)
+ * [Build integration](#build-integration)
+ * [Usage](#usage)
+* [Development](#development)
+ * [One-time setup](#one-time-setup)
+ * [Building and running the pattern library locally](#building-and-running-the-pattern-library-locally)
+ * [Building the UI library only](#building-the-ui-library-only)
+ * [Making commits](#making-commits)
+ * [Further information](#further-information)
+* [Deployment](#deployment)
+ * [Travis CI notes](#travis-ci-notes)
+ * [Further information](#further-information-1)
+
## Using this library
@@ -17,23 +33,107 @@ A SASS UI library from the Buildit's Gravity design system.
* [SASS](http://sass-lang.com/) compilation setup in your project
* `npm` (>= v5.8.0)
+
+If you intend to compile Gravity's SASS yourself, we strong recommend:
+
* [Eyeglass](https://github.com/sass-eyeglass/eyeglass) (>= 1.4.1)
+
### Installation
```bash
$ npm install --save-dev @buildit/gravity-ui-sass
```
-### Usage
+### Build integration
+
+Once installed as a dependency, you need to integrate Gravity into your project's build. The [Gravity UI library NPM package](https://www.npmjs.com/package/@buildit/gravity-ui-sass) ships with the following files:
+
+* **Pre-compiled CSS file**
+ * The SASS source from which the CSS was compiled
+* **An SVG file** containing symbol definitions for all Gravity SVG icons
+ * A JSON file containing metadata about the individual SVG icons
+* **Pre-compiled client-side JS file**
+
+You must integrate these into your own project builds as follows:
+
+#### CSS styles
+You need to get Gravity's CSS into your website or app somehow. Possible strategies include:
+
+* Copying Gravity's pre-compiled CSS file to your build output and linking to it from your HTML.
+* Combining Gravity's pre-compiled CSS with your own CSS code.
+ * You can keep them in separate CSS files and link to them individually from your HTML, or you can concatenate the CSS.
+ * Whichever way you choose, **Gravity's CSS must come first** since it includes normalisation rules and sets global default styles.
+* Compiling Gravity's SASS source to CSS yourself.
+ * By itself this is probably pointless (just grab the pre-compiled CSS!), but when adding your own, bespoke styling on top of Gravity this is useful. As with the CSS, you should ensure that Gravity's rules come first in the output. In practice, this amounts to making sure `@import "gravity-ui-sass";` is the first statement in our main SASS file.
+* Embedding Gravity's CSS in a bundle
+ * `import`ing Gravity's CSS or SASS into a JS bundle (with the appropriate loaders setup) is a perfectly valid approach
+ * However, you should **avoid using tools that mangle the CSS class names** (e.g. [CSS Modules](https://github.com/css-modules/css-modules)). Gravity's CSS is designed to be global. Attempting to scope it is not supported and may well break things. If you do this, you're on your own.
+ * That being said, for any _additional_ CSS rules you add _after_ the Gravity ones, you are of course free to use whatever tool or approach you like.
+
+If your chosen approach uses Gravity's pre-compiled CSS, you **must use the [build API](./docs/build-api.md)** to grab the file's path and/or filename.
+
+If your chosen approach uses Gravity's SASS sources, you are encouraged to use [Eyeglass](https://github.com/linkedin/eyeglass) to avoid needing to manually configure `includePaths`. If Eyeglass is not an option, then you **must use the [build API](./docs/build-api.md)** to grab the path and/or filenames for Gravity's SASS files.
+
+
+#### SVG symbols
+Currently, Gravity's SVG symbol definitions need to be inlined into your HTML. Then, whereever you want to _use_ one of the available icons or logos, you should use an inline SVG that references the required symbol's `id` like so:
+
+```html
+
+```
+
+The `height` and `width` properties should be set to ensure that your inline SVG's intrinsic size matches the aspect ratio of the referenced symbol. If you omit them, browsers will [default to a width of `150px` and a height of `100px`](https://www.sitepoint.com/replaced-elements-html-myths-realities/) and the chosen symbol will appear centered within that area.
-In your own SASS you can then include Gravity like so:
+The `aria-lebblledby` should be set to provide a text alternative for the SVG (equivalent to `alt` in `` elements). All of Gravity's SVG symbol definitions contain alternative texts in their `` elements and these have unique `id`s, so that they can be referenced from elsewhere via `aria-lebblledby`.
-```sass
-@import 'gravity-ui-sass';
+You can look up these values manually in [Gravity's pattern library](http://style.buildit.digital/?p=particles-svg-symbols). For convenience and possible automation, Gravity also ships with a JSON file that contains the symbol and title IDs and the intrinsic width and height values for every available symbol. The format of this file is as follows:
+
+```js
+{
+ "symbols": [
+ {
+ "symbolId": "buildit-logo-hollow",
+ "titleId": "buildit-logo-hollow__title",
+ "width": "700px",
+ "height": "700px"
+ },
+ // ...
+ ]
+}
```
-You can view all the available UI components in the [Buildit Living Style Guide](http://style.buildit.digital/).
+As with the CSS, you **must use the [build API](./docs/build-api.md)** to grab the path and/or filename(s) to Gravity's symbols SVG file and symbol info JSON file.
+
+#### JS
+
+_TBD_ (Currently, Gravity is first and foremost a CSS library. It is however likely that future releases will add some kind of JS for interactive UI components. When that happens, this section will be updated accordingly)
+
+
+### Usage
+Once the Gravity library has been integrated into your build, all you need to do is **produce the appropriate DOM elements**. You can view all the available styles and UI components in the [Buildit Living Pattern Library](http://style.buildit.digital/). Use the "Show pattern info" option to view the Nunjucks template and rendered HTML for the component you are viewing.
+
+
+
+You need to recreate the same HTML DOM structure in your project (via static HTML, dynamically via JS or a combination of both - it doesn't matter), and you will get the same appearance.
+
+This is pretty much the same process as using other UI libraries like [Bootstrap CSS](https://getbootstrap.com/) or [Semantic UI](https://semantic-ui.com/). There is one very important difference though: Those libraries tend to use class names exclusively to bind the CSS styles to your markup, meaning that the actual HTML element used rarely matters. For example, in Bootstrap `<button class="btn btn-primary">` and `<span class="btn btn-primary">` will both produce the same _visual_ result.
+
+**Gravity on the other hand often mandates that certain HTML elements or attributes are used**, and sometimes doesn't use classes at all (the equivalent to the Bootstrap primary button example in Gravity would simply be `<button>`). The intention is to promote semantically correct, accessible HTML. An additional benefit is that this often makes markup code is more terse as well.
+
+As a general rule you must therefore ensure that you match:
+* The HTML element used
+* The attributes used (if any) - not only `class`, but others like `type`, `aria-*`, etc. as well
+* For composite "molecule" or "organism" components you must also match the way they have been nested - i.e. don't introduce additional wrappers within the component
+
+Each component also has notes (shown in the pattern info panel) which describe what it should be used for and other noteworthy information.
## Development
@@ -43,35 +143,35 @@ You can view all the available UI components in the [Buildit Living Style Guide]
1. Clone this repo: https://github.com/buildit/gravity-ui-sass
1. Run `npm install` to install all the dev dependencies
-### Building and running the style guide locally
+### Building and running the pattern library locally
-We use Pattern Lab to generate our [Buildit Living Style Guide](http://style.buildit.digital/). During development, it's useful to build and run the style guide locally via:
+We use [Pattern Lab](https://patternlab.io/) to generate our [Buildit Living Pattern Library](http://style.buildit.digital/). During development, it's useful to build and run the pattern library locally via:
```bash
$ npm start
```
-This should also open the style guide in your default web browser. In any case, the URL will be listed in the console output. By default it is: http://localhost:3000/
+This should also open the pattern library in your default web browser. In any case, the URL will be listed in the console output. By default it is: http://localhost:3000/
The local server will then also watch source files under `src/` for changes and automatically trigger rebuilds & browser refreshes as necessary.
-### Building the style guide
+### Building the pattern library
-To only build the style guide (which is, in effect, a static HTML website) but _not_ run a local server, do:
+To only build the pattern library (which is, in effect, a static HTML website) but _not_ run a local server, do:
```bash
$ npm run styleguide
```
-Note that this will _also_ build the UI library. The build output will go into `dist/`. You can view the style guide locally by opening `dist/index.html` in your browser.
+Note that this will _also_ build the UI library. The build output will go into `dist/`. You can view the pattern library locally by opening `dist/index.html` in your browser.
This is mainly intended for automated build and deployments to our hosted [Buildit Living Style Guide](http://style.buildit.digital/).
### Building the UI library only
-To only build the UI library (without the style guide), use:
+To only build the UI library (without the pattern library), use:
```bash
$ npm run build
@@ -92,7 +192,7 @@ in this way may cause your PR to be rejected.
* Coding standards (TBC)
* [Naming conventions](./docs/naming-conventions.md)
-* Contribution guidelines (TBC)
+* [Contribution guidelines](/CONTRIBUTING.md)
* [`git` branching strategy](./docs/branching-strategy.md)
## Deployment
@@ -106,7 +206,7 @@ To be able to run `npm ci` on your machine, and to be sure to create a `package-
`.nvmrc` only allows us to specify Node.js version, but that alone is not enough at the moment, since Node.js 8 comes out of the box with npm version 5.6.0.
-### Further Information
+### Further information
* [Release process](./docs/releasing.md)
* [Travis CI setup](./docs/travis-ci.md) (for automated build & deplpoyments)
* [npm ci docs](https://docs.npmjs.com/cli/ci)
diff --git a/docs/build-api.md b/docs/build-api.md
new file mode 100644
index 00000000..d7eeeb86
--- /dev/null
+++ b/docs/build-api.md
@@ -0,0 +1,89 @@
+# Build API
+
+The `@buildit/gravity-ui-sass` NPM package provides a Node.js API for build scripts to use. It provides file names and paths to the relevant assets contained in the NPM package, as well as useful metadata about the package.
+
+Projects that use Gravity's UI library are **strongly encouraged** to use this API within their build scripts (e.g. [Gulp](https://gulpjs.com/) files or [Webpack](https://webpack.js.org/) configs), instead of hard-coding paths like `../node_modules/@buildit/gravity-ui-sass/some/file.ext`. The build API is part of this package's public API surface, but the actual assets file names and locations are not. So, if `gravity.css` was renamed to `foo.css` in a future release, that would _not_ be considered a breaking change. However, renaming or remoing the `distCssFilename` property of the build API _would_ be a breaking change.
+
+⚠️ **Note:** The build API is strictly intended for build-time scripts and tools. It should never be embedded into your actual build artefacts.
+
+## Using the API
+Simply `require()` (or `import`) `@buildit/gravity-ui-sass/build-api` and then use the properties and functions of the object you receive:
+
+```js
+const gravityPaths = require('@buildit/gravity-ui-sass/build-api');
+
+// === Metadata ===
+console.log(gravityPaths.version); // The Gravity version you have installed. E.g. '0.12.0'
+
+// === Pre-built distributables ===
+console.log( gravityPaths.distCssFilename ); // Filename of the main CSS file. E.g. 'gravity.css'
+console.log( gravityPaths.distCssDebugFilename ); // Filename of the debug CSS file. E.g. 'debug.css'
+console.log( gravityPaths.distSvgSymbolsFilename ); // Filename of the SVG containing symbol definitions. E.g. 'symbols.svg'
+console.log( gravityPaths.distSvgSymbolsInfoFilename ); // Filename of JSON containing SVG symbol metadata. E.g. 'symbols.json'
+console.log( gravityPaths.distJsFilename ); // Filename of main JS file. E.g. 'gravity.js'
+
+// Additionally, the distPath() function is provided to construct the absolute path
+// to any file in the distributables directory.
+
+// For example:
+console.log( gravityPaths.distPath(gravityPaths.distCssFilename) );
+// Will output something like: '/Users/xy123456/code/gravity-ui-sass/dist/ui-lib/gravity.css'
+
+// If invoked with no arguments, it returns the path to the distributables directory:
+console.log( gravityPaths.distPath() );
+// Will output something like: '/Users/xy123456/code/gravity-ui-sass/dist/ui-lib'
+
+// If invoked with multiple arguments, they are treated as path segments relative to the
+// distributables directory. This can be useful for constructing globs that have the
+// correct path separators for your OS:
+console.log( gravityPaths.distPath('**', '*.css') );
+// Will output something like: '/Users/xy123456/code/gravity-ui-sass/dist/ui-lib/**/*.css'
+
+
+// === SASS source code ===
+console.log( gravityPaths.srcSassMainFilename ); // Filename of main SASS file. E.g. 'index.scss'
+console.log( gravityPaths.srcSassDebugFilename ); // Filename of debug SASS file. E.g. 'debug.scss'
+
+// Additionally, the srcSassPath() function is provided to construct the absolute path
+// to any file in SASS source directory. It behaves exactly like the distPath() counterpart
+// described above:
+
+console.log( gravityPaths.srcSassPath() ); // '/Users/xy123456/code/gravity-ui-sass/src/ui-lib/sass
+console.log( gravityPaths.srcSassPath(gravityPaths.srcSassMainFilename) ); // '/Users/xy123456/code/gravity-ui-sass/src/ui-lib/sass/index.scss'
+console.log( gravityPaths.srcSassPath('**', '*.scss') ); // '/Users/xy123456/code/gravity-ui-sass/src/ui-lib/sass/**/*.scss'
+```
+
+## Gulp example
+Here's a simple example of how you might use this API within a Gulp build script:
+
+```js
+// gulpfile.js
+
+const path = require('path');
+const gulp = require('gulp');
+const gravityPaths = require('@buildit/gravity-ui-sass/build-api');
+
+// This project's build output dir
+const buildDir = path.resolve(__dirname, 'public');
+
+// Task to copy Gravity SVG symbols file to build output
+function copyGravitySvgSymbols() {
+ return gulp.src( gravityPaths.distPath(gravityPaths.distSvgSymbolsFilename) )
+ .pipe(gulp.dest( buildDir ));
+}
+
+// Task to copy Gravity's pre-compiled CSS file in the build output
+function copyGravityCss() {
+ return gulp.src( gravityPaths.distPath(gravityPaths.distCssFilename) )
+ .pipe(gulp.dest( buildDir ));
+}
+
+module.exports = {
+ // Default Gulp task to copy SVGs and compile SASS in parallel
+ default: gulp.parallel(copyGravitySvgSymbols, copyGravityCss)
+};
+```
+
+⚠️ **Note on SASS compilation:** When compiling your own SASS, it may be tempting to simply point the SASS compiler at `gravityPaths.srcSassMainFilename` (or to add `gravityPaths.srcSassPath()` to Node SASS's `inludePaths` and then `@import "gravity-ui-sass";` in one of your own SASS files). However, this alone will not work. Gravity's SASS depends on a few external SASS libraries (`@buildit/gravy`, `modularscale-sass` & `normalize-scss`). You must therefore ensure that each library's SASS directory is also added to the Node SASS's `includePaths` option.
+
+Note that Gravity itself and all of those SASS libraries support [Eyeglass](https://github.com/linkedin/eyeglass) which avoids the need to manually set the `includePaths` like that. We therefore recommend using Eyeglass to simplify your SASS build configuration.
diff --git a/docs/gravity-pattern-library.gif b/docs/gravity-pattern-library.gif
new file mode 100644
index 00000000..91393cd9
Binary files /dev/null and b/docs/gravity-pattern-library.gif differ