chore(docs): v3 docs update

CONTRIBUTING.md

@@ -82,6 +82,6 @@ We use [docsify](https://docsify.js.org/#/) to transform the markdown files into
 
 [issues]: https://github.com/amzn/style-dictionary/issues
 [pr]: https://github.com/amzn/style-dictionary/pulls
-[license]: https://github.com/amzn/style-dictionary/blob/master/LICENSE
+[license]: https://github.com/amzn/style-dictionary/blob/main/LICENSE
 [cla]: http://en.wikipedia.org/wiki/Contributor_License_Agreement
-[eslint]: https://github.com/amzn/style-dictionary/blob/master/.eslintrc.json
+[eslint]: https://github.com/amzn/style-dictionary/blob/main/.eslintrc.json

README.md

@@ -2,17 +2,16 @@
 
 [![npm version](https://img.shields.io/npm/v/style-dictionary.svg?style=flat-square)](https://badge.fury.io/js/style-dictionary)
 ![license](https://img.shields.io/npm/l/style-dictionary.svg?style=flat-square)
-[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/amzn/style-dictionary/blob/master/CONTRIBUTING.md#submitting-pull-requests)
-<br/>
-[![Build Status](https://img.shields.io/travis/amzn/style-dictionary.svg?style=flat-square)](https://travis-ci.org/amzn/style-dictionary)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/amzn/style-dictionary/blob/main/CONTRIBUTING.md#submitting-pull-requests)
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/amzn/style-dictionary/Test?style=flat-square)](https://github.com/amzn/style-dictionary/actions/workflows/test.yml)
 [![downloads](https://img.shields.io/npm/dm/style-dictionary.svg?style=flat-square)](https://www.npmjs.com/package/style-dictionary)
 
 # Style Dictionary
 > *Style once, use everywhere.*
 
 A Style Dictionary uses design tokens to define styles once and use those styles on any platform or language. It provides a single place to create and edit your styles, and exports these properties to all the places you need - 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.
 
-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.
+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. Style Dictionary solves this by automatically generating style definitions across all platforms from a single source - removing roadblocks, errors, and inefficiencies across your workflow.
 
 For detailed usage head to https://amzn.github.io/style-dictionary
 
@@ -24,7 +23,7 @@ For detailed usage head to https://amzn.github.io/style-dictionary
 * [Usage](#usage)
 * [Example](#example)
 * [Quick Start](#quick-start)
-* [Style Properties](#style-properties)
+* [Design tokens](#design-tokens)
 * [Extending](#extending)
 * [Contributing](#contributing)
 * [License](#license)
@@ -93,10 +92,11 @@ StyleDictionary.buildAllPlatforms();
 ## Example
 [Take a look at some of our examples](examples/)
 
-A style dictionary is a collection of style properties, key/value pairs that describe stylistic attributes like colors, sizes, icons, motion, etc. A style dictionary defines these style properties in JSON files, and can also include static assets like images and fonts. Here is a basic example of what the package structure can look like:
+A style dictionary is a collection of design tokens, key/value pairs that describe stylistic attributes like colors, sizes, icons, motion, etc. A style dictionary defines these design tokens in JSON or Javascript files, and can also include static assets like images and fonts. Here is a basic example of what the package structure can look like:
+
 ```
 ├── config.json
-├── properties/
+├── tokens/
 │   ├── size/
 │       ├── font.json
 │   ├── color/
@@ -108,10 +108,11 @@ A style dictionary is a collection of style properties, key/value pairs that des
 ```
 
 ### config.json
-This tells the style dictionary build system how and what to build. The default file path is config.json in the root of the project, but you can name it whatever you want, you can pass in the `--config` flag.
+This tells the style dictionary build system how and what to build. The default file path is `config.json` or `config.js` in the root of the project, but you can name it whatever you want by passing in the `--config` flag to the [CLI](https://amzn.github.io/style-dictionary/#/using_the_cli).
+
 ```json
 {
-  "source": ["properties/**/*.json"],
+  "source": ["tokens/**/*.json"],
   "platforms": {
     "scss": {
       "transformGroup": "scss",
@@ -132,9 +133,11 @@ This tells the style dictionary build system how and what to build. The default
   }
 }
 ```
+
 | Attribute | Type | Description |
 | :--- | :--- | :--- |
-| source | Array | Paths to the property json files. Can have globs. |
+| source | Array | An array of file path [globs](https://github.com/isaacs/node-glob) to design token files. Style Dictionary will do a deep merge of all of the token files, allowing you to organize your files files however you want. |
+| include | Array | An array of file path [globs](https://github.com/isaacs/node-glob) to design token 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 include. |
 | platforms | Object | Sets of platform files to be built. |
 | platforms | Array | Paths to the property json files. Can have globs. |
 | platform.transformGroup | String (optional) | Apply a group of transforms to the properties, must either define this or `transforms`. |
@@ -147,6 +150,7 @@ This tells the style dictionary build system how and what to build. The default
 | 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". |
 
 ### Properties
+
 ```json
 {
   "size": {
@@ -187,16 +191,21 @@ float const SizeFontBase = 16.00f;
 
 
 ## Quick Start
+
 The style dictionary framework comes with some example code to get you stared. Install the node module globally, create a directory and `cd` into it.
+
 ```
 $ npm i -g style-dictionary
 $ mkdir MyStyleDictionary
 $ cd MyStyleDictionary
 ```
+
 Now run:
+
 ```
 $ style-dictionary init basic
 ```
+
 This command will copy over the example files found in [example](examples/) in this repo. Now you have an example project set up. You can make changes to the style dictionary and rebuild the project by running:
 
 ```
@@ -206,13 +215,13 @@ $ style-dictionary build
 Take a look at the documentation for the example code.
 
 
-## Style Properties
+## Design tokens
 
-A style property is an attribute to describe something visually. It is atomic (it cannot be broken down further). Style properties have a name, a value, and optional attributes or metadata. The name of a property can be anything, but we have a proposed naming structure that works really well in the next section.
+A design token is an attribute to describe something visually. It is atomic (it cannot be broken down further). Style properties have a name, a value, and optional attributes or metadata. The name of a token can be anything, but we have a proposed naming structure that works really well in the next section.
 
 ### Category/Type/Item Structure
 
-While not exactly necessary, we feel this classification structure of style properties makes the most sense semantically. Style properties can be organized into a hierarchical tree structure with the top level, category, defining the primitive nature of the property. For example, we have the color category and every property underneath is always a color. As you proceed down the tree to type, item, sub-item, and state, you get more specific about what that color is. Is it a background color, a text color, or a border color? What kind of text color is it? You get the point. Now you can structure your property json files like simple objects:
+While not exactly necessary, we feel this classification structure of style properties makes the most sense semantically. Style properties can be organized into a hierarchical tree structure with the top level, category, defining the primitive nature of the token. For example, we have the color category and every token underneath is always a color. As you proceed down the tree to type, item, sub-item, and state, you get more specific about what that color is. Is it a background color, a text color, or a border color? What kind of text color is it? You get the point. Now you can structure your token json files like simple objects:
 
 ```
 {
@@ -225,15 +234,15 @@ While not exactly necessary, we feel this classification structure of style prop
 }
 ```
 
- The CTI is implicit in the structure, the category and type is 'size' and 'font', and there are 2 properties 'base' and 'large'.
+The CTI is implicit in the structure, the category and type is 'size' and 'font', and there are 2 properties 'base' and 'large'.
 
- Structuring style properties in this manner gives us consistent naming and accessing of these properties. You don't need to remember if it is button_color_error or error_button_color, it is color_background_button_error!
+Structuring style properties in this manner gives us consistent naming and accessing of these properties. You don't need to remember if it is button_color_error or error_button_color, it is color_background_button_error!
 
- You can organize and name your style properties however you want, there are no restrictions. But we have a good amount of helpers if you do use this structure, like the 'attribute/cti' transform which adds attributes to the property of its CTI based on the path in the object. There are a lot of name transforms as well for when you want a flat structure like for Sass variables.
+You can organize and name your style properties however you want, there are no restrictions. But we have a good amount of helpers if you do use this structure, like the 'attribute/cti' transform which adds attributes to the token of its CTI based on the path in the object. There are a lot of name transforms as well for when you want a flat structure like for Sass variables.
 
- Also, the CTI structure provides a good mechanism to target transforms for specific kinds of properties. All of the transforms provided by the framework use the CTI of a property to know if it should be applied. For instance, the 'color/hex' transform only applies to properties of the category 'color'.
+Also, the CTI structure provides a good mechanism to target transforms for specific kinds of properties. All of the transforms provided by the framework use the CTI of a token to know if it should be applied. For instance, the 'color/hex' transform only applies to properties of the category 'color'.
 
-You can also add a _comment_ to a style property:
+You can also add a _comment_ to a design token:
 
 ```
 {

docs/README.md

@@ -2,17 +2,16 @@
 
 [![npm version](https://img.shields.io/npm/v/style-dictionary.svg?style=flat-square)](https://badge.fury.io/js/style-dictionary)
 ![license](https://img.shields.io/npm/l/style-dictionary.svg?style=flat-square)
-[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/amzn/style-dictionary/blob/master/CONTRIBUTING.md#submitting-pull-requests)
-<br/>
-[![Build Status](https://img.shields.io/travis/amzn/style-dictionary.svg?style=flat-square)](https://travis-ci.org/amzn/style-dictionary)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/amzn/style-dictionary/blob/main/CONTRIBUTING.md#submitting-pull-requests)
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/amzn/style-dictionary/Test?style=flat-square)](https://github.com/amzn/style-dictionary/actions/workflows/test.yml)
 [![downloads](https://img.shields.io/npm/dm/style-dictionary.svg?style=flat-square)](https://www.npmjs.com/package/style-dictionary)
 
 # 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](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.
+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. Style Dictionary 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)
@@ -22,12 +21,12 @@ When you are managing user experiences, it can be quite challenging to keep styl
 
 ## The Basics
 __A style dictionary consists of:__
-1. [Style properties](properties.md), organized in JSON files
+1. [Design tokens](tokens.md), organized in JSON, JSON5, or JS 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
+1. [Configuration](config.md), defining the [transformation](transforms.md) and [formatting](formats.md) of the tokens and assets for each output platform
 
 __What a style dictionary does:__
-1. Transforms style properties and assets into platform specific deliverables
+1. Transforms design tokens 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:__
@@ -39,15 +38,14 @@ __Things you can build with a style dictionary:__
 
 **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. 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.
+The Style Dictionary framework is fully extensible and modular. 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
 
-Please help make this framework better. For more information take a look at [CONTRIBUTING.md](https://github.com/amzn/style-dictionary/blob/master/CONTRIBUTING.md)
+Please help make this framework better. For more information take a look at [CONTRIBUTING.md](https://github.com/amzn/style-dictionary/blob/main/CONTRIBUTING.md)
 
 
 ## License
 
-[Apache 2.0](https://github.com/amzn/style-dictionary/blob/master/LICENSE)
+[Apache 2.0](https://github.com/amzn/style-dictionary/blob/main/LICENSE)

docs/_sidebar.md

@@ -3,16 +3,16 @@
   - [Quick Start](quick_start.md)
   - [Examples](examples.md)
   - [Config](config.md)
-  - [Properties](properties.md)
+  - [Tokens](tokens.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)
+  - [Parsers](parsers.md)
   - [Transforms](transforms.md)
   - [Transform groups](transform_groups.md)
   - [Formats](formats.md)

docs/actions.md

@@ -6,7 +6,7 @@ EDIT scripts/handlebars/templates/api.hbs OR JSDOC COMMENT INSTEAD!
 
 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. 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).
+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/main/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
 
@@ -28,7 +28,7 @@ You use actions in your config file under platforms > [platform] > actions
 
 ## Pre-defined Actions
 
-[lib/common/actions.js](https://github.com/amzn/style-dictionary/blob/master/lib/common/actions.js)
+[lib/common/actions.js](https://github.com/amzn/style-dictionary/blob/main/lib/common/actions.js)
 
 ### android/copyImages 
 

docs/api.md

@@ -142,7 +142,7 @@ const StyleDictionary = require('style-dictionary').extend({
 
 
 
-Adds a custom action to the style property builder. Custom
+Adds a custom action to Style Dictionary. Custom
 actions can do whatever you need, such as: copying files,
 base64'ing files, running other build scripts, etc.
 After you register a custom action, you then use that
@@ -275,7 +275,7 @@ Adds a custom parser to parse style dictionary files
 
 | Param | Type | Description |
 | --- | --- | --- |
-| pattern | <code>Regex</code> | - |
+| pattern | <code>Regex</code> | A file path regular expression to match which files this parser should be be used on. This is similar to how webpack loaders work. `/\.json$/` will match any file ending in '.json', for example. |
 | parse | <code>function</code> | Function to parse the file contents. Takes 1 argument, which is an object with 2 attributes: contents wich is the string of the file contents and filePath. The function should return a plain Javascript object. |
 
 **Example**