jrolfs / design-tokens

A place where OpenTable engineers and designers openly work together

design-tokens

Design Tokens repository is the central location to store shared design attributes such as colors, fonts, widths, animations, etc. These attributes can then be transformed and formatted to meet the needs of different projects, teams and platforms.

---

Table of Contents generated with DocToc

• Project structure
  • OTKit
  • OTTheme
• Usage
  • Install the token
  • Use the token
    • Example: using different formats
    • Example: set your base font size
  • Pixel to Rem conversion
• Development
  • Preview and debug
  • Publish
• Contribution

Project structure

A token is a set of design attributes bundled together around a common theme.

We have two sets of design tokens available to consume.

OTKit

Standard design tokens. Use them if you are following the new design guidelines.

Token	Available Formats	Version
otkit-borders	scss, cssmodules.css, common.js
otkit-breakpoints	scss, cssmodules.css, common.js
otkit-colors	scss, cssmodules.css, common.js
otkit-icons	scss, cssmodules.css
otkit-shadows	scss, cssmodules.css, common.js
otkit-spacing	scss, cssmodules.css, common.js
otkit-typography (DEPRECATED)	scss, cssmodules.css, common.js
otkit-typography-desktop	scss, cssmodules.css, common.js

OTTheme

Legacy design tokens. Use them if you need the classic look and feel of OpenTable Theme.

Token	Available Formats	Version
ottheme-colors	scss, cssmodules.css, common.js
ottheme-spacing	scss, cssmodules.css, common.js

Usage

Install the token

$ npm install --save-dev <token-name>

---

Use the token

A Token exposes multiple available formats (listed above). The format needs to be explicitly referenced upon requiring/importing the token:

require('<token-name>/token.<format>')

Example: using different formats

// cssmodules example:
@value color-primary from 'otkit-colors/token.cssmodules.css';

// common.js require/import examples:
const color = require('otkit-colors/token.common.js');
import color from 'otkit-colors/token.common.js';

// scss example:
@import '../node_modules/ottheme-colors/token.scss';

Example: set your base font size

@value font-size-base from 'otkit-typography/token.cssmodules.css';

html {
  font-size: font-size-base;
}

---

Pixel to Rem conversion

All contributions to this project should be in pixels. For users of these tokens, you will have to install postcss-pxtorem to handle the pixel to rem conversion in your CSS files.

npm install --save-dev postcss-pxtorem

Then add it to your postcss processors with the following recommended configuration:

import pxtorem from 'postcss-pxtorem';
import { fontSizeBase } from 'otkit-typography/token.cssmodules.css';

const processors = [
  pxtorem({
    // fontSizeBase = '16px'.  Need to convert to 16.
    rootValue: parseInt(fontSizeBase, 10),
    selectorBlackList: [/^html$/],
    replace: true
  })
];

Note that depending on how you use postcss, your processors array may be in a JSON configuration file instead.

If you're not already using postcss, you will either have to use it as an additional build step after you transform your CSS with your current tool or use it as a complete replacement for your current CSS transformation process.

Development

Preview and debug

Executing npm run build will generate the token values in each token's folder, such as token.scss or other available formats you specified.

When you publish a token (more on that below), this step is executed as part of the publishing.

If you are using a token in your project, you can execute npm link '<token-name>' in node_modules folder to test the token values before publishing.

---

Contribution

Please refer to the contributing doc