vcc-ui-design-tokens

Multi Brand & Multi Platform

While it's pretty standard to use a common set of properties to generate the same design tokens for different platforms (only in different format), this example shows how to setup a multi-brand, multi-platform suite of design tokens, with values that may depend on the brand (eg. a brand color) or the platform (eg. a font family).

In this specific case it's necessary to use a custom build script to process the properties for each one of the possible brand/platform combinations. In the script the configuration used by Style Dictionary becomes parametric, with "brand" and "platform" used as arguments of a function that returns the "config" object used to extend Style Dictionary.

The properties are organised in specific folders, depending if they are "platform" dependent, "brand" dependent or "global" (independent of platform or brand). The organisation of the files used in this example is not strictly required, but has the advantage that it's easier to see what the properties depend on, and it's easier to use global paths to include the correct files for a specific combination of "brand" and "platform" (see the "source" declaration block in the getStyleDictionaryConfig function of the build script).

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 generate the files in the build folder. Unlike other examples, the files are organised not only by "platform", but also organised in "brand" sub-folders.

How does it work

The "build" command will run the custom script build.js. This script loops on all the possible combinations of "platform" (web, iOS, Android) and "brand" ("brand-1", "brand-2" and "brand-3" in the example):

['brand-1', 'brand-2', 'brand-3'].map(function (brand) {
  ['web', 'ios', 'android'].map(function (platform) {
    const StyleDictionary = StyleDictionaryPackage.extend(getStyleDictionaryConfig(brand, platform));
    StyleDictionary.buildPlatform(platform);
  })
})

For each combination it receives a parametric configuration object from the getStyleDictionaryConfig function, where the input property files to read and the output paths where to write the generaed files depend on the "platform" and "brand" values:

function getStyleDictionaryConfig(brand, platform) {
  return {
    "source": [
      `properties/brands/${brand}/*.json`,
      "properties/globals/**/*.json",
      `properties/platforms/${platform}/*.json`
    ],
    "platforms": {
      "web": {
        "transformGroup": "web",
        "buildPath": `build/web/${brand}/`,
        "files": [{
          "destination": "tokens.scss",
          "format": "scss/variables"
        }]
      },
      ...
    }
  };
}

The properties are stored in three different folders:

• brands: this folder contain properties that depend on the "brand", eg. the "primary" and "secondary" colors (generally these are called "brand colors", think of the blue of Facebook, the orange of Amazon, or the red of Gmail).
• platforms: this folder contain properties that depend on the "platform", eg. the font family used in the application or website (eg. a font stack like "Tahoma, Arial, 'Helvetica Neue', sans" on web, "San Francisco" in iOS, "Roboto" in Android).
• global: this folder contain properties that are common, that don't depend on the specific "platform" or "brand", eg. the base grayscale colors, the font sizes, etc.

Leveraging the ability of Style Dictionary to reference other properties values as "aliases", we can have generic properties like font.family.base or color.primary whose values actually depend on the "platform" and "brand" and whose values are computed dynamically at build time depending on the specific "platform/brand" files, included dynamically by the getStyleDictionaryConfig function.

What to look at

Open the build.js script and look how the StyleDictionary.buildPlatform function is called multiple times, looping on the combination of platform and brand, and how the configuration object is returned by the getStyleDictionaryConfig function.

Now look at the properties folders, and see how they are organised. Open properties/brands/brand-1/color.json. You will see this declaration:

{
  "color": {
    "brand": {
      "primary"   : { "value": "#3B5998" },
      "secondary" : { "value": "#4267B2" }
    }
  }
}

The actual values depend on the "brand" (compare this file with brand-2/color.json and brand-3/color.json. These values are used as "aliases" in the properties/global/color/base.json file:

{
  "color": {
    "base": {
      ...
    },
    "primary"     : { "value": "{color.brand.primary.value}" },
    "secondary"   : { "value": "{color.brand.secondary.value}" },
    ...
  }
}

Depending on the file included at build time, the actual value of color.primary will depend on the "brand". To see how this works out, open the file build/web/brand-1/tokens.scss and compare it with the similar files for "brand-2" and "brand-3": you will see how the values for color.primary, color.action.primary are different for different brands, and how they are actually the values declared in the "brands" source folders.

In the same way, now open properties/platforms/android/font.json and you will see:

{
  "font": {
    "platform": {
      "system": { "value": "Roboto" }
    }
  }
}

the value font.platform.system is consumed by the properties/globals/font/index.json file:

{
  "font": {
    "family": {
      "headers" : { "value": "Montserrat" },
      "base"    : { "value": "{font.platform.system.value}" }
    }
  }
}

In this way the design tokens for the different platforms will be:

// WEB
$font-family-headers: Montserrat;
$font-family-base: Tahoma, Arial, 'Helvetica Neue', sans;

// IOS
#define FontFamilyHeaders @"Montserrat"
#define FontFamilyBase @"San Francisco"

// ANDROID
// TODO - here you would see that the font-family-base is "Roboto"