Next Phenomenal Microbrewery
    Have ideas to improve npm?Join in the discussion! »


    1.0.5 • Public • Published


    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

    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
      spreadsheetUrl: '',
      // 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
      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) =>
          transform: {
            type: transform,
            file: `${name}.json`,
          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}`);

    ⚠ 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/
    ✔ 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/
    ✔ Design tokens written to ./tokens/spacing.ios.json
    ✨  Done in 2.29s.

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


    npm i google-spreadsheets-theo

    DownloadsWeekly Downloads






    Unpacked Size

    17.6 kB

    Total Files


    Last publish


    • avatar