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.
- In the File menu, select Publish to the web…
- 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);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
✨ Done in 2.29s.
Voilà! Tokens should now be available in the ./tokens directory.