Polaris design tokens

Colors, spacing, typography for all platforms

JavaScript · JSON · CSS · SCSS · Android · Sketch · macOS · Adobe Swatch

[![CircleCI](https://circleci.com/gh/Shopify/polaris-tokens.svg?style=shield)](https://circleci.com/gh/Shopify/polaris-tokens) [![npm version](https://img.shields.io/npm/v/@shopify/polaris-tokens.svg)](https://www.npmjs.com/package/@shopify/polaris-tokens) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)

Design tokens for Polaris, Shopify’s design system.

Design tokens originated at Salesforce, and the best way to describe them is to simply quote their documentation:

Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development – Salesforce UX

Installation

Polaris design tokens are available as both a npm package (@shopify/polaris-tokens) on npm, and as a Ruby gem (polaris_tokens) on RubyGems.

The recommended way to use and install design tokens may vary depending on your project; the most common are documented below.

JavaScript package installation

Using npm:

npm install @shopify/polaris-tokens --save

Using yarn:

yarn add @shopify/polaris-tokens

Ruby on Rails installation

Add polaris_tokens to your Gemfile:

$ echo "gem 'polaris_tokens'" >> Gemfile
$ bundle install

Usage

Find all available tokens in the design tokens documentation.

JavaScript

In JavaScript, design token names are formatted in lower camelCase.

const tokens = require('@shopify/polaris-tokens');
console.log(tokens.colorBlueLighter); // rgb(235, 245, 250)

In JSON, design token names are formatted in kebab-case.

const tokens = require('@shopify/polaris-tokens/dist/index.json');
console.log(tokens['color-blue-lighter']); // rgb(235, 245, 250)

Sass

Sass variables and map keys are formatted in kebab-case.

// Using variables
@import '~@shopify/polaris-tokens/dist/index';

a {
  color: $color-blue-text;
}

// Using the map of all tokens
@import '~@shopify/polaris-tokens/dist/index.map';

a {
  color: map-get($polaris-index-map, 'color-blue-text');
}

// Using the map for a specific type of tokens (here: spacing)
@import '~@shopify/polaris-tokens/dist/spacing.map';

a {
  color: map-get($polaris-spacing-map, 'spacing-loose');
}

Sass, with CSS Custom Properties

Custom properties are formatted in kebab-case.

// Omit .css at the end of the file
@import '~@shopify/polaris-tokens/dist/colors.custom-properties';

a {
  color: var(--color-blue-text);
}

Rails

Token files are added to the assets pipeline. In JSON, design token names are formatted in kebab-case.

require 'json'
polaris_token_file = Rails.application.assets_manifest.find_sources('colors.json').first
polaris_colors = JSON.parse(polaris_token_file)
polaris_colors['color-blue-lighter'] # "rgb(235, 245, 250)"

Contributing

The purpose of this repository is to see the core design elements of the Polaris design system evolve and improve over time with the needs of developers, designers and partners in mind.

We gratefully accept impromptu contributions to the documentation, typo and bug fixes, and expect design token requests and changes to be discussed before a pull request.