Develop | Using Visage design tokens

A "design token" represents a bit of shared language that we can use to describe our user interfaces. Since we want to have a consistent way to talk about the colors across our site, we create design tokens like "error-color" and "text-color" rather than passing around raw hex-values like #d12c0b.

Since we want to have a consistent way to talk about the spacing between components, we create design tokens like "spacing-size-1" and "spacing-size-2" rather than passing around raw pixel-values like 8px.

These tokens/terms make it much easier for designers and developers to communicate about designs, which greatly reduces the friction between design and implementation!

In order for us to use design tokens across all of our systems, we need to convert them into various different formats that are compatible with each of our platforms. Folks can use this simple specification in order to build libraries/tools/plugins across each of our different systems.

The tokens are packed inside the visage library and provide 3 ways of implementation:

LESS - e.g. @errorColor: #d12c0b
SASS - e.g. $errorColor: #d12c0b
JavaScript - e.g. const colors = { error: "#d12c0b" }

We've also encoded these tokens into Figma so that designers can use them when creating mockups!

If you want to use these design tokens in a system that's not currently supported, please reach out in #help-visage on Slack, and we'll get you access to the spec!

In your stylesheets, @import the file "site-globals.less" or "site-globals.scss" as appropriate into your stylesheet. For example, here's how you would import the site globals file into a .scss file (the exact path will depend on where you placed the static globals files):

@import "/somedirectory/site-globals.scss"

In general, imports will be like below:
@import '~@vp/visage/src/tokens/scss/site-globals' // SCSS
@import '~@vp/visage/src/tokens/less/site-globals' // LESS

You then will have available in your stylesheets:

variables for SASS/LESS for writing your own stylesheets; these variable provide a consistent, site-wide color palette, and breakpoints for responsive design
mixins for SASS/LESS to provide common functions (like "hide this from screens but not assistive technologies"), and to add any necessary vendor extensions for browsers that we support.

The static globals provide you with variables for the colors in the Vistaprint standard palette. This includes not just variables with color names (e.g. $silver for our silver color), but also semantic values such as $border-color for the standard border color, and $error-color for the standard error color.

There are also variables for our media query breakpoints, so that you can target some CSS at a particular screen size. For example, in SCSS:

@media #{$media-query-extra-small-screen-size}
 {
     // code for Extra-Small screens only
 }

Currently, we have these media query variables:

$media-query-large-screen-size
$media-query-medium-screen-size
$media-query-medium-screen-size-or-larger
$media-query-medium-screen-size-or-smaller
$media-query-small-screen-size
$media-query-small-screen-size-or-smaller
$media-query-small-screen-size-or-larger
$media-query-extra-small-screen-size
$media-query-landscape
$media-query-portrait

The static globals provide mixins to provide easy syntax for commonly-used sets of CSS, and for creating cross-browser CSS without having to write vendor extensions.

Use these mixins wherever possible, because they keep you from forgetting a particular vendor extension or cross-browser technique. For instance, you don't have to remember which vendor prefixes you need to include to cover our list of supported browsers; just use the mixin, which we update as we add or drop support for a particular browser.

Many of these same tokens are available as TypeScript files. For instance, colors.ts exports a colors object that lets you use colors.border or colors.error.

Here is a sample use case:

import {
  sourceColors,
  globalFont,
  colors,
  spacingPx,
  spacing,
  screenClasses,
  screenClassMaxWidths,
  screenClassMinWidths,
} from '@vp/visage'

// Sample Usage
console.log(sourceColors.white) // '#fff'
console.log(globalFont) // '#000'
console.log(colors.border) // '#dfdfdf'
console.log(spacingPx[1]) // '4px'
console.log(spacing[1]) // 4
console.log(screenClasses) // ['xs', 'sm', 'md', 'lg']
console.log(screenClassMaxWidths.sm) // 768
console.log(screenClassMinWidths.md) // 1024

Using Visage design tokens

Variables and mixins to use in your own stylesheets and pages

Usage

LESS/SASS

Color Variables

Media Query Variables

Mixins

Javascript