@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}, .cr-inner-shadow-n{scale}
• Border: .cr-border-shadow

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

For JavaScript apps there's multiple ways you can make use of the tokens.

Using helper functions

You can make use of the helpers by importing the @lightspeed/cirrus-tokens/utils package. For the scales and values to pass, check the documentation online: https://cirrus.lightspeedhq.com/.

Import the @lightspeed/cirrus-tokens/utils package as follows:

import {
  color,
  radius,
  shadow,
  innerShadow,
  borderShadow,
  spacing,
  duration,
  typeface,
  fontWeight,
  fontSize,
  letterSpacing,
} from '@lightspeed/cirrus-tokens/utils';

color('blue-300');

// Or if you want all of them
import * as tokens from '@lightspeed/cirrus-tokens/utils';

tokens.color('blue-300');

An example in a React app:

import React from 'react';
import * as tokens from '@lightspeed/cirrus-tokens/utils';

const styles = {
  padding: tokens.spacing(2),
  fontSize: tokens.fontSize('xxl'),
};

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

export default MyComponent;

color(value: CirrusColor): string

The color utility allows you to pass the name of the color and it returns you a hex color string.

Example:

color('blue-200');
// => "#5187e0"

radius(value: number | string): string

The radius utility allows you to pass the scale of the radius and it returns you the radius string in rem/percentage.

Example:

radius(1);
// => "0.1875rem"
radius('2');
// => "0.375rem"
radius('circle');
// => "50%"

shadow(value: number | string): string

The shadow utility allows you to pass the scale of the box-shadow and it returns you CSS value for the shadow.

Example:

shadow(1);
// => "0 0.0625rem 0.125rem rgba(12, 13, 13, 0.15)"
shadow('3');
// => "0 0.75rem 1.5rem rgba(12, 13, 13, 0.15)"

innerShadow(value: number | string): string

The shadow utility allows you to pass the scale of the box-shadow and it returns you CSS value for the shadow.

Example:

innerShadow(1);
// => "inset 0 0.0625rem 0.1875rem rgba(12, 13, 13, 0.2)"
innerShadow('2');
// => "inset 0 0 0.375rem rgba(12, 13, 13, 0.2)"
innerShadow('n1');
// => "inset 0 -0.0625rem 0.1875rem rgba(12, 13, 13, 0.2)"

borderShadow(): string

The border shadow utility allows you to add a border using shadows. This is useful when you want to add an border to an image, but you don't know what kind of color the image contains or you want to make an element appear on top of an image.

Example:

borderShadow();
// => "0 0 0 0.0625rem rgba(12, 13, 13, 0.15)"

spacing(value: number | string): number | string

The spacing utility allows you to get a spacing value based on a scale.

Example:

spacing(0);
// => 0
spacing(1);
// => "0.375rem"
spacing('10');
// => "3.375rem"

duration(value: string): string

The duration utility allows you to get the duration in ms based on the value passed.

Example:

duration('slow');
// => "100ms"
duration('base');
// => "200ms"
duration('fast');
// => "300ms"

typeface(value: string): string

The typeface utility allows you to get possible fonts for a specific typography style.

Example:

typeface('serif');
// => "serif"
typeface('sans-serif');
// => "Lato, Helvetica Neue, Helvetica, Arial, sans-serif"
typeface('monospace');
// => "monospace"

fontWeight(value: string): string

The font-weight utility allows you to get possible font-weight for a specific style.

Example:

fontWeight('regular');
// => "400"
fontWeight('bold');
// => "700"

fontSize(value: string): string

The fontSize utility allows you to get possible font-size based on a scale and will return in rem.

Example:

fontSize(); // Will fallback to the base
// => "1rem"
fontSize('xxs');
// => "0.5rem"

letterSpacing(value: number | string): string

The letter spacing utility allows to the letter spacing based on a scale in rem.

Example:

letterSpacing(1);
// => "0.03125rem"
letterSpacing('3');
// => "0.09375rem"

Using tokens directly (Advanced)

You can import tokens directly in JS, which will give you some additional options that are available. We recommend using the helper functions (see above) as much as possible, since this will suffice for most use-cases. If you do need more fine-grain control, importing directly might give you what you need.

When you import the tokens directly, you will get access to 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;