m5-docs/docs/quick_start.md

Quick Start

Installation

Note that you must have node (and npm) installed.

If you want to use the CLI, you can install it globally via npm:

$ npm install -g style-dictionary

!> Or you can install it like a normal npm dependency. This is a build tool so you are most likely going to want to save it as a dev dependency:

$ npm install -D style-dictionary

If you want to install it with yarn:

$ yarn add style-dictionary --dev

Creating a New Project

The CLI comes with some starter code to get a new project started easily.

$ mkdir MyStyleD
$ cd MyStyleD
$ style-dictionary init basic

This command will copy over the example files found in example in this repo and then run the style-dictionary build command to generate the build artifacts. You should see something like this output:

Reading config file from ./config.json
Building all platforms

scss
✔︎ build/scss/_variables.scss

android
✔︎ build/android/font_dimens.xml

ios
✔︎ build/ios/StyleDictionaryColor.h
✔︎ build/ios/StyleDictionaryColor.m

Pat yourself on the back, you just built your first style dictionary! Take a look at what you built. This should have created a build directory and it should look like this:

├── README.md
├── config.json
├── properties/
│   ├── color/
│       ├── base.json
│       ├── font.json
│   ├── size/
│       ├── font.json
│       ├── font.json
├── build/
│   ├── android/
│      ├── font_dimens.xml
│      ├── colors.xml
│   ├── scss/
│      ├── _variables.scss
│   ├── ios/
│      ├── StyleDictionaryColor.h
│      ├── StyleDictionaryColor.m

If you open config.json you will see there are 3 platforms defined: scss, android, ios. Each platform has a transformGroup, buildPath, and files defined. The buildPath and files of the platform should match up to the files what were built. Those files should look like these:

Android

<!-- 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_font_base">#ff111111</color>
  <color name="color_font_secondary">#ff999999</color>
  <color name="color_font_tertiary">#ffcccccc</color>
</resources>

SCSS

$color-base-gray-light: rgb(204, 204, 204);
$color-base-gray-medium: rgb(153, 153, 153);
$color-base-gray-dark: rgb(17, 17, 17);
$color-font-base: rgb(17, 17, 17);
$color-font-secondary: rgb(153, 153, 153);
$color-font-tertiary: rgb(204, 204, 204);
$size-font-small: 0.75rem;
$size-font-medium: 1rem;
$size-font-large: 2rem;
$size-font-base: 1rem;

iOS

@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.80f green:0.80f blue:0.80f alpha:1.0f],
[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.0f],
[UIColor colorWithRed:0.07f green:0.07f blue:0.07f alpha:1.0f],
[UIColor colorWithRed:0.07f green:0.07f blue:0.07f alpha:1.0f],
[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.0f],
[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.0f]
    ];
  });

  return colorArray;
}

@end

Pretty nifty! This shows a few things happening:

1. The build system does a deep merge of all the property JSON files defined in the source attribute of config.json. This allows you to split up the property JSON files however you want. There are 2 JSON files with color as the top level key, but they get merged properly.
2. The build system resolves references to other style properties. {size.font.medium.value} gets resolved properly
3. The build system handles references to property values in other files as well as you can see in properties/color/font.json
4. Values get transformed differently depending on the platform they are built to

Making a change

Now lets make a change and see how that affects things. Open up properties/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. Now

Android

<!-- 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">#ff000000</color>
  <color name="color_font_base">#ff111111</color>
  <color name="color_font_secondary">#ff999999</color>
  <color name="color_font_tertiary">#ffcccccc</color>
</resources>

$color-base-gray-light: rgb(204, 204, 204);
$color-base-gray-medium: rgb(153, 153, 153);
$color-base-gray-dark: rgb(0, 0, 0);
$color-font-base: rgb(0, 0, 0);
$color-font-secondary: rgb(153, 153, 153);
$color-font-tertiary: rgb(204, 204, 204);

[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.00f],
[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.00f],
[UIColor colorWithRed:0.00f green:0.00f blue:0.00f alpha:1.00f],
[UIColor colorWithRed:0.00f green:0.00f blue:0.00f alpha:1.00f],
[UIColor colorWithRed:0.60f green:0.60f blue:0.60f alpha:1.00f],
[UIColor colorWithRed:0.80f green:0.80f blue:0.80f alpha:1.00f]

That's it! There is a lot more you can do with your style dictionary than just generate some files with color values. Take a look at some examples or take a deeper dive into package structure, extending, or how the build process works.

Basic Usage

CLI

$ 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]	-h	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 the functionality or use it in another build system like Grunt or Gulp.

const StyleDictionary = require('style-dictionary').extend('config.json');

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.

const StyleDictionary = require('style-dictionary').extend({
  source: ['properties/**/*.json'],
  platforms: {
    scss: {
      transformGroup: 'scss',
      buildPath: 'build/',
      files: [{
        destination: 'variables.scss',
        format: 'scss/variables'
      }]
    }
    // ...
  }
});

StyleDictionary.buildAllPlatforms();