feat(examples): add custom filters example

examples/advanced/custom-filters/.gitignore

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

examples/advanced/custom-filters/README.md

@@ -0,0 +1,61 @@
+## Customize token output using filters
+
+This example shows how you can manage what tokens are generated and how they are organized. This is useful when you want to generate a 1:1 relationship between files and token categories.
+
+Common use cases include:
+
+- Each token category as its own Sass partial (_colors.scss)
+- Separate component files (button.css, input.css, etc)
+- Tree shaking (only import what you need)
+
+#### 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 processes the JSON files in the `properties` folder. The `index.js` file adds each folder, allowing you to map through them in `config.js`. The script goes through each folder and generates a file for each folder and populates it with tokens that match the filter.
+
+```sh
+# properties/color/base.json
+{
+   "color": {
+       "red": {
+            "value": "#FF0000"
+        }
+   }
+}
+```
+
+```sh
+# properties/size/base.json
+{
+   "size": {
+       "small": {
+            "value": "2px"
+        }
+   }
+}
+```
+
+Because the folder name matches the category, the output would automatically generate separate `color` and `size` files.
+
+#### What to look at
+
+Open the `config.json` file and see how the script first looks within the `properties` directory to map through each folder. The destination then outputs a file that would match the name, and fill that file with the tokens that match the filter criteria.
+
+```sh
+ files: properties.map(tokenCategory => ({
+          destination: `${tokenCategory}.js`,
+          format: "format/js",
+          filter: {
+            attributes: {
+              category: tokenCategory
+            }
+          }
+        }))
+```
+
+Now each new folder that gets added will automatically generate a corresponding file filled with tokens that match the category!

examples/advanced/custom-filters/config.js

@@ -0,0 +1,115 @@
+const StyleDictionary = require("style-dictionary");
+const tokens = require("./properties");
+
+module.exports = {
+  source: ["properties/**/*.json"],
+  platforms: {
+    "esm/category": {
+      transformGroup: "js",
+      buildPath: "build/js/esm/",
+      transforms: ["attribute/cti", "name/cti/camel", "size/px", "color/hex"],
+      files: tokens.map((tokenCategory) => ({
+        destination: `${tokenCategory}.js`,
+        format: "javascript/es6",
+        filter: {
+          attributes: {
+            category: tokenCategory,
+          },
+        },
+      })),
+    },
+    "esm/index": {
+      transformGroup: "js",
+      buildPath: "build/js/esm/",
+      transforms: ["attribute/cti", "name/cti/camel", "size/px", "color/hex"],
+      files: [
+        {
+          destination: `index.js`,
+          format: "javascript/es6",
+        },
+      ],
+    },
+    "cjs/category": {
+      transformGroup: "js",
+      buildPath: "build/js/cjs/",
+      transforms: ["attribute/cti", "name/cti/camel", "size/px", "color/hex"],
+      files: tokens.map((tokenCategory) => ({
+        destination: `${tokenCategory}.js`,
+        format: "custom/cjsmodule",
+        filter: {
+          attributes: {
+            category: tokenCategory,
+          },
+        },
+      })),
+    },
+    "cjs/index": {
+      transformGroup: "js",
+      buildPath: "build/js/cjs/",
+      transforms: ["attribute/cti", "name/cti/camel", "size/px", "color/hex"],
+      files: [
+        {
+          destination: `index.js`,
+          format: "custom/cjsmodule",
+        },
+      ],
+    },
+
+    // Web output in scss format
+    scss: {
+      transformGroup: "scss",
+      buildPath: `build/scss/`,
+      files: [
+        {
+          destination: `tokens.scss`,
+          format: "scss/variables",
+        },
+      ],
+    },
+    // Web output in scss partialformat
+    "scss/category": {
+      transformGroup: "scss",
+      buildPath: `build/scss/`,
+      files: tokens.map((tokenCategory) => ({
+        destination: `_${tokenCategory}.scss`,
+        format: "scss/variables",
+        filter: {
+          attributes: {
+            category: tokenCategory,
+          },
+        },
+      })),
+    },
+  },
+};
+
+StyleDictionary.registerTransform({
+  name: "size/pxToPt",
+  type: "value",
+  matcher: function (prop) {
+    return prop.value.match(/[\d.]+px/g);
+  },
+  transformer: function (prop) {
+    return prop.value.replace(/px/g, "pt");
+  },
+});
+
+StyleDictionary.registerTransform({
+  name: "size/pxToDp",
+  type: "value",
+  matcher: function (prop) {
+    return prop.value.match(/[\d.]+px/g);
+  },
+  transformer: function (prop) {
+    return prop.value.replace(/px/g, "dp");
+  },
+});
+
+StyleDictionary.registerFormat({
+  name: "custom/cjsmodule",
+  formatter: function (dictionary) {
+    return `module.exports = {${dictionary.allProperties.map(
+      (prop) => `\n\t${prop.name}: "${prop.value}"`
+    )}\n};`;
+  },
+});

examples/advanced/custom-filters/foundations.js

@@ -0,0 +1,5 @@
+/**
+ * Do not edit directly
+ * Generated on Sat, 07 Nov 2020 21:21:52 GMT
+ */
+