style-dictionary 3.8.0 → 4.0.0-prerelease.0

package/README.md

@@ -11,7 +11,8 @@
 [![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.*
+
+> _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 tokens 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.
 
@@ -20,56 +21,67 @@ When you are managing user experiences, it can be quite challenging to keep styl
 For detailed usage head to https://amzn.github.io/style-dictionary
 
 ## Watch the Demo on YouTube
+
 [![Watch the video](/docs/assets/fake_player.png)](http://youtu.be/1HREvonfqhY)
 
 ## Experiment in the playground
+
 Try the browser-based Style Dictionary playground: [https://www.style-dictionary-play.dev/](https://www.style-dictionary-play.dev/), built by the folks at [\<div\>RIOTS](https://divriots.com/).
 
 ## Contents
-* [Installation](#installation)
-* [Usage](#usage)
-* [Example](#example)
-* [Quick Start](#quick-start)
-* [Design Tokens](#design-tokens)
-* [Extending](#extending)
-* [Contributing](#contributing)
-* [License](#license)
 
+- [Installation](#installation)
+- [Usage](#usage)
+- [Example](#example)
+- [Quick Start](#quick-start)
+- [Design Tokens](#design-tokens)
+- [Extending](#extending)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
-*Note that you must have node (and npm) installed.*
+
+_Note that you must have node (and npm) installed._
 
 If you want to use the CLI, you can install it globally via npm:
+
 ```bash
 $ npm install -g style-dictionary
 ```
 
 Or you can install it like a normal npm dependency. This is a build tool and you are most likely going to want to save it as a dev dependency:
+
 ```bash
 $ npm install -D style-dictionary
 ```
 
 If you want to install it with yarn:
+
 ```bash
 $ yarn add style-dictionary --dev
 ```
 
 ## Usage
+
 ### CLI
+
 ```bash
 $ style-dictionary build
 ```
+
 Call this in the root directory of your project. The only thing needed is a `config.json` file. There are also arguments:
 
-| Flag | Short Flag | Description |
-| --- | --- | --- |
-| --config \[path\] | -c | Set the config file to use. Must be a .json file |
-| --platform \[platform\] | -p | Only build a specific platform defined in the config file. |
-| --help | -h | Display help content |
-| --version | -v | Display the version |
+| Flag                    | Short Flag | Description                                                |
+| ----------------------- | ---------- | ---------------------------------------------------------- |
+| --config \[path\]       | -c         | Set the config file to use. Must be a .json file           |
+| --platform \[platform\] | -p         | Only build a specific platform defined in the config file. |
+| --help                  | -h         | Display help content                                       |
+| --version               | -v         | Display the version                                        |
 
 ### Node
+
 You can also use the style dictionary build system in node if you want to [extend](#extending) the functionality or use it in another build system like Grunt or Gulp.
+
 ```javascript
 const StyleDictionary = require('style-dictionary').extend('config.json');
 
@@ -77,6 +89,7 @@ StyleDictionary.buildAllPlatforms();
 ```
 
 The `.extend()` method is an overloaded method that can also take an object with the configuration in the same format as a config.json file.
+
 ```javascript
 const StyleDictionary = require('style-dictionary').extend({
   source: ['tokens/**/*.json'],
@@ -84,19 +97,22 @@ const StyleDictionary = require('style-dictionary').extend({
     scss: {
       transformGroup: 'scss',
       buildPath: 'build/',
-      files: [{
-        destination: 'variables.scss',
-        format: 'scss/variables'
-      }]
-    }
+      files: [
+        {
+          destination: 'variables.scss',
+          format: 'scss/variables',
+        },
+      ],
+    },
     // ...
-  }
+  },
 });
 
 StyleDictionary.buildAllPlatforms();
 ```
 
 ## Example
+
 [Take a look at some of our examples](examples/)
 
 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:
@@ -115,6 +131,7 @@ A style dictionary is a collection of design tokens, key/value pairs that descri
 ```
 
 ### config.json
+
 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
@@ -124,36 +141,40 @@ This tells the style dictionary build system how and what to build. The default
     "scss": {
       "transformGroup": "scss",
       "buildPath": "build/",
-      "files": [{
-        "destination": "scss/_variables.scss",
-        "format": "scss/variables"
-      }]
+      "files": [
+        {
+          "destination": "scss/_variables.scss",
+          "format": "scss/variables"
+        }
+      ]
     },
     "android": {
       "transformGroup": "android",
       "buildPath": "build/android/",
-      "files": [{
-        "destination": "font_dimens.xml",
-        "format": "android/fontDimens"
-      }]
+      "files": [
+        {
+          "destination": "font_dimens.xml",
+          "format": "android/fontDimens"
+        }
+      ]
     }
   }
 }
 ```
 
-| Attribute | Type | Description |
-| :--- | :--- | :--- |
-| 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 tokens. The tokens found using the "source" attribute will overwrite tokens found using include. |
-| platforms | Object | Sets of platform files to be built. |
-| platform.transformGroup | String (optional) | Apply a group of transforms to the tokens, must either define this or `transforms`. |
-| platform.transforms | Array (optional) | Transforms to apply sequentially to all tokens. Can be a built-in one or you can create your own. |
-| 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 used to generate the file. Can be a built-in one or you can create your own. [More on formats](https://amzn.github.io/style-dictionary/#/formats) |
-| 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". |
+| Attribute                            | Type              | Description                                                                                                                                                                                                                                                                   |
+| :----------------------------------- | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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 tokens. The tokens found using the "source" attribute will overwrite tokens found using include. |
+| platforms                            | Object            | Sets of platform files to be built.                                                                                                                                                                                                                                           |
+| platform.transformGroup              | String (optional) | Apply a group of transforms to the tokens, must either define this or `transforms`.                                                                                                                                                                                           |
+| platform.transforms                  | Array (optional)  | Transforms to apply sequentially to all tokens. Can be a built-in one or you can create your own.                                                                                                                                                                             |
+| 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 used to generate the file. Can be a built-in one or you can create your own. [More on formats](https://amzn.github.io/style-dictionary/#/formats)                                                                                                                      |
+| 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".                                                                                                                                                    |
 
 ### Design Tokens
 
@@ -161,10 +182,10 @@ This tells the style dictionary build system how and what to build. The default
 {
   "size": {
     "font": {
-      "small" : { "value": "10px" },
+      "small": { "value": "10px" },
       "medium": { "value": "16px" },
-      "large" : { "value": "24px" },
-      "base"  : { "value": "{size.font.medium.value}" }
+      "large": { "value": "24px" },
+      "base": { "value": "{size.font.medium.value}" }
     }
   }
 }
@@ -195,7 +216,6 @@ float const SizeFontLarge = 24.00f;
 float const SizeFontBase = 16.00f;
 ```
 
-
 ## Quick Start
 
 The style dictionary framework comes with some example code to get you started. Install the node module globally, create a directory and `cd` into it.
@@ -220,7 +240,6 @@ $ style-dictionary build
 
 Take a look at the documentation for the example code.
 
-
 ## Design Tokens
 
 A design token is an attribute to describe something visually. It is atomic (it cannot be broken down further). Design tokens 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 we find works really well in the next section.
@@ -233,7 +252,7 @@ While not exactly necessary, we feel this classification structure of design tok
 {
   "size": {
     "font": {
-      "base":  { "value": "16" },
+      "base": { "value": "16" },
       "large": { "value": "20" }
     }
   }
@@ -254,7 +273,7 @@ You can also add a _comment_ to a design token:
 {
   "size": {
     "font": {
-      "base":  {
+      "base": {
         "value": "16",
         "comment": "the base size of the font"
       },
@@ -267,8 +286,7 @@ You can also add a _comment_ to a design token:
 }
 ```
 
-The comment  will appear in the output files, where relevant or the output format supports comments.
-
+The comment will appear in the output files, where relevant or the output format supports comments.
 
 ## Extending
 
@@ -280,12 +298,12 @@ const StyleDictionary = require('style-dictionary').extend('config.json');
 StyleDictionary.registerTransform({
   name: 'time/seconds',
   type: 'value',
-  matcher: function(token) {
+  matcher: function (token) {
     return token.attributes.category === 'time';
   },
-  transformer: function(token) {
+  transformer: function (token) {
     return (parseInt(token.original.value) / 1000).toString() + 's';
-  }
+  },
 });
 
 StyleDictionary.buildAllPlatforms();
@@ -303,7 +321,6 @@ The mascot for Style Dictionary is ["Pascal"](https://github.com/amzn/style-dict
 
 Please help make this framework better. For more information take a look at [CONTRIBUTING.md](CONTRIBUTING.md)
 
-
 ## License
 
 [Apache 2.0](LICENSE)

package/bin/style-dictionary

@@ -2,12 +2,18 @@
 
 'use strict';
 
-var fs = require('fs-extra'),
-    program = require('commander'),
-    path = require('path'),
-    StyleDictionary = require('..'),
-    pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')),
-    chalk = require('chalk');
+import JSON5 from 'json5';
+import program from 'commander';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import node_fs from 'node:fs';
+// usually also node:fs in this context, but can be customized by user
+import { fs } from '../fs.js';
+import StyleDictionary from '../index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const pkg = JSON5.parse(node_fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 
 function collect(val, arr) {
   arr.push(val);
@@ -15,16 +21,14 @@ function collect(val, arr) {
 }
 
 function getConfigPath(options) {
-  var configPath = options.config;
+  let configPath = options.config;
 
-  if(!configPath) {
-    if(fs.existsSync('./config.json')) {
+  if (!configPath) {
+    if (fs.existsSync('./config.json')) {
       configPath = './config.json';
-    }
-    else if(fs.existsSync('./config.js')) {
+    } else if (fs.existsSync('./config.js')) {
       configPath = './config.js';
-    }
-    else {
+    } else {
       console.error('Build failed; unable to find config file.');
       process.exit(1);
     }
@@ -33,75 +37,88 @@ function getConfigPath(options) {
   return configPath;
 }
 
-program
-  .version(pkg.version)
-  .description(pkg.description)
-  .usage('[command] [options]');
-
+program.version(pkg.version).description(pkg.description).usage('[command] [options]');
 
 program
   .command('build')
   .description('Builds a style dictionary package from the current directory.')
   .option('-c, --config <path>', 'set config path. defaults to ./config.json')
-  .option('-p, --platform [platform]', 'only build specific platforms. Must be defined in the config', collect, [])
+  .option(
+    '-p, --platform [platform]',
+    'only build specific platforms. Must be defined in the config',
+    collect,
+    [],
+  )
   .action(styleDictionaryBuild);
 
 program
   .command('clean')
-  .description('Removes files specified 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, [])
+  .option(
+    '-p, --platform [platform]',
+    'only clean specific platform(s). Must be defined in the config',
+    collect,
+    [],
+  )
   .action(styleDictionaryClean);
 
 program
   .command('init <type>')
   .description('Generates a starter style dictionary')
-  .action(function(type){
-    var types = ['basic', 'complete'];
+  .action(function (type) {
+    const types = ['basic', 'complete'];
     if (types.indexOf(type) < 0) {
       console.error('Please supply 1 type of project from: ' + types.join(', '));
       process.exit(1);
     }
 
     console.log('Copying starter files...\n');
-    fs.copySync(path.join(__dirname, '..', 'examples', type), process.cwd());
+    node_fs.copySync(path.join(__dirname, '..', 'examples', type), process.cwd());
     console.log('Source style dictionary starter files created!\n');
-    console.log('Running `style-dictionary build` for the first time to generate build artifacts.\n');
+    console.log(
+      'Running `style-dictionary build` for the first time to generate build artifacts.\n',
+    );
     styleDictionaryBuild();
   });
 
 // error on unknown commands
 program.on('command:*', function () {
-  console.error('Invalid command: %s\nSee --help for a list of available commands.', process.argv.slice(2).join(' '));
+  console.error(
+    'Invalid command: %s\nSee --help for a list of available commands.',
+    process.argv.slice(2).join(' '),
+  );
   process.exit(1);
 });
 
-function styleDictionaryBuild(options) {
+async function styleDictionaryBuild(options) {
   options = options || {};
-  var configPath = getConfigPath(options);
+  const configPath = getConfigPath(options);
 
   // Create a style dictionary object with the config
-  var styleDictionary = StyleDictionary.extend( configPath );
+  const styleDictionary = await StyleDictionary.extend(configPath);
 
   if (options.platform && options.platform.length > 0) {
-    options.platform.forEach(function(platform) {
-      styleDictionary.buildPlatform( platform );
+    options.platform.forEach(function (platform) {
+      styleDictionary.buildPlatform(platform);
     });
   } else {
     styleDictionary.buildAllPlatforms();
   }
 }
 
-function styleDictionaryClean(options) {
+async function styleDictionaryClean(options) {
   options = options || {};
-  var configPath = getConfigPath(options);
+  const configPath = getConfigPath(options);
 
   // Create a style dictionary object with the config
-  var styleDictionary = StyleDictionary.extend( configPath );
+  const styleDictionary = await StyleDictionary.extend(configPath);
 
   if (options.platform && options.platform.length > 0) {
-    options.platform.forEach(function(platform) {
-      styleDictionary.cleanPlatform( platform );
+    options.platform.forEach(function (platform) {
+      styleDictionary.cleanPlatform(platform);
     });
   } else {
     styleDictionary.cleanAllPlatforms();

package/examples/README.md

@@ -13,42 +13,43 @@ $ style-dictionary init [example]
 Where `[example]` is one of: `basic`, `complete`.
 
 ## Basic
+
 [View on Github](https://github.com/amzn/style-dictionary/tree/main/examples/basic)
 
 This example code is bare-bones to show you what this framework can do. Use this if you want to play around with what the Style Dictionary can do.
 
-
 ## Complete
+
 [View on Github](https://github.com/amzn/style-dictionary/tree/main/examples/complete)
 
 This is a more complete package and should have everything you need to get started. This package can be consumed as a Cocoapod on iOS, as a node module for web, and as a local library for Android.
 
 ## Advanced
+
 [View the folder](https://github.com/amzn/style-dictionary/tree/main/examples/advanced)
 
 If you want to look at more advanced examples of possible applications and customizations of Style Dictionary, the [`examples/advanced`](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/) folder on GitHub contains these extra folders:
 
-* [**assets-base64-embed**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/assets-base64-embed) shows how it's possible to embed and distribute assets – like images, icons and fonts – directly as design tokens.
-* [**auto-rebuild-watcher**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/auto-rebuild-watcher) shows how to setup a "watcher" that auto-rebuilds the tokens every time there is a change in the tokens.
-* [**component-cti**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/component-cti) shows how to write component tokens and still use the CTI structure.
-* [**create-react-app**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/create-react-app) shows how to integrate Style Dictionary into a React application.
-* [**create-react-native-app**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/create-react-native-app) shows how to integrate Style Dictionary into a React Native application.
-* [**custom-file-header**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-file-header) shows how to define custom file headers and use them in output files.
-* [**custom-formats-with-templates**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-formats-with-templates) shows how to generate custom output formats using templates, useful when you need to distribute your design tokens into your own pipelines or scripts.
-* [**custom-parser**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-parser) shows how to use custom parsers for token files.
-* [**custom-transforms**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-transforms) shows how to use custom transforms (and transformGroups) to apply custom "transformations" to the design tokens.
-* [**flutter**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/flutter) shows how to integrate with Flutter applications.
-* [**matching-build-files**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/matching-build-files) shows how to output files 1-to-1 with source files.
-* [**multi-brand-multi-platform**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/multi-brand-multi-platform) shows how to set up Style Dictionary to support a multi-brand (for brand theming) and multi-platform (web, iOS, Android) solution, with token values depending on brand and platforms.
-* [**node-modules-as-config-and-properties**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/node-modules-as-config-and-properties) shows how to use Javascript rather than JSON for configuration and token files.
-* [**npm-module**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/npm-module) shows how to set up a style dictionary as an npm module, either to publish to a local npm service or to publish externally.
-* [**referencing_aliasing**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/referencing_aliasing) shows how to use referencing (or "aliasing") to reference a value -or an attribute– of a token and assign it to the value –or attribute– of another token.
-* [**s3**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/s3) shows how to set up a style dictionary to build files for different platforms (web, iOS, Android) and upload those build artifacts, together with a group of assets, to an S3 bucket.
-* [**tokens-deprecation**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/tokens-deprecation) shows one way to deprecate tokens by adding metadata to tokens and using custom formats to output comments in the generated files.
-* [**transitive-transforms**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/transitive-transforms) shows how to use transitive transforms to transform references
-* [**variables-in-outputs**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/variables-in-outputs) shows you how to use the `outputReferences` option to generate files variable references in them.
-* [**yaml-tokens**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/yaml-tokens) shows how to use a custom parser to define your source files in YAML rather than JSON. 
-
+- [**assets-base64-embed**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/assets-base64-embed) shows how it's possible to embed and distribute assets – like images, icons and fonts – directly as design tokens.
+- [**auto-rebuild-watcher**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/auto-rebuild-watcher) shows how to setup a "watcher" that auto-rebuilds the tokens every time there is a change in the tokens.
+- [**component-cti**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/component-cti) shows how to write component tokens and still use the CTI structure.
+- [**create-react-app**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/create-react-app) shows how to integrate Style Dictionary into a React application.
+- [**create-react-native-app**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/create-react-native-app) shows how to integrate Style Dictionary into a React Native application.
+- [**custom-file-header**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-file-header) shows how to define custom file headers and use them in output files.
+- [**custom-formats-with-templates**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-formats-with-templates) shows how to generate custom output formats using templates, useful when you need to distribute your design tokens into your own pipelines or scripts.
+- [**custom-parser**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-parser) shows how to use custom parsers for token files.
+- [**custom-transforms**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/custom-transforms) shows how to use custom transforms (and transformGroups) to apply custom "transformations" to the design tokens.
+- [**flutter**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/flutter) shows how to integrate with Flutter applications.
+- [**matching-build-files**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/matching-build-files) shows how to output files 1-to-1 with source files.
+- [**multi-brand-multi-platform**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/multi-brand-multi-platform) shows how to set up Style Dictionary to support a multi-brand (for brand theming) and multi-platform (web, iOS, Android) solution, with token values depending on brand and platforms.
+- [**node-modules-as-config-and-properties**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/node-modules-as-config-and-properties) shows how to use Javascript rather than JSON for configuration and token files.
+- [**npm-module**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/npm-module) shows how to set up a style dictionary as an npm module, either to publish to a local npm service or to publish externally.
+- [**referencing_aliasing**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/referencing_aliasing) shows how to use referencing (or "aliasing") to reference a value -or an attribute– of a token and assign it to the value –or attribute– of another token.
+- [**s3**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/s3) shows how to set up a style dictionary to build files for different platforms (web, iOS, Android) and upload those build artifacts, together with a group of assets, to an S3 bucket.
+- [**tokens-deprecation**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/tokens-deprecation) shows one way to deprecate tokens by adding metadata to tokens and using custom formats to output comments in the generated files.
+- [**transitive-transforms**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/transitive-transforms) shows how to use transitive transforms to transform references
+- [**variables-in-outputs**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/variables-in-outputs) shows you how to use the `outputReferences` option to generate files variable references in them.
+- [**yaml-tokens**](https://github.com/amzn/style-dictionary/tree/main/examples/advanced/yaml-tokens) shows how to use a custom parser to define your source files in YAML rather than JSON.
 
 ---
 

package/examples/advanced/assets-base64-embed/README.md

@@ -6,7 +6,7 @@ This means that you can centralize all your "core" design values in one single p
 
 #### Running the example
 
-First of all, set up the required dependencies running the command `npm install` in your local CLI environment (if you prefer to use *yarn*, update the commands accordingly).
+First of all, set up the required dependencies running the command `npm install` in your local CLI environment (if you prefer to use _yarn_, update the commands accordingly).
 
 At this point, run `npm run build`. This command will generate the files in the `build` folder.
 
@@ -25,11 +25,13 @@ will be rendered as:
 ```
 <img src="data:image/png;base64,PHN2ZyB4bWxucz0iaHR0..." />
 ```
+
 and in **Sass** this code:
 
 ```
 background-image: url('data:image/png;base64,$asset-image-logo');
 ```
+
 will be rendered as:
 
 ```
@@ -38,7 +40,7 @@ background-image: url('data:image/png;base64,PHN2ZyB4bWxucz0iaHR0...');
 
 #### What to look at
 
-Open the `config.json` file and see how all the "assets/embed/*" platform blocks are configured:
+Open the `config.json` file and see how all the "assets/embed/\*" platform blocks are configured:
 
 ```
     "assets/embed/json": {
@@ -54,7 +56,7 @@ Open the `config.json` file and see how all the "assets/embed/*" platform blocks
       ...
 ```
 
-Here there are **three specific transforms**: *attribute/cti* to assign the Category/Type/Item attributes to the tokens, *name/cti/kebab* to assign them the correct name, and finally *asset/base64* to take the path declared in the "value" of the tokens, convert the file at that path in base64 format, and assign the output of the base64 conversion to the "value" of the token.
+Here there are **three specific transforms**: _attribute/cti_ to assign the Category/Type/Item attributes to the tokens, _name/cti/kebab_ to assign them the correct name, and finally _asset/base64_ to take the path declared in the "value" of the tokens, convert the file at that path in base64 format, and assign the output of the base64 conversion to the "value" of the token.
 
 If you take for example the file `assets/icons.json` you will see this declaration:
 
@@ -64,6 +66,7 @@ If you take for example the file `assets/icons.json` you will see this declarati
       "alert-circle": { "value": "assets/icons/alert-circle.svg" }
 
 ```
+
 where the value of the `alert-circle` token is a path that points to the `alert-circle.svg` file in the `assets/icons/` folder.
 
 Now, `build` the dictionary and open the generated file `build/scss/assets_icons.scss`, and you will see this result:

package/examples/advanced/auto-rebuild-watcher/README.md

@@ -6,7 +6,7 @@ This is quite handy when there are continuous changes to the token values (e.g.
 
 #### Running the example
 
-First of all, set up the required dependencies running the command `npm install` in your local CLI environment (if you prefer to use *yarn*, update the commands accordingly).
+First of all, set up the required dependencies running the command `npm install` in your local CLI environment (if you prefer to use _yarn_, update the commands accordingly).
 
 At this point, if you want to build once the tokens you can run `npm run build`. This command will generate the files in the `build` folder.
 

package/examples/advanced/component-cti/README.md

@@ -5,7 +5,7 @@ This example will show you one way to define component tokens in a simple way wh
 ```json
 {
   "size": {
-    "padding" : {
+    "padding": {
       "button": { "value": "{size.padding.base.value}" }
     },
     "font": {
@@ -39,12 +39,12 @@ Instead, when defining component tokens it makes more sense to structure them mo
     "button": {
       "padding": { "value": "{size.padding.medium.value}" },
       "font-size": { "value": 2 },
-      
+
       "primary": {
         "background-color": { "value": "hsl(10, 80, 50)" },
         "color": { "value": "{color.font.inverse.value}" }
       },
-      
+
       "secondary": {
         "background-color": { "value": "{color.background.primary.value}" },
         "color": { "value": "{color.font.link.value}" }
@@ -56,14 +56,13 @@ Instead, when defining component tokens it makes more sense to structure them mo
 
 ### Running the example
 
-First of all, set up the required dependencies running the command `npm install` in your local CLI environment (if you prefer to use *yarn*, update the commands accordingly).
+First of all, set up the required dependencies running the command `npm install` in your local CLI environment (if you prefer to use _yarn_, update the commands accordingly).
 
 At this point, if you want to build the tokens run `npm run build`. This command will generate the files in the `build` folder.
 
-
 ### How does it work
 
-All of the built-in transforms target tokens using the CTI attributes. The built-in [`attribute/cti`](https://amzn.github.io/style-dictionary/#/transforms?id=attributecti) transform adds the CTI attributes to each token based on the object path of the token. In this example we override the default behavior of the [`attribute/cti`](https://amzn.github.io/style-dictionary/#/transforms?id=attributecti) transform to apply CTI attributes based on token's key, or last part of the object path to generate the equivalent category and type. This way we can correctly map a token with an object path of `component.button.background-color` to a category of `color` and type of `background`. 
+All of the built-in transforms target tokens using the CTI attributes. The built-in [`attribute/cti`](https://amzn.github.io/style-dictionary/#/transforms?id=attributecti) transform adds the CTI attributes to each token based on the object path of the token. In this example we override the default behavior of the [`attribute/cti`](https://amzn.github.io/style-dictionary/#/transforms?id=attributecti) transform to apply CTI attributes based on token's key, or last part of the object path to generate the equivalent category and type. This way we can correctly map a token with an object path of `component.button.background-color` to a category of `color` and type of `background`.
 
 Style Dictionary allows for extensibility through [monkey patching](https://en.wikipedia.org/wiki/Monkey_patch). This allows you to override the default behavior of the Style Dictionary library, and any built-in transforms and formats. You can override built-in transforms and formats by adding ones with the same name. Also, all of the built-in transforms, transformGroups, and formats are available by accessing them in the Style Dictionary library under the attributes `transform`, `transformGroup`, and `format` respectively. For example:
 
@@ -83,7 +82,7 @@ For example, if the key of the token (the last part of the object path) is "back
 
 ### What to look at
 
-* `config.js`:
-  * `propertiesToCTI`: A plain object where we map the CSS property name to the proper category and type.
-  * `CTITransform`: A transform object that defines a transformer method, which will override the default `attribute/cti` transform. This is similar to creating a child class with some custom logic and then calling `super`. In the transformer function it first looks at the top-level namespace, the first item in the object path, and if it is 'component' we run our custom logic using the `propertiesToCTI` map. If it is not 'component', use the built-in `attribute/cti`.
-* `tokens/component/button.json`: Take a look at how it defines the component tokens and uses the last part of the object path as the CSS property. Notice how we can define token values in here that are not references, but they still get transformed properly: font-size uses 'rem' and background-color uses hex in the output.
+- `config.js`:
+  - `propertiesToCTI`: A plain object where we map the CSS property name to the proper category and type.
+  - `CTITransform`: A transform object that defines a transformer method, which will override the default `attribute/cti` transform. This is similar to creating a child class with some custom logic and then calling `super`. In the transformer function it first looks at the top-level namespace, the first item in the object path, and if it is 'component' we run our custom logic using the `propertiesToCTI` map. If it is not 'component', use the built-in `attribute/cti`.
+- `tokens/component/button.json`: Take a look at how it defines the component tokens and uses the last part of the object path as the CSS property. Notice how we can define token values in here that are not references, but they still get transformed properly: font-size uses 'rem' and background-color uses hex in the output.