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.