@lightspeed/cirrus-tokens

Tokens

What are tokens?

Design Tokens are an abstraction for everything impacting the visual design of an app/platform.

This includes:

• Typography
• Colors
• Shadows
• Radii
• Spacing
• Transitions

Those can eventually be reused for multiple platforms (Web, iOS, Android, etc.)

Some references on the subject:

• Lightning Design System - Design Tokens
• Tokens in Design Systems
• Salesforce UX - Design Tokens

Installation

First, make sure you have been through the Getting Started steps of adding Cirrus in your application.

If using Yarn:

yarn add @lightspeed/cirrus-tokens

Or using npm:

npm i -S @lightspeed/cirrus-tokens

Contributing

Tokens are kept in JavaScript files for maximum flexibility and are built as .scss (Sass) and .css (PostCSS) through a prepublish npm script.

To see changes when updating a token or making any changes to this package code, navigate to this directory in and run this command to re-generate the build:

npm run prepublish

Note that this command will be run automatically when we publish to npm.

Usage

Import SCSS variables

@import '@lightspeed/cirrus-tokens/index.scss';

Use as utility classes

You can also use tokens as utility classes by importing partials:

@import '@lightspeed/cirrus-tokens/partials/_typography.scss';
@import '@lightspeed/cirrus-tokens/partials/_colors.scss';
@import '@lightspeed/cirrus-tokens/partials/_shadows.scss';
@import '@lightspeed/cirrus-tokens/partials/_radii.scss';
@import '@lightspeed/cirrus-tokens/partials/_spacing.scss';
@import '@lightspeed/cirrus-tokens/partials/_transitions.scss';

Or include them all in one import:

@import '@lightspeed/cirrus-tokens/partials/index.scss';

Utility classes follow the same naming convention as variables, except for spacing. Here's a rundown:

Typography

• Typefaces: .cr-serif, .cr-sans-serif, .cr-monospace
• Weights: .cr-regular, .cr-bold
• Sizes: .cr-text-{size}
• Letter-spacing: .cr-letter-spacing-{scale}

Colors

• Text colors: .cr-{color}-{value}
• Background colors: .cr-bg-{color}-{value}
• Border colors: .cr-border-{color}-{value}

Shadows

• Outer: .cr-shadow-{scale}
• Inner: .cr-inner-shadow-{scale}

Radii

• Scale: .cr-radius-{scale}
• Circle: .cr-radius-circle

Spacing

We use shorthand notation for spacing to keep things terse. m is for margin, p is for padding.

• All sides: .cr-m-{scale}, .cr-p-{scale}
• Top: .cr-mt-{scale}, .cr-pt-{scale}
• Left: .cr-ml-{scale}, .cr-pl-{scale}
• Bottom: .cr-mb-{scale}, .cr-pb-{scale}
• Right: .cr-mr-{scale}, .cr-pr-{scale}
• Vertical (Top/Bottom): .cr-mv-{scale}, .cr-pv-{scale}
• Horizontal (Left/Right): .cr-mh-{scale}, .cr-ph-{scale}

Transitions

• Durations: .cr-transition-duration-{speed}

For JavaScript Apps

You can import tokens in JS and you will get the following modules:

• typography
• spacing
• colors
• shadows
• radii
• transitions

Then in your JavaScript file:

import React from 'react';
import tokens from '@lightspeed/cirrus-tokens';
// Or import needed token directly:
// import { spacing } from '@lightspeed/cirrus-tokens';

const styles = {
  padding: tokens.spacing.scale['spacing-2'],
  // Or when importing only needed tokens:
  // padding: spacing.scale['spacing-2'],
};

const MyComponent = () => (
  <div style={styles}>
    My Component
  </div>
);

export default MyComponent;