@lightspeed/cirrus-tokens

Tokens

What are tokens?

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

This includes:

• Colors
• Typography
• Spacing
• Shadows
• Radii
• 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/_colors.scss';
@import '@lightspeed/cirrus-tokens/partials/_typography.scss';
@import '@lightspeed/cirrus-tokens/partials/_spacing.scss';
@import '@lightspeed/cirrus-tokens/partials/_shadows.scss';
@import '@lightspeed/cirrus-tokens/partials/_radii.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:

---

Colors

Every color is structured in the following way: We have one base color (e.g., blue) and each base color has three variants which are scaled on brightness with a numeric system similar to fonts (blue-100 being the lighter variant and blue-300 being the darker one*). That leaves space for potential new colors and makes things clear if you have to pick a non-base color for something.

We name our colors by their original name except for our brand colors. It makes things more clear when you are using a brand color which is a good thing to take in mind.

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

---

Typography

Our Typeface

Lato is the font we use as our body and product font. This sans-serif typeface was designed by Łukasz Dziedzic in 2010.

So why do we use Lato over all the others? Simply put, we appreciate its rich character and effortless legibility. With Lato, numbers appear crisp and decipherable no matter the size. This is important for us, given our extensive use of digits across our products (prices, orders, etc.).

Font scale

The font scale consists of seven different font sizes. No other sizes are accepted. The text-xxs text style should only be used in uppercase because 8 is generally too small for text, by making it uppercase it has the same height as normal text-xs text.

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

---

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}

---

Shadows

Shadows make things tangible on screen. It gives the illusion of things coming off the screen and not being flat. They will also help to create depth levels, which enables hierarchy.

Inputs become more recognizable when they have an inner shadow in place. Also, to provide more feeling to the pressed states of buttons we need to create the illusion that it is being pushed into the background, an inner shadow will help with that.

• Outer: .cr-shadow-{scale}
• Inner: .cr-inner-shadow-{scale}, `.cr-inner-shadow-n{scale}
• Border: .cr-border-shadow

---

Radii

Border radius applies to all corners. We use them to make our elements look friendlier and softer to the eye.

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

---

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;