Skip to content

Design tokens

Design systems consist of reusable key-value pairs. These are known as design tokens. Constructing digital interfaces using only the values of tokens that are defined in a design system ensures visual consistency.

API reference

View API reference table
Token Helper function Shorthand
Breakpoints breakpoint() bp()
Appearance
Colors color() c()
Gradients gradient() g()
Opacities opacity() o()
Background images background-image() bgi()
Line styles line-style() lns()
Line widths line-width() lnw()
Border radiuses border-radius() bdr()
Box shadows box-shadow() bsh()
Text shadows text-shadow() tsh()
Typography
Baseline baseline() bl()
Font sizes font-size() fz()
Line heights line-height() lh()
Font families font-family() ff()
Font styles font-style() fs()
Font weights font-weight() fw()
Letter spacings letter-spacing() ls()
Layout
Spacing spacing() s()
Coordinates coordinate() coord()
Wrapper widths wrapper-width() wrap()
Text measures text-measure() measure()
Grids flex-grid()
Ratios ratio()
Angles angle()
Animation
Durations duration() dur()
Easings easing() ease()
Keyframes keyframe()

Managing design tokens

Defining a token

// Define tokens in a config file
// e.g. `src/scss/config/spacing.scss`
@include set(spacing, (
  xs: 0.25rem,
  s:  0.5rem,
  m:  1rem,
  l:  1.5rem,
  xl: 2.5rem
));

Retrieving a token

// Use tokens in other stylesheets
.my-component {
  margin-top: spacing(s); // 0.5rem
  margin-bottom: s(xs);   // 0.25rem (Shorthand helper function)
}

Deleting a token

// The `unset()` mixin deletes an existing token.
@include unset(spacing, m); // Deletes the `m` spacing token

Using custom tokens

Custom tokens can also be defined if needed. They can be retrieved with the get() function:

@include set(custom-token, (
  token-1: 'value-1',
  token-2: 'value-2',
  token-3: 'value-3'
));

.my-component {
  ::before {
    content: get(custom-token, token-2); // 'value-2';
  }
}

Default tokens

These are the tokens that are recognized by Scarab. Helper functions are available for each of these tokens, allowing you to easily retrieve their value in Sass.

Breakpoints

Scarab takes a mobile-first approach to responsive web design. Define breakpoints as min-widths using px or em.

// Setter
@include set(breakpoint, (
  cinema:  1600px,
  desktop: 1280px,
  tablet:  768px
));

// Helper function
$_: breakpoint(desktop); // 1280px

// Shorthand helper
$_: bp(desktop); // 1280px

Appearance

Colors

Color tokens can be defined as a Sass color, or as a map representing a color palette.

// Setter
@include set(color, (
  black: #000000,
  grey: (
    dark:  #333333,
    _:     #999999,
    light: #CCCCCC
  )
));

// Helper function
$_: color(black); // #000000

// Shorthand helper
$_: c(black); // #000000

// Working with nested color palettes
$_: c(grey);       // #999999
$_: c(grey, dark); // #333333

Gradients

// Setter
@include set(gradient, (
  fade-to-black-from-top: linear-gradient(from top, rgba(0,0,0,0), rgba(0,0,0,1)),
));

// Helper function
$_: gradient(fade-to-black-from-top); // linear-gradient(from top, rgba(0,0,0,0), rgba(0,0,0,1))

// Shorthand helper
$_: g(fade-to-black-from-top); // linear-gradient(from top, rgba(0,0,0,0), rgba(0,0,0,1))

Opacities

// Setter
@include set(opacity, (
  opaque:      1,
  translucent: 0.5,
  sheer:       0.2
));

// Helper function
$_: opacity(sheer); // 0.2

// Shorthand helper
$_: o(sheer); // 0.2

Background images

// Setter
@include set(background-image, (
  stripes:        url(../images/stripes.svg),
  company-banner: url(../images/company-banner.jpg)
));

// Helper function
$_: background-image(company-banner); // url(../images/company-banner.jpg)

// Shorthand helper
$_: bgi(company-banner); // url(../images/company-banner.jpg)

Line styles

// Setter
@include set(line-style, (
  solid:  solid,
  dotted: dotted
));

// Helper function
$_: line-style(dotted); // dotted

// Shorthand helper
$_: lns(dotted); // dotted

Line widths

// Setter
@include set(line-width, (
  thick: 3px,
  thin:  1px
));

// Helper function
$_: line-width(thick); // 3px

// Shorthand helper
$_: lnw(thick); // 3px

Border radiuses

// Setter
@include set(border-radius, (
  pill:     10000px,
  curved:   9px,
  rounded:  3px
));

// Helper function
$_: border-radius(rounded); // 3px

// Shorthand helper
$_: bdr(rounded); // 3px

Box shadows

// Setter
@include set(box-shadow, (
  heavy:  0 0 4px 2px rgba(0,0,0,0.5),
  subtle: 0 0 2px rgba(0,0,0,0.125)
));

// Helper function
$_: box-shadow(heavy); // 0 0 4px 2px rgba(0,0,0,0.5)

// Shorthand helper
$_: bsh(heavy); // 0 0 4px 2px rgba(0,0,0,0.5)

Text shadows

// Setter
@include set(text-shadow, (
  inset: 0 1px 0 rgba(0,0,0,.25),
  glow:  0 0 4px rgba(255,255,255,0.5)
));

// Helper function
$_: text-shadow(inset); // 0 1px 0 rgba(0,0,0,.25)

// Shorthand helper
$_: tsh(inset); // 0 1px 0 rgba(0,0,0,.25)

Typography

Baseline

Defines the global typographic baseline value. Passing a number to the helper function returns a multiple of the baseline value.

// Setter
@include set(baseline, 1.5rem);

// Helper function
$_: baseline(2); // 3rem

// Shorthand helper
$_: bl(2); // 3rem

Font sizes + Line heights

Font size and line height tokens should share the same names. Scarab's type-scale() mixin generates font-size and line-height properties based on these token names.

// Setter
@include set(font-size, (
  heading: 2.5rem,
  body:    1rem,
  small:   0.8rem
));

@include set(line-height, (
  heading: 3.25rem,
  body:    1.5rem,
  small:   1.25rem
));

// Helper functions
$_: font-size(heading);   // 2.5rem
$_: line-height(heading); // 3.25rem

// Shorthand helpers
$_: fz(heading); // 2.5rem
$_: lh(heading); // 3.25rem

// `type-scale()` mixin
@include type-scale(heading); // font-size: 2.5rem; line-height: 3.25rem

Responsive typography

Each font size and line height token can also be responsive (i.e. have different sizes at different breakpoint). To make a token responsive, define it as a map of breakpoint names to token values.

@include set(font-size, (
  heading: (
    desktop: 4rem,
    tablet:  3rem,
    _:       2.5rem
  ),
  body:    1rem,
  small:   0.8rem
));

@include set(line-height, (
  heading: (
    desktop: 6rem,
    tablet:  4rem,
    _:       3.25rem
  ),
  body:    1.5rem,
  small:   1.25rem
));

@include type-scale(heading);

// font-size: 2.5rem;
// line-height: 3.25rem;
// 
// @media (min-width: 768px) {
//   font-size: 3rem;
//   line-height: 4rem;
// }
//
// @media (min-width: 1280px) {
//   font-size: 4rem;
//   line-height: 6rem;
// }

Font families

// Setter
@include set(font-family, (
  heading: ('Open Sans Condensed', sans-serif),
  body:    ('Open Sans', sans-serif), 
  accent:  ('Inconsolata', monospace)
));

// Helper function
$_: font-family(heading); // 'Open Sans Condensed', sans-serif

// Shorthand helper
$_: ff(heading); // 'Open Sans Condensed', sans-serif

Font styles

// Setter
@include set(font-style, (
  normal: normal,
  italic: italic
));

// Helper function
$_: font-style(italic); // italic

// Shorthand helper
$_: fs(italic); // italic

Font weights

// Setter
@include set(font-weight, (
  heavy:    700,
  semibold: 500,
  regular:  400
));

// Helper function
$_: font-weight(semibold); // 500

// Shorthand helper
$_: fw(semibold); // 500

Letter spacings

// Setter
@include set(letter-spacing, (
  loose:  0.2em,
  normal: 0,
  tight: -0.1em
));

// Helper function
$_: letter-spacing(loose); // 0.2em

// Shorthand helper
$_: ls(loose); // 0.2em

Layout

Spacing

// Setter
@include set(spacing, (
  xl: 4rem,
  l:  2rem,
  m:  1rem,
  s:  0.5rem,
  xs: 0.25rem
));

// Helper function
$_: spacing(l); // 2rem

// Shorthand helper
$_: s(l); // 2rem

Wrapper widths

// Setter
@include set(wrapper-width, (
  l: 80rem,
  m: 50rem,
  s: 30rem
));

// Helper function
$_: wrapper-width(m); // 50rem

// Shorthand helper
$_: wrap(m); // 50rem

Text measures

// Setter
@include set(text-measure, (
  l: 60em,
  m: 40em,
  s: 24em
));

// Helper function
$_: text-measure(m); // 40em

// Shorthand helper
$_: measure(m); // 40em

Coordinates

// Setter
@include set(coordinate, (
  10:  10%,
  20:  20%,
  30:  30%,
  40:  40%,
  50:  50%,
  60:  60%,
  70:  70%,
  80:  80%,
  90:  90%,
  100: 100%
));

// Helper function
$_: coordinate(50); // 50%

// Shorthand helper
$_: coord(50); // 50%

Grids

// Setter
@include set(flex-grid, (
  standard: 12,
  mini:     5
));

// Helper function
$_: flex-grid(mini); // 5

Ratios

// Setter
@include set(ratio, (
  square: 1/1,
  4-3:    4/3,
  21-9:   21/9
));

// Helper function
$_: ratio(4-3); // 4/3

Angles

// Setter
@include set(angle, (
  acute:  15deg,
  obtuse: 120deg
));

// Helper function
$_: angle(obtuse); // 120deg

Animation

Durations

// Setter
@include set(duration, (
  long:  0.85s,
  short: 0.25s,
  quick: 0.125s
));

// Helper function
$_: duration(long); // 0.85s

// Shorthand helper
$_: dur(long); // 0.85s

Easings

// Setter
@include set(easing, (
  default: cubic-bezier(0.645, 0.045, 0.355, 1),
  bounce:  cubic-bezier(0.68, -0.55, 0.265, 1.55)
));

// Helper function
$_: easing(bounce); // cubic-bezier(0.68, -0.55, 0.265, 1.55)

// Shorthand helper
$_: ease(bounce); // cubic-bezier(0.68, -0.55, 0.265, 1.55)

Keyframes

// Setter
@include set(keyframes, (
  fade-out: ()
));

// Helper function
$_: keyframe(fade-out);