@moda/tokens

Been here before? Visit the click-to-copy documentation. First time? Keep reading.

What is this?

Tokens are the lowest level of the design system. They are individual named values that, when composed, form our styles; names of colors, values for spacing, etc. We use them to ensure consistency across all of our UI. For more information about this concept, broadly see: Tokens in Design Systems and What Are Design Tokens?.

This library encapsulates these values and provides some interfaces for utilizing them within your stylesheets or JavaScript.

What this is not

This is not a library of React components or a library of icons. It is not "The Design System", only a single piece of it — the lowest-level piece.

Meta

• State: production
• Point people: @ModaOperandi/ecommerce-squad

Architecture

The source of truth for these values begins in SASS variables. Moda uses SASS (specifically SCSS) across all of its front-end projects and it's easier to go from SASS to JSON, TypeScript, etc, than it is the other way around. The values are accessed through either SASS functions or mixins, appropriate to the type of value in question. At build time we also auto-generate TypeScript maps and export some typed helper functions for accessing them when needed.

Getting started

Install the package:

npm install --save @moda/tokens

Import the library and utilize the mixins or functions in your SCSS files:

@use '~@moda/tokens';

// Use functions to access values:
p {
  @include tokens.text(body1);
}

Import the library and utilize the values in TypeScript:

import { color } from '@moda/tokens';

color('ink');

• Netlify deploy config is located here: https://github.com/ModaOperandi/tokens/blob/main/netlify.toml

• Netlify site overview: https://app.netlify.com/sites/moda-tokens/overview

(settings specified in netlify.toml override any corresponding settings in the Netlify UI)

API

SASS

Functions

color($key, $opacity: number)

Returns a hexadecimal value associated with the color key. Optionally accepts a value for opacity, which if present, converts the color to rgba and includes the opacity as the alpha value. Will throw an error if key is not present within the color map.

space($indexOrKey)

Returns a rem value from the spacing scale. Accepts a number (between 0–12) or a named key "half-x", "2x" etc. Will throw an error if index is out of bounds or key is not in the map.

spacing($indices...)

Shorthand similar to padding/margin shorthand. spacing(6, 0) => 2rem 0, spacing(4, 2, 6, 2) => 1rem 0.5rem 2rem 0.5rem

Mixins

@include text($key, $font: name, $important: boolean|property-name)

Primary method of utilizing typography. Accepts the name of a text treatment and returns the composition of styles (font-size, line-height, letter-spacing, etc.) that form the text treatment. Optionally accepts a $font argument which can be either sans, serif, or code. $important is a less useful option but available if you need to clobber some legacy styling.

@include breakpoint($key, $prop: property-name) { @content }

Wraps nested content in the specified breakpoint. $prop defaults to min-width in a mobile-first approach. Pass it $prop: max-width for a more familiar desktop-centric usage.

Variables

Refer to the files in the variables directory.

Less-common functions

font-family($key)

Returns the font-stack associated with the key.

dangerously-get-letter-spacing($index)

Returns the letter-spacing associated with the index.

dangerously-get-line-height($index)

Returns the line-height associated with the index.

dangerously-get-font-size($index)

Returns the font-size associated with the index.

text-treatment($key)

Returns text-treatment map associated the key.

important($important: false, $prop: null)

Allows one to append !important conditionally on the end of a given prop.

Less-common mixins

compound($map, $important: false)

Accepts a map of styles and converts them into actual styles that can be mixed into a class.

TypeScript

The package exports typed maps built from the SASS maps as well as some similar helper functions for accessing values.

Maps

colors;
// => colors.all,
//    colors.ui,
//    colors.global,
//    colors.mens,
//    colors.womens,
//    colors.greyscale

typography;
//  => typography.fonts
//     typography['line-heights']
//     typography['letter-spacing']
//     typography['font-scale']
//     typography['root-font-size']
//     typography['text-treatments']

space;
// => space.scale
//    space.map

breakpoints;
// => breakpoints.xs
//    breakpoints.sm
//    breakpoints.md
//    breakpoints.lg
//    breakpoints.xl

Functions

text

Accepts the name of a text treatment and, optionally, a font. Returns an object representing the CSS styles for that text treatment.

type TextTreatment = "display" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "body1" | "bold1" | "body2" | "eyebrow"

const text: (name: TextTreatment, font?: "serif" | "sans" | "code") => {
    "font-family": string;
    "line-height": string;
    "font-size": string;
    "letter-spacing": number;
} | {
    "font-family": string;
    "line-height": string;
    "font-size": string;
    "letter-spacing": number;
} | ... 7 more ... | {
    ...;
}

remToUnitlessPx

Take some rem value '0.8125rem' and turn it into corresponding px (@ root) => 13

const remToUnitlessPx: (value: string) => number;

color

Accepts the name of a color and returns back the corresponding rgb(a) value.

type Color = "ink" | "cement" | "fog" | "elephant" | "noise" | "snow" | "strawberry" | "code-red" | "mint" | "money-good" | "fuchsia" | "klein-blue" | "brick" | "goldenrod" | "seafoam" | "coral" | ... 7 more ... | "canary"
const color: (name: Color, alpha?: number) => string

colorInHex

Accepts the name of a color and returns back the corresponding hex value.

type Color = "ink" | "cement" | "fog" | "elephant" | "noise" | "snow" | "strawberry" | "code-red" | "mint" | "money-good" | "fuchsia" | "klein-blue" | "brick" | "goldenrod" | "seafoam" | "coral" | ... 7 more ... | "canary"
const colorInHex: (name: Color, alpha?: number) => string

spacing

Accepts indices from the space scale or strings and returns back spacing values. Example: margin: ${spacing(8, "auto")};

const spacing: (
  ty: number | string,
  rx?: string | number | undefined,
  b?: string | number | undefined,
  l?: string | number | undefined
) => string | number | undefined;