geoffp / theo

A set of Gulp plugins for transforming and formatting Design Tokens

Theo

Theo is a an abstraction for transforming and formatting Design Tokens.

Looking for the gulp plugin?

As of Theo v6, the gulp plugin is distributed as a separate package: gulp-theo.

Example

# buttons.yml
props:
  buttonBackground:
    value: "{!primaryColor}"
imports:
  - aliases.yml
global:
  type: token
  category: buttons

# aliases.yml
aliases:
  primaryColor:
    value: "#0070d2"

const theo = require('theo')

theo.convert({
  transform: {
    type: 'raw',
    file: 'buttons.yml'
  },
  format: {
    type: 'raw.json'
  }
})
.then(result => {
  const rawJSON = JSON.parse(result)
  console.log(rawJSON.props.buttonBackground.value) // '#0070d2'
  console.log(rawJSON.props.buttonBackground.category) // 'buttons'
  console.log(rawJSON.props.buttonBackground.type) // 'token'
})
.catch(error => console.log(`Something went wrong: ${error}`))

Design Tokens

Theo consumes Design Token files which are a central location to store design related information such as colors, fonts, widths, animations, etc. These raw values can then be transformed and formatted to meet the needs of any platform.

Let's say you have a web, native iOS, and native Android application that would like to share information such as background colors.

The web might like to consume the colors as hsla values formatted as Sass variables in an .scss file.

iOS might like rgba values formatted as .json.

Finally, Android might like 8 Digit Hex (AARRGGBB) values formatted as .xml.

Instead of hard coding this information in each platform/format, Theo can consume the centralized Design Tokens and output files for each platform.

Spec

A Design Token file is written in either JSON (JSON5 supported) or YAML and should conform to the following spec:

{
  // Required
  // A map of property names and value objects
  "props": {
    "color_brand": {
      // Required
      // Can be any valid JSON value
      "value": "#ff0000",

      // Required
      // Describe the type of value
      // [color|number|...]
      "type": "color",

      // Required
      // Describe the category of this property
      // Often used for style guide generation
      "category": "background",

      // Optional
      // This value will be included during transform
      // but excluded during formatting
      "meta": {
        // This value might be needed for some special transform
        "foo": "bar"
      }
    }
  },

  // Optional
  // This object will be merged into each property
  // Values defined on a property level will take precedence
  "global": {
    "category": "some-category",
    "meta": {
      "foo": "baz"
    }
  },

  // Optional
  // Share values across multiple props
  // Aliases are resolved like: {!sky}
  "aliases": {
    "sky": "blue",
    "grass": {
      "value": "green",
      "yourMetadata": "How grass looks"
    }
  },

  // Optional
  // Array of design token files to be imported
  // "aliases" will be imported as well
  // "aliases" will already be resolved
  // "global" will already be merged into each prop
  "imports": [
    "./some/dir/file.json"
  ]
}

Available Formats

json

{
  "PROP_NAME": "PROP_VALUE"
}

raw.json

{
  "props": {
    "PROP_NAME": {
      "value": "PROP_VALUE",
      "type": "PROP_TYPE",
      "category": "PROP_CATEGORY"
    }
  }
}

ios.json

{
  "properties": [
    {
      "name": "propName",
      "value": "PROP_VALUE",
      "type": "PROP_TYPE",
      "category": "PROP_CATEGORY"
    }
  ]
}

android.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <property name="PROP_NAME" type="PROP_TYPE" category="PROP_CATEGORY">PROP_VALUE</property>
  <color name="PROP_NAME" type="color" category="PROP_CATEGORY">PROP_VALUE</color>
</resources>

Note: PROP_NAME will be set to upper case

scss

// If prop has 'comment' key, that value will go here.
$prop-name: PROP_VALUE;

Note: $prop-name will be set to kebab-case.

map.scss

$file-name-map: (
  "prop-name": (PROP_VALUE),
);

Note: prop-name will be set to kebab-case.

map.variables.scss

$file-name-map-variables: (
  "prop-name": ($prop-name)
);

Note: prop-name will be set to kebab-case.

sass

$prop-name: PROP_VALUE

Note: $prop-name will be set to kebab-case.

less

@prop-name: PROP_VALUE;

Note: @prop-name will be set to kebab-case.

aura.tokens

<aura:tokens>
  <aura:token name="propName" value="PROP_VALUE" />
</aura:tokens>

common.js

module.exports = {
  propName: PROP_VALUE
};

amd.js

define(function() {
  return {
    propName: PROP_VALUE
  };
});