New cut at documentation PR using current develop branch

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);

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 through npm, but can also be used like any normal node module 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)
 
+## 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), which are organized in JSON files
+1. Static assets, which are delivered across platforms
+1. [Configuration](config.md), which defines the transformation of the properties and assets into deliverables
 
 __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. Allows style properties and assets to be consumed in any platform or language for rendering styles
+1. Allows the creation of digital media for use by humans (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. _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 extend the style dictionary framework to create the necessary files.
 
 
 ## Contributing

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)

docs/architecture.md

@@ -0,0 +1,13 @@
+# Architecture Overview
+
+This is how Style Dictionary works under the hood.
+
+## TODO
+
+1. We need to replace the picture with one that is more representative of the process.
+1. The picture needs to remove the data ovals, which are confusing - this is supposed to show the process
+1. The picture should have more examples underneath the sections to show what is happening
+1. Each platform should be an actual example (android, ios, css), showing some actual differences between the platforms
+1. We need to add a section below the image that contains a step by step walkthrough of each item in the image
+
+![build structure](assets/build-diagram.png)

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).

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](how_to_build#cli). If you are using a [custom build system](how_to_build#custom-build-system), 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-desctructive 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. |
+
+----

docs/formats.md

@@ -6,7 +6,7 @@ your style dictionary.
 
 ### Using formats
 
-You use formats in your config file under platforms > [platform] > files > [file]
+You use formats in your config file under platforms > [platform] > files > [file] > format
 
 ```json
 {
@@ -560,5 +560,3 @@ Creates a sketchpalette file of all the base colors
 ```
 
 * * *
-
-