style-dictionary 3.7.1 → 3.7.2

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/transitive-transforms/tokens/saturation.json5

@@ -0,0 +1,18 @@
+{
+  // Because these are not like a token object with a 'value' attribute,
+  // Style Dictionary won't consider them tokens and therefore won't output them.
+  // But, you can still access/reference them in tokens using the same reference
+  // syntax: "value": "{lightness.0}"
+  // This can be used when defining colors as HSL:
+  // "value": {"h": "{hue.red}", "l": "{lightness.0}", "s": "{saturation.0}"}
+  saturation: [
+    100,
+    90,
+    85,
+    80,
+    75,
+    70,
+    65,
+    50
+  ]
+}

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/variables-in-outputs/README.md

@@ -0,0 +1,53 @@
+## Use variables in output files
+
+This example shows how you keep aliases/references intact in certain types of formats as well as in custom formats.
+
+Common use cases include:
+
+- Vending theme-able output like CSS variables
+
+#### 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).
+
+At this point, you can run `npm run build`. This command will generate the output file in the `build` folder.
+
+#### How does it work
+
+The "build" command uses the `sd.config.js` file as the Style Dictionary configuration. It is configured to use JSON files in the `tokens/` directory as the source files. It adds a custom format directly in the configuration (as opposed to using the `.registerFormat()` method) that uses 2 new methods added onto the internal dictionary object that is passed to formats and actions: `.usesReference()` and `.resolveReference()`. Also, it uses a new configuration on some formats: `keepReferences: true` to include variable references in the output.
+
+
+#### What to look at
+
+The `sd.config.js` file has everything you need to see. The tokens included in this example are just enough to show these new techniques.
+
+Here is an example that shows how to get an alias's name within a custom format:
+```javascript
+//...
+function({ dictionary }) {
+  return dictionary.allTokens.map(token => {
+    let value = JSON.stringify(token.value);
+    // the `dictionary` object now has `usesReference()` and
+    // `getReferences()` methods. `usesReference()` will return true if
+    // the value has a reference in it. `getReferences()` will return 
+    // an array of references to the whole tokens so that you can access their
+    // names or any other attributes.
+    if (dictionary.usesReference(token.original.value)) {
+      const refs = dictionary.getReferences(token.original.value);
+      refs.forEach(ref => {
+        value = value.replace(ref.value, function() {
+          return `${ref.name}`;
+        });
+      });
+    }
+    return `export const ${token.name} = ${value};`
+  }).join(`\n`)
+}
+```
+
+The `build/` directory is where all the files are being built to. After Style Dictionary is run, take a look at the files it generates:
+
+* `build/tokens.js` This file is generated from the custom format in this example. Tokens that are references to other tokens use the variable name instead of raw value.
+* `build/tokens.json` This file does not use variable references to show that other outputs work as intended.
+* `build/tokens.css` This file is generated using the `css/variables` built-in format with the new `keepReferences` configuration.
+* `build/tokens.scss` This file is generated using the `scss/variables` built-in format with the new `keepReferences` configuration.

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/variables-in-outputs/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "style-dictionary-example-variables-in-outputs",
+  "version": "1.0.0",
+  "description": "",
+  "main": "sd.config.js",
+  "scripts": {
+    "build": "style-dictionary build --config ./sd.config.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "style-dictionary": "3.7.1"
+  }
+}

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/variables-in-outputs/sd.config.js

@@ -0,0 +1,67 @@
+module.exports = {
+  format: {
+    // Adding a custom format to show how to get an alias's name.
+    customFormat: function({dictionary, options}) {
+      return dictionary.allTokens.map(token => {
+        let value = JSON.stringify(token.value);
+        // new option added to decide whether or not to output references
+        if (options.outputReferences) {
+          // the `dictionary` object now has `usesReference()` and
+          // `getReferences()` methods. `usesReference()` will return true if
+          // the value has a reference in it. `getReferences()` will return
+          // an array of references to the whole tokens so that you can access
+          // their names or any other attributes.
+          if (dictionary.usesReference(token.original.value)) {
+            const refs = dictionary.getReferences(token.original.value);
+            refs.forEach(ref => {
+              value = value.replace(ref.value, function() {
+                return `${ref.name}`;
+              });
+            });
+          }
+        }
+
+        return `export const ${token.name} = ${value};`
+      }).join(`\n`)
+    }
+  },
+
+  source: ['tokens/**/*.json'],
+  platforms: {
+    json: {
+      buildPath: 'build/',
+      files: [{
+        destination: 'tokens.json',
+        format: 'json/nested'
+      }]
+    },
+    js: {
+      buildPath: 'build/',
+      transformGroup: 'js',
+      files: [{
+        destination: 'tokens.js',
+        format: 'customFormat',
+        options: {
+          outputReferences: true
+        }
+      }]
+    },
+    css: {
+      transformGroup: 'css',
+      buildPath: 'build/',
+      files: [{
+        destination: 'tokens.css',
+        format: 'css/variables',
+        options: {
+          outputReferences: true, // new setting, if true will use variable references
+        }
+      },{
+        destination: 'tokens.scss',
+        format: 'scss/variables',
+        options: {
+          outputReferences: true, // new setting, if true will use variable references
+        }
+      }]
+    }
+  }
+};

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/variables-in-outputs/tokens/color/background.json

@@ -0,0 +1,10 @@
+{
+  "color": {
+    "background": {
+      "primary": { "value": "{color.palette.neutral.0.value}" },
+      "secondary": { "value": "{color.palette.neutral.5.value}" },
+      "tertiary": { "value": "{color.palette.neutral.10.value}" },
+      "base": { "value": "{color.background.primary.value}" }
+    }
+  }
+}

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/variables-in-outputs/tokens/color/palette.json

@@ -0,0 +1,17 @@
+{
+  "color" : {
+    "palette" : {
+      "neutral": {
+        "140" : { "value" : "#192026" },
+        "100" : { "value" : "#303942" },
+        "80"  : { "value" : "#63676B" },
+        "60"  : { "value" : "#8C8F92" },
+        "40"  : { "value" : "#ADB0B3" },
+        "20"  : { "value" : "#D1D2D3" },
+        "10"  : { "value" : "#EAEBEC" },
+        "5"   : { "value" : "#F2F4F5" },
+        "0"   : { "value" : "#FFFFFF" }
+      }
+    }
+  }
+}

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/yaml-tokens/README.md

@@ -0,0 +1,18 @@
+## Yaml Tokens
+
+This example shows how to use a custom parser to define yaml token files.
+
+#### 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).
+
+At this point, if you want to build the tokens you can run `npm run build`. This command will run the Style Dictionary CLI with the **sd.config.js** as the configuration file and will generate the files in the `build` folder.
+
+#### How does it work?
+
+Style Dictionary added the ability to use custom parsers for token files in the 3.0 release. A custom parser has a regular expression pattern to match against source filenames. The parse function is then run taking the text content of the file and returning an object. A custom parser is like a module rule in a webpack configuration.
+
+#### What to look at
+
+The [`sd.config.js`](sd.config.js) file is the first thing to look at. It has a lot of comments how everything works. It shows how you can add a custom parser and set it to the yaml parser. You can also look in the [`tokens/`](tokens/) directory to see a yaml token file. 
+

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/yaml-tokens/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "style-dictionary-example-yaml-tokens",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "build": "style-dictionary build --config ./sd.config.js"
+  },
+  "author": "",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "style-dictionary": "3.7.1",
+    "yaml": "^1.10.0"
+  }
+}

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/yaml-tokens/sd.config.js

@@ -0,0 +1,26 @@
+const yaml = require('yaml');
+
+module.exports = {
+  parsers: [{
+    // A custom parser will only run against filenames that match the pattern
+    // This pattern will match any file with the .yaml extension.
+    // This allows you to mix different types of files in your token source
+    pattern: /\.yaml$/,
+    // the parse function takes a single argument, which is an object with
+    // 2 attributes: contents which is a string of the file contents, and
+    // filePath which is the path of the file.
+    // The function is expected to return a plain object.
+    parse: ({contents, filePath}) => yaml.parse(contents)
+  }],
+  source: [`tokens/**/*.yaml`],
+  platforms: {
+    css: {
+      transformGroup: 'css',
+      buildPath: 'build/',
+      files: [{
+        destination: 'variables.css',
+        format: 'css/variables'
+      }]
+    }
+  }
+}

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/advanced/yaml-tokens/tokens/color/core.yaml

@@ -0,0 +1,13 @@
+color:
+  base:
+    white:
+      value: "#fff"
+    red:
+      value:
+        r: 255
+        g: 0
+        b: 0
+    green:
+      value: "rgb(0,255,0)"
+    success:
+      value: "{color.base.green.value}"

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/basic/README.md

@@ -0,0 +1,181 @@
+# Basic Style Dictionary
+
+This example code is bare-bones to show you what this framework can do. If you have the style-dictionary module installed globally, you can `cd` into this directory and run:
+```bash
+style-dictionary build
+```
+
+You should see something like this output:
+```
+Copying starter files...
+
+Source style dictionary starter files created!
+
+Running `style-dictionary build` for the first time to generate build artifacts.
+
+
+scss
+✔︎  build/scss/_variables.scss
+
+android
+✔︎  build/android/font_dimens.xml
+✔︎  build/android/colors.xml
+
+compose
+✔︎ build/compose/StyleDictionaryColor.kt
+✔︎ build/compose/StyleDictionarySize.kt
+
+ios
+✔︎  build/ios/StyleDictionaryColor.h
+✔︎  build/ios/StyleDictionaryColor.m
+✔︎  build/ios/StyleDictionarySize.h
+✔︎  build/ios/StyleDictionarySize.m
+
+ios-swift
+✔︎  build/ios-swift/StyleDictionary.swift
+
+ios-swift-separate-enums
+✔︎  build/ios-swift/StyleDictionaryColor.swift
+✔︎  build/ios-swift/StyleDictionarySize.swift
+```
+
+Good for you! You have now built your first style dictionary! Moving on, take a look at what we have built. This should have created a build directory and it should look like this:
+```
+├── README.md
+├── config.json
+├── tokens/
+│   ├── color/
+│       ├── base.json
+│       ├── font.json
+│   ├── size/
+│       ├── font.json
+├── build/
+│   ├── android/
+│      ├── font_dimens.xml
+│      ├── colors.xml
+│   ├── compose/
+│      ├── StyleDictionaryColor.kt
+│      ├── StyleDictionarySize.kt
+│   ├── scss/
+│      ├── _variables.scss
+│   ├── ios/
+│      ├── StyleDictionaryColor.h
+│      ├── StyleDictionaryColor.m
+│      ├── StyleDictionarySize.h
+│      ├── StyleDictionarySize.m
+│   ├── ios-swift/
+│      ├── StyleDictionary.swift
+│      ├── StyleDictionaryColor.swift
+│      ├── StyleDictionarySize.swift
+```
+
+If you open `config.json` you will see there are 5 platforms defined: scss, android, compose, ios, and ios-swift. Each platform has a transformGroup, buildPath, and files. The buildPath and files of the platform should match up to the files what were built. The files built should look like these:
+
+**Android**
+```xml
+<!-- font_dimens.xml -->
+<resources>
+  <dimen name="size_font_small">12.00sp</dimen>
+  <dimen name="size_font_medium">16.00sp</dimen>
+  <dimen name="size_font_large">32.00sp</dimen>
+  <dimen name="size_font_base">16.00sp</dimen>
+</resources>
+
+<!-- colors.xml -->
+<resources>
+  <color name="color_base_gray_light">#ffcccccc</color>
+  <color name="color_base_gray_medium">#ff999999</color>
+  <color name="color_base_gray_dark">#ff111111</color>
+  <color name="color_base_red">#ffff0000</color>
+  <color name="color_base_green">#ff00ff00</color>
+  <color name="color_font_base">#ffff0000</color>
+  <color name="color_font_secondary">#ff00ff00</color>
+  <color name="color_font_tertiary">#ffcccccc</color>
+</resources>
+```
+
+**Compose**
+```kotlin
+object StyleDictionaryColor {
+  val colorBaseGrayDark = Color(0xff111111)
+  val colorBaseGrayLight = Color(0xffcccccc)
+  val colorBaseGrayMedium = Color(0xff999999)
+  val colorBaseGreen = Color(0xff00ff00)
+  val colorBaseRed = Color(0xffff0000)
+  val colorFontBase = Color(0xffff0000)
+  val colorFontSecondary = Color(0xff00ff00)
+  val colorFontTertiary = Color(0xffcccccc)
+}
+
+object StyleDictionarySize {
+  /** the base size of the font */
+  val sizeFontBase = 16.00.sp
+  /** the large size of the font */
+  val sizeFontLarge = 32.00.sp
+  /** the medium size of the font */
+  val sizeFontMedium = 16.00.sp
+  /** the small size of the font */
+  val sizeFontSmall = 12.00.sp
+}
+```
+
+**SCSS**
+```scss
+// variables.scss
+$color-base-gray-light: #cccccc;
+$color-base-gray-medium: #999999;
+$color-base-gray-dark: #111111;
+$color-base-red: #ff0000;
+$color-base-green: #00ff00;
+$color-font-base: #ff0000;
+$color-font-secondary: #00ff00;
+$color-font-tertiary: #cccccc;
+$size-font-small: 0.75rem;
+$size-font-medium: 1rem;
+$size-font-large: 2rem;
+$size-font-base: 1rem;
+```
+
+**iOS**
+```objc
+#import "StyleDictionaryColor.h"
+
+@implementation StyleDictionaryColor
+
++ (UIColor *)color:(StyleDictionaryColorName)colorEnum{
+  return [[self values] objectAtIndex:colorEnum];
+}
+
++ (NSArray *)values {
+  static NSArray* colorArray;
+  static dispatch_once_t onceToken;
+
+  dispatch_once(&onceToken, ^{
+    colorArray = @[
+[UIColor colorWithRed:0.800f green:0.800f blue:0.800f alpha:1.000f],
+[UIColor colorWithRed:0.600f green:0.600f blue:0.600f alpha:1.000f],
+[UIColor colorWithRed:0.067f green:0.067f blue:0.067f alpha:1.000f],
+[UIColor colorWithRed:1.000f green:0.000f blue:0.000f alpha:1.000f],
+[UIColor colorWithRed:0.000f green:1.000f blue:0.000f alpha:1.000f],
+[UIColor colorWithRed:1.000f green:0.000f blue:0.000f alpha:1.000f],
+[UIColor colorWithRed:0.000f green:1.000f blue:0.000f alpha:1.000f],
+[UIColor colorWithRed:0.800f green:0.800f blue:0.800f alpha:1.000f]
+    ];
+  });
+
+  return colorArray;
+}
+
+@end
+```
+
+Pretty nifty! This shows a few things happening:
+1. The build system does a deep merge of all the token JSON files defined in the `source` attribute of `config.json`. This allows you to split up the token JSON files however you want. There are 2 JSON files with `color` as the top level key, but they get merged properly.
+1. The build system resolves references to other design tokens. `{size.font.medium.value}` gets resolved properly.
+1. The build system handles references to token values in other files as well as you can see in `tokens/color/font.json`.
+
+Now let's make a change and see how that affects things. Open up `tokens/color/base.json` and change `"#111111"` to `"#000000"`. After you make that change, save the file and re-run the build command `style-dictionary build`. Open up the build files and take a look.
+
+**Huzzah!**
+
+Now go forth and create! Take a look at all the built-in [transforms](https://amzn.github.io/style-dictionary/#/transforms?id=pre-defined-transforms) and [formats](https://amzn.github.io/style-dictionary/#/formats?id=pre-defined-formats).

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/basic/config.json

@@ -0,0 +1,143 @@
+{
+  "source": ["tokens/**/*.json"],
+  "platforms": {
+    "scss": {
+      "transformGroup": "scss",
+      "buildPath": "build/scss/",
+      "files": [{
+        "destination": "_variables.scss",
+        "format": "scss/variables"
+      }]
+    },
+    "android": {
+      "transformGroup": "android",
+      "buildPath": "build/android/",
+      "files": [{
+        "destination": "font_dimens.xml",
+        "format": "android/fontDimens"
+      },{
+        "destination": "colors.xml",
+        "format": "android/colors"
+      }]
+    },
+    "compose": {
+      "transformGroup": "compose",
+      "buildPath": "build/compose/",
+      "files": [{
+        "destination": "StyleDictionaryColor.kt",
+        "format": "compose/object",
+        "className": "StyleDictionaryColor",
+        "packageName": "StyleDictionaryColor",
+        "filter": {
+          "attributes": {
+            "category": "color"
+          }
+        }
+      },{
+        "destination": "StyleDictionarySize.kt",
+        "format": "compose/object",
+        "className": "StyleDictionarySize",
+        "packageName": "StyleDictionarySize",
+        "type": "float",
+        "filter": {
+          "attributes": {
+            "category": "size"
+          }
+        }
+      }]
+    },
+    "ios": {
+      "transformGroup": "ios",
+      "buildPath": "build/ios/",
+      "files": [{
+        "destination": "StyleDictionaryColor.h",
+        "format": "ios/colors.h",
+        "className": "StyleDictionaryColor",
+        "type": "StyleDictionaryColorName",
+        "filter": {
+          "attributes": {
+            "category": "color"
+          }
+        }
+      },{
+        "destination": "StyleDictionaryColor.m",
+        "format": "ios/colors.m",
+        "className": "StyleDictionaryColor",
+        "type": "StyleDictionaryColorName",
+        "filter": {
+          "attributes": {
+            "category": "color"
+          }
+        }
+      },{
+        "destination": "StyleDictionarySize.h",
+        "format": "ios/static.h",
+        "className": "StyleDictionarySize",
+        "type": "float",
+        "filter": {
+          "attributes": {
+            "category": "size"
+          }
+        }
+      },{
+        "destination": "StyleDictionarySize.m",
+        "format": "ios/static.m",
+        "className": "StyleDictionarySize",
+        "type": "float",
+        "filter": {
+          "attributes": {
+            "category": "size"
+          }
+        }
+      }]
+    },
+    "ios-swift": {
+      "transformGroup": "ios-swift",
+      "buildPath": "build/ios-swift/",
+      "files": [{
+        "destination": "StyleDictionary+Class.swift",
+        "format": "ios-swift/class.swift",
+        "className": "StyleDictionaryClass",
+        "filter": {}
+      },{
+        "destination": "StyleDictionary+Enum.swift",
+        "format": "ios-swift/enum.swift",
+        "className": "StyleDictionaryEnum",
+        "filter": {}
+      },{
+        "destination": "StyleDictionary+Struct.swift",
+        "format": "ios-swift/any.swift",
+        "className": "StyleDictionaryStruct",
+        "filter": {},
+        "options": {
+          "imports": "SwiftUI",
+          "objectType": "struct",
+          "accessControl": "internal"
+        }
+      }]
+    },
+    "ios-swift-separate-enums": {
+      "transformGroup": "ios-swift-separate",
+      "buildPath": "build/ios-swift/",
+      "files": [{
+        "destination": "StyleDictionaryColor.swift",
+        "format": "ios-swift/enum.swift",
+        "className": "StyleDictionaryColor",
+        "filter": {
+          "attributes": {
+            "category": "color"
+          }
+        }
+      },{
+        "destination": "StyleDictionarySize.swift",
+        "format": "ios-swift/enum.swift",
+        "className": "StyleDictionarySize",
+        "filter": {
+          "attributes": {
+            "category": "size"
+          }
+        }
+      }]
+    }
+  }
+}

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/basic/tokens/color/base.json

@@ -0,0 +1,13 @@
+{
+  "color": {
+    "base": {
+      "gray": {
+        "light" : { "value": "#CCCCCC" },
+        "medium": { "value": "#999999" },
+        "dark"  : { "value": "#111111" }
+      },
+      "red": { "value": "#FF0000" },
+      "green": { "value": "#00FF00" }
+    }
+  }
+}

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/basic/tokens/color/font.json

@@ -0,0 +1,9 @@
+{
+  "color": {
+    "font": {
+      "base"     : { "value": "{color.base.red.value}" },
+      "secondary": { "value": "{color.base.green.value}" },
+      "tertiary" : { "value": "{color.base.gray.light.value}" }
+    }
+  }
+}

package/examples/advanced/custom-file-header/node_modules/style-dictionary/examples/basic/tokens/size/font.json

@@ -0,0 +1,22 @@
+{
+  "size": {
+    "font": {
+      "small" : {
+        "value": "0.75",
+        "comment": "the small size of the font"
+      },
+      "medium": {
+        "value": "1",
+        "comment": "the medium size of the font"
+      },
+      "large" : {
+        "value": "2",
+        "comment": "the large size of the font"
+      },
+      "base"  : {
+        "value": "{size.font.medium.value}",
+        "comment": "the base size of the font"
+      }
+    }
+  }
+}