amzn · chazzmoney · Nov 30, 2018 · Nov 17, 2018 · Nov 18, 2018 · Nov 18, 2018
diff --git a/__tests__/__output/json-nested.json b/__tests__/__output/json-nested.json
@@ -0,0 +1,12 @@
+{
+  "color": {
+    "base": {
+      "red": {
+        "primary": "#611D1C",
+        "secondary": {
+          "inverse": "#000000"
+        }
+      }
+    }
+  }
+}
diff --git a/bin/style-dictionary b/bin/style-dictionary
@@ -29,7 +29,7 @@ program
 
 program
   .command('clean')
-  .description('Removes files specificed in the config of the style dictionary package of the current directory.')
+  .description('Removes files specified in the config of the style dictionary package of the current directory.')
   .option('-c, --config <path>', 'set config path. defaults to ./config.json')
   .option('-p, --platform [platform]', 'only clean specific platform(s). Must be defined in the config', collect, [])
   .action(styleDictionaryClean);

diff --git a/docs/README.md b/docs/README.md
@@ -8,102 +8,37 @@
 # Style Dictionary
 > *Style once, use everywhere.*
 
-A Style Dictionary is a system that allows you to define styles once, in a way for any platform or language to consume. A single place to create and edit your styles, and a single command exports these rules to all the places you need them - iOS, Android, CSS, JS, HTML, sketch files, style documentation, etc. It is available as a CLI through npm, but can also be used like any normal node module if you want to extend its functionality.
+A Style Dictionary is a system that allows you to define styles once, in a way for any platform or language to consume. A single place to create and edit your styles, and a single command exports these rules to all the places you need them - iOS, Android, CSS, JS, HTML, sketch files, style documentation, etc. It is available as a [CLI](using_the_cli.md) through npm, but can also be used like any normal [npm module](using_the_npm_module.md) if you want to [extend](extending.md) its functionality.
 
 When you are managing user experiences, it can be quite challenging to keep styles consistent and synchronized across multiple development platforms and devices.  At the same time, designers, developers, PMs and others must be able to have consistent and up-to-date style documentation to enable effective work and communication.  Even then, mistakes inevitably happen and the design may not be implemented accurately.  StyleDictionary solves this by automatically generating style definitions across all platforms from a single source - removing roadblocks, errors, and inefficiencies across your workflow.
 
 ## Watch the Demo on Youtube
 [![Watch the video](assets/fake_player.png)](http://youtu.be/1HREvonfqhY)
 
-## The basics
+## Examples
+[See examples of Style Dictionary here](examples.md)
+
+## The Basics
 __A style dictionary consists of:__
-1. [Style properties](#style-properties) organized in JSON files
-1. Static assets that can be used across platforms
+1. [Style properties](properties.md), organized in JSON files
+1. Static assets (e.g. fonts, icons, images, sounds, etc.), organized into folders
+1. [Configuration](config.md), defining the transformation of the properties and assets for each output platform
 
 __What a style dictionary does:__
-1. Allows the style properties and assets to be consumed in any platform or language
-
-Let's take a look at a very basic example.
-
-```json
-{
-  "size": {
-    "font": {
-      "small" : { "value": "10px" },
-      "medium": { "value": "16px" },
-      "large" : { "value": "24px" },
-      "base"  : { "value": "{size.font.medium.value}" }
-    }
-  }
-}
-```
-
-Here we are creating some basic font size properties. The style property `size.font.small` is "10px" for example. The style definition size.font.base.value is automatically aliased to the value found in size.font.medium.value, so both of those resolve to "16px".
-
-Now what the style dictionary build system will do with this information is convert it to different formats so that you can use these values in any type of codebase. From this one file you can generate any number of files like:
-
-```scss
-$size-font-small: 10px;
-$size-font-medium: 16px;
-$size-font-large: 24px;
-$size-font-base: 16px;
-```
-
-```xml
-<dimen name="font-small">10sp</dimen>
-<dimen name="font-medium">16sp</dimen>
-<dimen name="font-large">24sp</dimen>
-<dimen name="font-base">16sp</dimen>
-```
-
-```objectivec
-float const SizeFontSmall = 10.00f;
-float const SizeFontMedium = 16.00f;
-float const SizeFontLarge = 24.00f;
-float const SizeFontBase = 16.00f;
-```
-
-This is a very simple example, take a deeper dive into the style dictionary framework in
-
-The style dictionary framework is completely extensible and modular so you can create any type of file from a style dictionary.
-If there is a new language, platform, file type, you can extend the style dictionary framework to create the files you need.
-
-__Some other things you can build with a style dictionary__
+1. Transforms style properties and assets into platform specific deliverables
+1. Creates human readable artifacts (e.g. documentation, design libraries, etc)
+
+__Things you can build with a style dictionary:__
+1. Styling files for any platform
 1. Images and graphics
 1. Sketch files
-1. Documentation site
-1. _Literally anything_
-
-
-## Style Properties
-
-> Synonyms: design token, design variable, design constant, atom
-
-A style property is a key/value data to describe any fundamental/atomic visual properties. This information is stored in a canonical
-source, the style dictionary, and transformed for use in different platforms, languages, and contexts. A simple example is a color.
-A color can be represented in many ways, all of these are the same color: `#ffffff`, `rgb(255,255,255)`, `hsl(0,0,1)`.
-
-A style dictionary organizes style properties in a structured way for easy access. Style properties are organized as a deep object
-with the leaf nodes being the style properties.
-
-```json
-{
-  "color": {
-    "font": {
-      "base": { "value": "#111111" },
-      "secondary": { "value": "#333333" },
-      "tertiary": { "value": "#666666" },
-      "inverse": {
-        "base": { "value": "#ffffff" }
-      }
-    }
-  }
-}
-```
-
-In this example there are 4 style properties: `color.font.base`, `color.font.secondary`, `color.font.tertiary`, and `color.font.inverse.base`.
-A style property is any object in the JSON that has a `value` attribute on it. In this way you can nest properties at different levels.
-This allows you to easily access the property as well as do things like get all the inverse font colors.
+1. Documentation website
+1. _Literally anything you want styles or style data in_
+
+**The value of using Style Dictionary to build all of these is that they are all consistent and up to date.**
+
+The Style Dictionary framework is fully extensible and modular so you can create any type of file from a style dictionary.
+If there is a new language, platform, or file type you need, you can easily [extend](extending.md) the style dictionary framework to create the necessary files.
 
 
 ## Contributing

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -2,14 +2,19 @@
   - [Overview](README.md)
   - [Quick Start](quick_start.md)
   - [Examples](examples.md)
+  - [Config](config.md)
+  - [Properties](properties.md)
   - [Package structure](package_structure.md)
   - [Extending](extending.md)
 
 - Reference
+  - [Architecture](architecture.md)
+  - [Build Process](build_process.md)
+  - [Using the CLI](using_the_cli.md)
+  - [Using the NPM Module](using_the_npm_module.md)
   - [API](api.md)
   - [Transforms](transforms.md)
   - [Transform groups](transform_groups.md)
   - [Formats](formats.md)
   - [Templates](templates.md)
   - [Actions](actions.md)
-  - [Build process](build_process.md)
diff --git a/docs/actions.md b/docs/actions.md
@@ -2,7 +2,7 @@
 
 Actions provide a way to run custom build code such as generating binary assets like images.
 
-Here are all the actions that come with the Style Dictionary build system. We try to include what most people might need. You can define custom actions with the [`registerAction`](api.md#registeraction). If you think we are missing some things, take a look at our [contributing docs](https://github.com/amzn/style-dictionary/blob/master/CONTRIBUTING.md) and send us a pull request! If you have a specific need for your project, you can always write your own [custom actions](#adding-custom-actions).
+Here are all the actions that come with the Style Dictionary build system. We try to include what most people might need. If you think we are missing some things, take a look at our [contributing docs](https://github.com/amzn/style-dictionary/blob/master/CONTRIBUTING.md) and send us a pull request! If you have a specific need for your project, you can always create your own custom action with [`registerAction`](api.md?id=registeraction).
 
 You use actions in your config file under platforms > [platform] > actions
 
@@ -26,19 +26,18 @@ You use actions in your config file under platforms > [platform] > actions
 
 [lib/common/actions.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/actions.js)
 
-### android/copyImages 
+### android/copyImages
 
 
 Action to copy images into appropriate android directories.
 
 
 * * *
 
-### copy_assets 
+### copy_assets
 
 
 Action that copies everything in the assets directory to a new assets directory in the build path of the platform.
 
 
 * * *
-
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -0,0 +1,33 @@
+# Architecture Overview
+
+This is how Style Dictionary works under the hood.
+
+![build structure](assets/build-diagram.png)
+
+Let's take a closer look into each of these steps.
+
+## 1. Find all token files
+
+In your [config](config.md) file you define a `source`, which is an array of file paths. This tells Style Dictionary where to find your token files. You can have them anywhere and in any folder structure as long as you tell Style Dictionary where to find them.
+
+## 2. Deep merge token files
+
+Style Dictionary takes all the files it found and performs a deep merge. This allows you to split your token files in any way you like, without worrying about accidentally overriding groups of tokens. This gives Style Dictionary a single, complete token object to work from.
+
+## 3. Split the platforms
+
+For each platform defined in your [config](config.md), Style Dictionary will do a few steps to get it ready to be consumed on that platform. Everything that happens in a platform is non-destructive so you don't need to worry about one platform affecting another.
+
+## 4. Transform the tokens
+
+Style Dictionary now traverses over the whole token object and looks for design tokens. It does this by looking for anything with a `value` key. When it comes across a design token, it then performs all the [transforms](transforms.md) defined in your [config](config.md) in order.
+
+## 5. Resolve aliases
+
+After all the tokens have been transformed, it then does another pass over the token object looking for aliases, which look like `"{size.font.base.value}"`. When it finds these, it then replaces it with the resolved value. You can have any levels of aliases and Style Dictionary will correctly get the final value. Also, because we have a single complete token object, aliases can be in any token file and still work.
+
+## 6. Build files
+
+Now all the design tokens are ready to be written to a file. Style Dictionary takes the whole transformed and resolved token object and for each file defined in the platform it [formats](formats.md) the token object and write the output to a file. Internally, Style Dictionary creates a flat array of all the design tokens it finds in addition to the token object. This is how you can output a flat SCSS variables file.
+
+After Style Dictionary does steps 4-6 for each platform, now you have all your output files that are ready to consume in each platform and codebase.
diff --git a/docs/assets/build-diagram.png b/docs/assets/build-diagram.png
diff --git a/docs/assets/property-definitions.png b/docs/assets/property-definitions.png
diff --git a/docs/build_process.md b/docs/build_process.md
@@ -4,39 +4,13 @@ Here is what the build system is doing under the hood.
 
 ![build structure](assets/build-diagram.png)
 
-## CLI
-
-1. The build system looks for a config file. By default it looks for config.json in the current directory, or you can specify the config path with the `-c --config` flag.
-1. If there is an `includes` attribute in the config, it will take those JSON files and deep merge them into the `properties` object.
-1. It then takes all the JSON files in the `source` attribute in the config and performs a deep merge onto the `properties` object.
+1. The build system reads in a configuration
+1. If there is an `includes` attribute in the config, it will take those files and deep merge them into the `properties` object
+1. It takes all the JSON files in the `source` attribute in the config and performs a deep merge onto the `properties` object
 1. Then it iterates over the platforms in the config and:
-  1. Perform all transforms, in order, defined in the transforms attribute or transformGroup.
-  1. Build all files defined in the files array
-  1. Perform any actions defined in the actions attribute
-
-
-## Node
-
-If you use this as a node module, the steps are slightly different, but the overall.
-
-1. When you call the [`extend`](api.md#extend) method, you can either pass it a path to a JSON or JS config file, or give it a plain object that has the configuration. This will perform steps 1-3 above.
-1. Then you can now call `buildAllPlatforms` or other methods like `buildPlatform('scss')` or `exportPlatform('javascript')`. This is equivalent to step 4 above.
-
-```javascript
-const StyleDictionary = require('style-dictionary');
-
-const styleDictionary = StyleDictionary.extend( 'config.json' );
-// is equivalent to this:
-// const styleDictionary = StyleDictionary.extend(
-//   JSON.parse( fs.readFileSync( 'config.json' ) )
-// )
-
-// You can also extend with an object
-// const styleDictionary = StyleDictionary.extend({ /* config options */ });
+  1. Performs all transforms, in order, defined in the transforms attribute or transformGroup
+  1. Builds all files defined in the files array
+  1. Performs any actions defined in the actions attribute
 
-// This will perform step 3 above, for each platform:
-// 1. Apply transforms
-// 2. Build files
-// 3. Perform actions
-styleDictionary.buildAllPlatforms();
-```
+# How to Build
+You can build a style dictionary [using the cli](using_the_cli.md) or [using the npm module](using_the_npm_module.md).
diff --git a/docs/config.md b/docs/config.md
@@ -0,0 +1,51 @@
+# Configuration
+
+Style dictionaries are configuration driven. Your config file defines what executes and what to output when the style dictionary builds.
+
+By default, Style Dictionary looks for a `config.json` file in the root of your package. You can also specify a custom location when you use the [CLI](using_the_cli.md). If you want a custom build system using the [npm module](using_the_npm_module.md), you can specify a custom location for a configuration file or use a plain Javascript object.
+
+## config.json
+ Here is a quick example:
+```json
+{
+  "source": ["properties/**/*.json"],
+  "platforms": {
+    "scss": {
+      "transformGroup": "scss",
+      "prefix": "sd",
+      "buildPath": "build/scss/",
+      "files": [{
+        "destination": "_variables.scss",
+        "format": "scss/variables"
+      }],
+      "actions": ["copy_assets"]
+    },
+    "android": {
+      "transforms": ["attribute/cti", "name/cti/snake", "color/hex", "size/remToSp", "size/remToDp"],
+      "buildPath": "build/android/src/main/res/values/",
+      "files": [{
+        "destination": "style_dictionary_colors.xml",
+        "format": "android/colors"
+      }]
+    }
+  }
+}
+```
+
+| Attribute | Type | Description |
+| :--- | :--- | :--- |
+| includes | Array[String] (optional) | An array of paths to Style Dictionary property files that contain default styles. The Style Dictionary uses this as a base collection of properties. The properties found using the "source" attribute will overwrite properties found using includes. |
+| source | Array[String] | An array of paths to JSON files that contain style properties. The Style Dictionary will do a deep merge of all of the JSON files so you can separate your properties into multiple files. |
+| platforms | Object | An object containing platform config objects that describe how the Style Dictionary should build for that platform. You can add any arbitrary attributes on this object that will get passed to formats and actions (more on these in a bit). This is useful for things like build paths, name prefixes, variable names, etc.  |
+| platform.transforms | Array[String] (optional) | An array of [transforms](transforms.md) to be performed on the style properties object. These will transform the properties in a non-destructive way so each platform can transform the properties. Transforms to apply sequentially to all properties. Can be a built-in one or you can create your own. |
+| platform.transformGroup | String (optional) | A string that maps to an array of transforms. This makes it easier to reference transforms by grouping them together. You must either define this or `transforms`. |
+| platform.buildPath | String (optional) | Base path to build the files, must end with a trailing slash. |
+| platform.files | Array (optional) | Files to be generated for this platform. |
+| platform.file.destination | String (optional) | Location to build the file, will be appended to the buildPath. |
+| platform.file.format | String (optional) | [Format](formats.md) used to generate the file. Can be a built-in one or you can create your own. |
+| platform.file.filter | Function/Object (optional) | A function or object used to filter the properties that will be included in the file. If a function is provided, each property will be passed to the function and the result (true or false) will determine whether the property is included. If an object is provided, each property will be matched against the object using a partial deep comparison to determine whether the property is included. |
+| platform.file.options | Object (optional) | A set of extra options associated with the file. |
+| platform.file.options.showFileHeader | Boolean | If the generated file should have a "Do not edit + Timestamp" header (where the format supports it). By default is "true". |
+| platform.actions | Array[String] (optional) | [Actions](actions.md) to be performed after the files are built for that platform. Actions can be any arbitrary code you want to run like copying files, generating assets, etc. You can use pre-defined actions or create custom actions. |
+
+----
diff --git a/docs/extending.md b/docs/extending.md
@@ -1,13 +1,17 @@
 # Extending
 
-The style dictionary build system is made to be extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why it is easy to create custom transforms and formats.
+The style dictionary build system is easily extended. We don't know exactly how everyone will want to use style dictionaries in their project, which is why it is easy to create custom transforms and formats.
 
+## Extension Functions in the API
 * [registerTransform](api.md#registertransform)
 * [registerTransformGroup](api.md#registertransformgroup)
 * [registerFormat](api.md#registerformat)
 * [registerTemplate](api.md#registertemplate)
 * [registerAction](api.md#registeraction)
 
+## Extension Examples
+Importing a configuration, defining a new `time/seconds` transform, and building the style dictionary.
+
 ```javascript
 const StyleDictionary = require('style-dictionary').extend('config.json');
 
@@ -25,7 +29,8 @@ StyleDictionary.registerTransform({
 StyleDictionary.buildAllPlatforms();
 ```
 
-You can also export your extended style dictionary as a node module if you need other projects to depend on it.
+
+Export your extended style dictionary as a node module (without building) if you need other projects to depend on it.
 
 ```javascript
 // package a