google-spreadsheets-theo

Import design tokens from a Google Spreadsheet to a format digestable by Theo.

Quick start

This example shows how to manage color tokens using Google Spreadsheets and Theo.

The end result is available in the ./example directory.

A ready-to-use demo project (more detailed and published to npm), is available at https://github.com/kaelig/google-spreadsheets-theo-demo.

1. Create a Google Spreadsheet to store the design tokens

Paste this table in a new Google spreadsheet, and populate it with the project or company’s design tokens:

name	value	type	category	comment
color-primary	red	color	background-color	Primary color for use on all main actions
color-secondary	#ff00ff	color	background-color
color-tertiary	green	color	background-color

It should look something like this example Google Spreadsheet.

2. Publish the spreadsheet to the web

google-spreadsheets-theo is only able to access the contents of the spreadsheet if it’s publicly published to the web.

1. In the File menu, select Publish to the web…
2. Click the Publish button (leave the default options)

3. Install Theo and google-spreadsheets-theo

Using yarn:

yarn add theo google-spreadsheets-theo --dev

Or, using npm:

npm install theo google-spreadsheets-theo --save-dev

4. Set up Theo and google-spreadsheets-theo

In a file called build-tokens.js, paste:

const fs = require('fs');
const path = require('path');
const theo = require('theo');
const googleSpreadsheetsTheo = require('google-spreadsheets-theo');
 
const config = {
  // URL of the spreadsheet
  // REPLACE WITH YOUR OWN
  spreadsheetUrl: 'https://docs.google.com/spreadsheets/d/xxx/edit#gid=0',
 
  // Each worksheet is for a different type of tokens (colors, spacing, typography…)
  worksheets: [
    {
      id: 1, // position of the worksheet (or "tab") in Google Spreadsheets
      name: 'colors',
    },
    // Example for adding spacing tokens:
    // {
    //   id: 2,
    //   name: 'spacing',
    // },
  ],
 
  // Output formats (see https://github.com/salesforce-ux/theo#formats)
  formats: [
    {
      transform: 'web',
      format: 'scss',
    },
    // Add formats below.
    // {
    //   transform: 'ios',
    //   format: 'ios.json',
    // },
  ],
 
  // Where the output files should be stored
  outputDirectory: './tokens/',
};
 
const convert = (name, transform, format, data) =>
  theo
    .convert({
      transform: {
        type: transform,
        file: `${name}.json`,
        data,
      },
      format: {
        type: format,
      },
    })
    .then((contents) => contents)
    .catch((error) => console.log(`Something went wrong: ${error}`));
 
const main = async (config) => {
  for ({id, name} of config.worksheets) {
    const data = await googleSpreadsheetsTheo(config.spreadsheetUrl, id);
 
    for ({transform, format} of config.formats) {
      const tokens = await convert(name, transform, format, data);
      const filename = `${config.outputDirectory}${name}.${format}`;
      await fs.promises
        .mkdir(path.dirname(filename), {recursive: true})
        .then(() => {
          fs.writeFileSync(filename, tokens);
        });
      console.log(`✔ Design tokens written to ${filename}`);
    }
  }
};
 
main(config);

⚠ Don’t forget to change the value of spreadsheetUrl in the config object.

5. Run the script

Add the script to the project’s package.json:

  // package.json
  "scripts": {
    // copy-paste this line:
    "build-tokens": "node ./build-tokens.js",
  },

In a terminal, run:

yarn build-tokens

Or, using npm:

npm run build-tokens

This should appear:

yarn build-tokens
yarn run v1.12.3
$ node ./build-tokens.js
✔ Design tokens written to ./tokens/colors.scss
✔ Design tokens written to ./tokens/colors.common.js
✔ Design tokens written to ./tokens/colors.android.xml
✔ Design tokens written to ./tokens/colors.ios.json
✔ Design tokens written to ./tokens/spacing.scss
✔ Design tokens written to ./tokens/spacing.common.js
✔ Design tokens written to ./tokens/spacing.android.xml
✔ Design tokens written to ./tokens/spacing.ios.json
✨  Done in 2.29s.

Voilà! Tokens should now be available in the ./tokens directory.