gulp-theo

Theo is a gulp plugin for transforming and formatting Design Tokens with Theo.

Install

npm install theo gulp-theo --save-dev

Usage

Here is a simple example with one file (props.yml) that gets transformed into its Sass (SCSS) equivalent:

# design/props.yml
global:
  category: 'web'
  type: 'color'
props:
  foo:
    value: '#ff0000'
  baz:
    value: '#0000ff'

// gulpfile.js
const gulp = require('gulp')
const theo = require('gulp-theo')
 
// Transform design/props.yml to dist/props.scss:
gulp.task('tokens:scss', () =>
  gulp.src('design/props.yml')
    .pipe(theo({
      transform: { type: 'web' },
      format: { type: 'scss' }
    }))
    .pipe(gulp.dest('dist'))
)

Running gulp run tokens:scss outputs:

// dist/props.scss 
$foo: rgb(255, 0, 0);
$baz: rgb(0, 0, 255);

Advanced Usage

In this example (available in the /example folder), gulp-theo generates multiple files, transformed using a custom format (array.js).

# tokens/_aliases.yml
aliases:
  red: 'rgb(255, 0, 0)'
  blue: 'rgb(0, 0, 255)'

# tokens/_colors.yml
global:
  category: 'web'
  type: 'color'
imports:
  - _aliases.yml
props:
  brand:
    value: '{!blue}'
    comment: 'ACME Inc. brand color.'
  primary:
    value: '{!red}'
    comment: 'Use the primary color on call-to-action buttons. e.g. "Save", "Log In"…'

# tokens/_mobile-overrides.yml
global:
  category: 'web'
  type: 'mobile'
props:
  large:
    value: '3rem'

# tokens/_sizes.yml
global:
  category: 'web'
  type: 'size'
imports:
  - _aliases.yml
props:
  medium:
    value: '1rem'
  large:
    value: '2rem'

# tokens/default.yml
imports:
  - _colors.yml
  - _sizes.yml

# tokens/mobile.yml
imports:
  - _colors.yml
  - _sizes.yml
  - _mobile-overrides.yml

// gulpfile.js
const gulp = require('gulp')
const gulpTheo = require('gulp-theo')
const theo = require('theo')
 
theo.registerFormat('array.js', `
  // Source: {{stem meta.file}}
  module.exports = [
    {{#each props as |prop|}}
      {{#if prop.comment}}// {{{prop.comment}}}{{/if}}
      ['{{camelcase prop.name}}', '{{prop.value}}'],
    {{/each}}
  ]
`)
 
gulp.task('tokens:array', () =>
  gulp.src([
    // Look for yml files
    'tokens/*.yml',
    // Exclude partials (files prefixed with _)
    '!tokens/_*'
  ])
  .pipe(gulpTheo(
    {
      transform: {
        type: 'web'
      },
      format: {
        type: 'array.js'
      }
    }
  ))
  .pipe(gulp.dest('dist'))
)
 

Running gulp tokens:array will output:

// dist/default.array.js
 
// Source: default
module.exports = [
  // ACME Inc. brand color.
  ['brand', 'rgb(0, 0, 255)'],
  // Use the primary color on call-to-action buttons. e.g. "Save", "Log In"…
  ['primary', 'rgb(255, 0, 0)'],
  ['medium', '1rem'],  
  ['large', '2rem'],
]

// dist/mobile.array.js
 
// Source: mobile
module.exports = [
  // ACME Inc. brand color.
  ['brand', 'rgb(0, 0, 255)'],
  // Use the primary color on call-to-action buttons. e.g. "Save", "Log In"…
  ['primary', 'rgb(255, 0, 0)'],
  ['medium', '1rem'],  
  ['large', '3rem'],
]

---

Another example is available at https://github.com/salesforce-ux/theo-example.

For any other options, refer to Theo’s documentation.