Skip to content
master
Switch branches/tags
Go to file
Code

README.md

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

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 npm version
otkit-breakpoints scss, cssmodules.css, common.js npm version
otkit-colors scss, cssmodules.css, common.js npm version
otkit-grids scss, cssmodules.css, common.js npm version
otkit-icons scss, cssmodules.css, common.js npm version
otkit-shadows scss, cssmodules.css, common.js npm version
otkit-spacing scss, cssmodules.css, common.js npm version
otkit-typography (DEPRECATED) scss, cssmodules.css, common.js npm version
otkit-typography-desktop scss, cssmodules.css, common.js npm version

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 npm version
ottheme-spacing scss, cssmodules.css, common.js npm version

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;
}

otkit-icons token usages

The otkit-icons token offers two different sets of icons:

  • Standard icons with defined colors
  • Themeable icons using currentColor

They are available for SCSS, CSS Modules and CommonJS

Note: The themeable icons are only available in version 9.0.1 and above

Standard icons

This is the standard icons with predefined color for fill and stroke.

import { icTicket } from 'otkit-icons/token.common'

/*
<svg ...>
  <g id="icon/ic_ticket" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
    <path d="M12.7133596,8.1066091 ..." id="ic_ticket" fill="#2D333F"></path>
  </g>
</svg>/*

Themeable icons

This is the themeable icons where the icons colors will be inherited from the parent element/component. The fill and stroke have currentColor as their values.

import { icTicket } from 'otkit-icons/token.theme.common'

/*
<svg ...>
  <g id="icon/ic_ticket" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
    <path d="M12.7133596,8.1066091 ..." id="ic_ticket" fill="currentColor"></path>
  </g>
</svg>
*/

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