docs(example): add an example for tokens deprecation (#256)

examples/advanced/tokens-deprecation/.gitignore

@@ -0,0 +1,2 @@
+build/
+node_modules/

examples/advanced/tokens-deprecation/README.md

@@ -0,0 +1,23 @@
+## How to deprecate design tokens
+
+There are many ways in which one can decide to deprecate a design token. This example shows one of the possible ways, but please consider it as a suggestion and adapt it to your own specific needs.
+
+#### 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 run `npm run build`. This command will generate the files in the `build` folder.
+
+
+#### How does it work
+
+Using extra attributes associated to a design token, is possible (at build time) to read this extra meta-information and, using custom templates, generates output files that contain these extra information in the form of specific comments that inform the consumers of these files about the fact that some of the design tokens are to be considered deprecated.
+
+
+#### What to look at
+
+Open the `properties/color/base.json` and `properties/size/font.json` files and see how some of the properties have a custom `deprecated` attribute (and an additional `deprecated_comment` attribute).
+
+Now open the custom template files in `templates` and see how this attributes are used to - conditionally, when a property is deprecated - add extra comments to the output files.
+
+Finally, once generated the output files, open the `build/scss/_variables.scss` and `build/ios/tokens.plist` files and see how the `deprecated` attributes have been converted to comments (and extra properties in the plist) in the output files.

examples/advanced/tokens-deprecation/build.js

@@ -0,0 +1,24 @@
+const StyleDictionary = require('style-dictionary').extend(__dirname + '/config.json');
+const fs = require('fs');
+const _ = require('lodash');
+
+
+console.log('Build started...');
+console.log('\n==============================================');
+
+StyleDictionary.registerFormat({
+  name: 'custom/format/scss',
+  formatter: _.template(fs.readFileSync(__dirname + '/templates/web-scss.template'))
+});
+
+StyleDictionary.registerFormat({
+  name: 'custom/format/ios-plist',
+  formatter: _.template(fs.readFileSync(__dirname + '/templates/ios-plist.template'))
+});
+
+// FINALLY, BUILD ALL THE PLATFORMS
+StyleDictionary.buildAllPlatforms();
+
+
+console.log('\n==============================================');
+console.log('\nBuild completed!');

examples/advanced/tokens-deprecation/config.json

@@ -0,0 +1,21 @@
+{
+  "source": ["properties/**/*.json"],
+  "platforms": {
+    "scss": {
+      "transformGroup": "scss",
+      "buildPath": "build/scss/",
+      "files": [{
+        "destination": "_variables.scss",
+        "format": "custom/format/scss"
+      }]
+    },
+    "ios": {
+      "transformGroup": "ios",
+      "buildPath": "build/ios/",
+      "files": [{
+        "destination": "tokens.plist",
+        "format": "custom/format/ios-plist"
+      }]
+    }
+  }
+}

examples/advanced/tokens-deprecation/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "style-dictionary-tokens-deprecation",
+  "version": "1.0.0",
+  "description": "",
+  "main": "build/index.js",
+  "files": [
+    "build",
+    "properties"
+  ],
+  "scripts": {
+    "build": "node ./build.js",
+    "clean": "rm -rf build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "lodash": "^4.17.11",
+    "style-dictionary": "2.6.2"
+  }
+}

examples/advanced/tokens-deprecation/properties/color/base.json

@@ -0,0 +1,22 @@
+{
+  "color": {
+    "base": {
+      "gray": {
+        "light" : { "value": "#CCCCCC" },
+        "medium": { "value": "#999999" },
+        "dark"  : { "value": "#111111" }
+      },
+      "red": {
+        "value": "#FF0000",
+        "deprecated": true,
+        "deprecated_comment": "replace with the \"blue\" color"
+      },
+      "green": {
+        "value": "#00FF00"
+      },
+      "blue": {
+        "value": "#0000FF"
+      }
+    }
+  }
+}

examples/advanced/tokens-deprecation/properties/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}" }
+    }
+  }
+}

examples/advanced/tokens-deprecation/properties/size/font.json

@@ -0,0 +1,24 @@
+{
+  "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",
+        "deprecated": true,
+        "deprecated_comment": "replace with the \"medium\" size"
+      },
+      "base"  : {
+        "value": "{size.font.medium.value}",
+        "comment": "the base size of the font"
+      }
+    }
+  }
+}

examples/advanced/tokens-deprecation/templates/ios-plist.template

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+
+<% _.each(allProperties, function(prop) {
+    // NOTICE: this is a simplified version of a PLIST file for iOS
+    // please refer to the documentation for a proper format
+    // or speak with one of your iOS developers to agree on a format that works for them
+    var output = "";
+    output += "\t<key>" + prop.name + "</key>\n";
+    output += "\t<dict>\n";
+    output += "\t\t<key>value</key><string>" + prop.value + "</string>";
+    if(prop.comment) {
+    output += " <!-- " + prop.comment + " -->";
+    }
+    output += "\n";
+    if(prop.deprecated) {
+    output += "\t\t<key>deprecated</key><true/>";
+        if(prop.deprecated_comment) {
+            output += " <!-- " + prop.deprecated_comment + " -->";
+        }
+    output += "\n";
+    }
+    output += "\t</dict>\n\n";
+    print(output);
+}); %>
+
+</dict>
+</plist>

examples/advanced/tokens-deprecation/templates/web-scss.template

@@ -0,0 +1,16 @@
+<% _.each(allProperties, function(prop) {
+    var output = "";
+    if(prop.deprecated) {
+    output += "// Notice: the following value is deprecated";
+        if(prop.deprecated_comment) {
+        output += " (" + prop.deprecated_comment + ")";
+        }
+    output += "\n";
+    }
+    output += "$" + prop.name + ": " + prop.value + ";";
+    if(prop.comment) {
+    output += " // " + prop.comment;
+    }
+    output += "\n";
+    print(output);
+}); %>