Vanilla setup | Get started

Installing SWAN

If you are generating HTML pages using some template engines, installing SWAN will help with injecting styles and scripts.

Additionally, you may just want to re-use the design tokens that are exported within the SWAN package.

Configuring the .npmrc file for your project

SWAN is hosted in a private npm repository, so to install the package, you need to ensure that your .npmrc file is configured.

Add an .npmrc file to the root of our project with the following content.

.npmrcGetting artifactory token

@vp:registry=https://vistaprint.jfrog.io/vistaprint/api/npm/npm/
@vistaprint:registry=https://vistaprint.jfrog.io/vistaprint/api/npm/npm/
//vistaprint.jfrog.io/vistaprint/api/npm/npm/:_authToken=${VP_ARTIFACTORY_TOKEN}
//vistaprint.jfrog.io/vistaprint/api/npm/npm/:always-auth=true

@vp:registry=https://vistaprint.jfrog.io/vistaprint/api/npm/npm/
@vistaprint:registry=https://vistaprint.jfrog.io/vistaprint/api/npm/npm/
//vistaprint.jfrog.io/vistaprint/api/npm/npm/:_authToken=${VP_ARTIFACTORY_TOKEN}
//vistaprint.jfrog.io/vistaprint/api/npm/npm/:always-auth=true

# Login 
npm login --registry https://vistaprint.jfrog.io/artifactory/api/npm/npm/
# When asked username: firstname.lastname
# For passwoard Use API Key (Jfrog -> Edit Profile -> API Key)
# For email: use your official email id
# Copy the token from ./.npmrc file and store in the env file

# Login 
npm login --registry https://vistaprint.jfrog.io/artifactory/api/npm/npm/
# When asked username: firstname.lastname
# For passwoard Use API Key (Jfrog -> Edit Profile -> API Key)
# For email: use your official email id
# Copy the token from ./.npmrc file and store in the env file

You need to configure the VP_ARTIFACTORY_TOKEN environment variable in your system. To retrieve the value, please log in to jfrog and configure your npm client by login into it.

Read more in detail at "Install NPM Packages from Vistaprint Artifactory"

Install the latest version of SWAN

npm install @vp/swan@latest

npm install @vp/swan@latest

Configuring Page

Specifying the Locale (HTML Tag)

The html tag must have a lang attribute whose value is the language tag for that locale's language and region, using the language and region subtags. For instance, the language tag for Irish English would be en-IE, while the language tag for United States Spanish would be es-US.

<!DOCTYPE html>
<html lang="en-IE">
  <!--
  en-IE is for Ireland and English specifically;
  use the value appropriate for the user's locale and language
  -->
</html>

<!DOCTYPE html>
<html lang="en-IE">
  <!--
  en-IE is for Ireland and English specifically;
  use the value appropriate for the user's locale and language
  -->
</html>

Configuring Head

Add favicons

htmlUsing Script

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="format-detection" content="telephone=no" />
    <!-- Favicon Setup: Replace major_version with 2 or current value. -->
    <!--If the current version is 2.3.4, then the major version is 2, and the folder will become v2-assets-->
    <!--Replace default cdn domain name with locale based domain path-->

    <link
      rel="shortcut icon"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/favicon.ico"
    />
    <link
      rel="apple-touch-icon"
      sizes="152x152"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/apple-icon-152x152.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="120x120"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/apple-icon-120x120.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="76x76"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/apple-icon-76x76.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="60x60"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/apple-icon-60x60.png"
    />
  </head>
  <body>
    <!-- Body Content Goes Here -->
  </body>
</html>

<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="format-detection" content="telephone=no" />
    <!-- Favicon Setup: Replace major_version with 2 or current value. -->
    <!--If the current version is 2.3.4, then the major version is 2, and the folder will become v2-assets-->
    <!--Replace default cdn domain name with locale based domain path-->

    <link
      rel="shortcut icon"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/favicon.ico"
    />
    <link
      rel="apple-touch-icon"
      sizes="152x152"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/apple-icon-152x152.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="120x120"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/apple-icon-120x120.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="76x76"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/apple-icon-76x76.png"
    />
    <link
      rel="apple-touch-icon"
      sizes="60x60"
      href="https://swan.prod.merch.vpsvc.com/v{major_version}-assets/favicons/apple-icon-60x60.png"
    />
  </head>
  <body>
    <!-- Body Content Goes Here -->
  </body>
</html>

import {
  SWAN_BASE_URL_MAP,
  SWAN_PUBLIC_ASSET_FOLDER,
  SwanAssetFolders,
  getSwanAssetFolderName,
} from '@vp/swan'

function getLinkHtml() {
  const favFolder = `${
    SWAN_BASE_URL_MAP.vistaprint.com
  }${SWAN_PUBLIC_ASSET_FOLDER}/${getSwanAssetFolderName(
    SwanAssetFolders.FAVICONS,
  )}`
  return `
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="format-detection" content="telephone=no" />
    <link rel="shortcut icon" href="${favFolder}/favicon.ico">
    <link rel="apple-touch-icon" sizes="152x152" href="${favFolder}/apple-icon-152x152.png" />
    <link rel="apple-touch-icon" sizes="120x120" href="${favFolder}/apple-icon-120x120.png" />
    <link rel="apple-touch-icon" sizes="76x76" href="${favFolder}/apple-icon-76x76.png" />
    <link rel="apple-touch-icon" sizes="60x60" href="${favFolder}/apple-icon-60x60.png" />
  `
}

import {
  SWAN_BASE_URL_MAP,
  SWAN_PUBLIC_ASSET_FOLDER,
  SwanAssetFolders,
  getSwanAssetFolderName,
} from '@vp/swan'

function getLinkHtml() {
  const favFolder = `${
    SWAN_BASE_URL_MAP.vistaprint.com
  }${SWAN_PUBLIC_ASSET_FOLDER}/${getSwanAssetFolderName(
    SwanAssetFolders.FAVICONS,
  )}`
  return `
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="format-detection" content="telephone=no" />
    <link rel="shortcut icon" href="${favFolder}/favicon.ico">
    <link rel="apple-touch-icon" sizes="152x152" href="${favFolder}/apple-icon-152x152.png" />
    <link rel="apple-touch-icon" sizes="120x120" href="${favFolder}/apple-icon-120x120.png" />
    <link rel="apple-touch-icon" sizes="76x76" href="${favFolder}/apple-icon-76x76.png" />
    <link rel="apple-touch-icon" sizes="60x60" href="${favFolder}/apple-icon-60x60.png" />
  `
}

Add fonts and font faces

Most pages will need only the the Graphik webfont. (If a page design specifies MarkWeb, consult your designer first before you add it. That font was used on the monolith for older VistaPrint site designs, and isn't part of our current branding.)

Configuring FontsUsing Script

<link
  rel="preload"
  href="https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_medium2.woff2"
  as="font"
  crossorigin
/>
<link
  rel="preload"
  href="https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_regular2.woff2"
  as="font"
  crossorigin
/>

<style>
  @font-face {
    font-family: "Graphik";
    font-stretch: normal;
    font-style: normal;
    font-weight: 700;
    src: url("https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_medium2.woff2") format("woff2"),
                url("https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_medium.woff") format("woff");
  }
  @font-face {
    font-family: "Graphik";
    font-stretch: normal;
    font-style: normal;
    font-weight: 400;
    src: url("https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_regular2.woff2") format("woff2"),
                url("https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_regular.woff") format("woff");
  }
</style>

<link
  rel="preload"
  href="https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_medium2.woff2"
  as="font"
  crossorigin
/>
<link
  rel="preload"
  href="https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_regular2.woff2"
  as="font"
  crossorigin
/>

<style>
  @font-face {
    font-family: "Graphik";
    font-stretch: normal;
    font-style: normal;
    font-weight: 700;
    src: url("https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_medium2.woff2") format("woff2"),
                url("https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_medium.woff") format("woff");
  }
  @font-face {
    font-family: "Graphik";
    font-stretch: normal;
    font-style: normal;
    font-weight: 400;
    src: url("https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_regular2.woff2") format("woff2"),
                url("https://swan.prod.merch.vpsvc.com/v[swan_version]/fonts/graphic_regular.woff") format("woff");
  }
</style>

import {
  getSwanFontRenderConfig,
  SWAN_BASE_URL_MAP,
  SwanFontNameEnum,
  SwanPathTypeEnum,
} from '@vp/swan'

function getFontHtmlSnippet() {
  const [preloadLinks, fontFaceConfig] = getSwanFontRenderConfig(
    [SwanFontNameEnum.Graphik], // Font Names to load
    SwanPathTypeEnum.hashed, // Path type -> hashed | versioned
    SWAN_BASE_URL_MAP.vistaprint.com, // Domain name
  )

  return `
  ${preloadLinks.map(
    url =>
      `<link rel="preload" crossOrigin="anonymous" as="font" href="${url}" />`,
  )}
  <style type="text/css">${fontFaceConfig}</style>
  `
}

import {
  getSwanFontRenderConfig,
  SWAN_BASE_URL_MAP,
  SwanFontNameEnum,
  SwanPathTypeEnum,
} from '@vp/swan'

function getFontHtmlSnippet() {
  const [preloadLinks, fontFaceConfig] = getSwanFontRenderConfig(
    [SwanFontNameEnum.Graphik], // Font Names to load
    SwanPathTypeEnum.hashed, // Path type -> hashed | versioned
    SWAN_BASE_URL_MAP.vistaprint.com, // Domain name
  )

  return `
  ${preloadLinks.map(
    url =>
      `<link rel="preload" crossOrigin="anonymous" as="font" href="${url}" />`,
  )}
  <style type="text/css">${fontFaceConfig}</style>
  `
}

Adding stylesheets

All the stylesheets are hosted on our CDN.

SWAN exports utility methods to retrieve the URLs for our hosted stylesheets, as shown below. Using these, you can add either hashed and versioned files.

If you are manually typing the URLs its advisable to use the versioned one.

htmlUsing Script

<head>
  <!--After configuring Fonts-->
  <!--Configure StyleSheets: Note we are using versioned strategy, since getting hashed file name is not easy, use script approach for that. -->
  <!--Replace {version} with the library version eg. 1.0.0 -->
  <!--Replace default cdn domain name with locale based domain path-->
  <link
    rel="stylesheet"
    type="text/css"
    href="https://swan.prod.merch.vpsvc.com/v{version}/styles/core.min.css"
  />
  <link
    rel="stylesheet"
    type="text/css"
    href="https://swan.prod.merch.vpsvc.com/v{version}/styles/button.min.css"
  />
  <!--Add Other stylesheets-->
</head>

<head>
  <!--After configuring Fonts-->
  <!--Configure StyleSheets: Note we are using versioned strategy, since getting hashed file name is not easy, use script approach for that. -->
  <!--Replace {version} with the library version eg. 1.0.0 -->
  <!--Replace default cdn domain name with locale based domain path-->
  <link
    rel="stylesheet"
    type="text/css"
    href="https://swan.prod.merch.vpsvc.com/v{version}/styles/core.min.css"
  />
  <link
    rel="stylesheet"
    type="text/css"
    href="https://swan.prod.merch.vpsvc.com/v{version}/styles/button.min.css"
  />
  <!--Add Other stylesheets-->
</head>

import {
  SWAN_BASE_URL_MAP,
  SWAN_STYLE_KEY_MAP,
  SwanPathTypeEnum,
  getSwanStylesheetUrl,
} from '@vp/swan'

const keys = [SWAN_STYLE_KEY_MAP.core, SWAN_STYLE_KEY_MAP.button]

function getStyleSheetHtml() {
  const urls = keys.map(key =>
    getSwanStylesheetUrl(
      key,
      SwanPathTypeEnum.hashed, // pathType => hashed | versioned
      SWAN_BASE_URL_MAP.vistaprint.com, // Domain name to use
    ),
  )
  return urls
    .map(url => `<link rel="stylesheet" type="text/css" href="${url}" />`)
    .join('\n')
}

import {
  SWAN_BASE_URL_MAP,
  SWAN_STYLE_KEY_MAP,
  SwanPathTypeEnum,
  getSwanStylesheetUrl,
} from '@vp/swan'

const keys = [SWAN_STYLE_KEY_MAP.core, SWAN_STYLE_KEY_MAP.button]

function getStyleSheetHtml() {
  const urls = keys.map(key =>
    getSwanStylesheetUrl(
      key,
      SwanPathTypeEnum.hashed, // pathType => hashed | versioned
      SWAN_BASE_URL_MAP.vistaprint.com, // Domain name to use
    ),
  )
  return urls
    .map(url => `<link rel="stylesheet" type="text/css" href="${url}" />`)
    .join('\n')
}

Adding Scripts

Most of our components are CSS and HTML only, and don't need any additional JavaScript. The components below require JavaScript, and we provide a vanilla JS implementation:

Accordion
Alert Box
core
Modal Dialog
Popover
Progress
Progressive Image
Tabs
Toggle Switch

htmlUsing Script

<body>
  <div>You Content</div>
  <!--Replace {version} with the library version eg. 1.0.0 -->
  <!--Replace default cdn domain name with locale based domain path-->
  <script src="https://swan.prod.merch.vpsvc.com/v{version}/js/accordion.min.js"></script>
</body>

<body>
  <div>You Content</div>
  <!--Replace {version} with the library version eg. 1.0.0 -->
  <!--Replace default cdn domain name with locale based domain path-->
  <script src="https://swan.prod.merch.vpsvc.com/v{version}/js/accordion.min.js"></script>
</body>

import { getSwanJsUrl, SWAN_JS_KEY_MAP } from '@vp/swan'

function scriptHtml() {
  const scriptUrls = [
    SWAN_JS_KEY_MAP.accordion,
    SWAN_JS_KEY_MAP.alertBox,
    SWAN_JS_KEY_MAP.core,
    SWAN_JS_KEY_MAP.modalDialog,
    SWAN_JS_KEY_MAP.popover,
    SWAN_JS_KEY_MAP.progress,
    SWAN_JS_KEY_MAP.progressiveImage,
    SWAN_JS_KEY_MAP.tabs,
    SWAN_JS_KEY_MAP.toggleSwitch,
  ].map(key => getSwanJsUrl(key))
  return scriptUrls.map(src => `<script src="${src}"></script>`).join('')
}

import { getSwanJsUrl, SWAN_JS_KEY_MAP } from '@vp/swan'

function scriptHtml() {
  const scriptUrls = [
    SWAN_JS_KEY_MAP.accordion,
    SWAN_JS_KEY_MAP.alertBox,
    SWAN_JS_KEY_MAP.core,
    SWAN_JS_KEY_MAP.modalDialog,
    SWAN_JS_KEY_MAP.popover,
    SWAN_JS_KEY_MAP.progress,
    SWAN_JS_KEY_MAP.progressiveImage,
    SWAN_JS_KEY_MAP.tabs,
    SWAN_JS_KEY_MAP.toggleSwitch,
  ].map(key => getSwanJsUrl(key))
  return scriptUrls.map(src => `<script src="${src}"></script>`).join('')
}

SASS:

There are separate instructions on how to use SWAN design tokens in your project's stylesheets.

If you’re using node-sass in your project, we recommend that you use sass instead of node-sass with SWAN. The sass project works with all the major bundlers and frameworks (eg. gatsby, webpack, snowpack, parcel, etc) without you needing to change anything in the configuration.

npm uninstall node-sass # if already installed
npm i sass -D

Configuring the Body

SWAN is built to be interoperable with other design systems to allow incremental adoption. In order to achieve this, everything related to swan must be within the swan class.

Page Structure

Pages need a single, consistent set of HTML tags and CSS classes for wrapping major elements of the page, to provide a standard layout, and to support any behaviors we want to be consistent across the site. Your individual environment may already be providing some of these tags, e.g. through SwanProvider when using the visage library. If so, do not duplicate them.

<body class="swan">
  <!-- this tag should be the first child of the body tag -->
  <div class="swan-site-content">
    <!--Skip Link should be first focusable element for accessibility-->
    <a href="#maincontentstart" class="swan-skip-link">Skip to main content</a>
    <!-- header goes here -->
    <header>
      Add your page header and navigation, generally added via bookends
    </header>
    <main class="swan-site-main">
      <span id="maincontentstart"></span>
      <!-- for accessibility support -->
      <!-- your page content goes here, bounded content is not requried, but is mostly used -->
      <div class="swan-bounded-content"></div>
    </main>
    <!-- footer goes here -->
    <footer>Page footer, generally added via bookends</footer>
  </div>
</body>

<body class="swan">
  <!-- this tag should be the first child of the body tag -->
  <div class="swan-site-content">
    <!--Skip Link should be first focusable element for accessibility-->
    <a href="#maincontentstart" class="swan-skip-link">Skip to main content</a>
    <!-- header goes here -->
    <header>
      Add your page header and navigation, generally added via bookends
    </header>
    <main class="swan-site-main">
      <span id="maincontentstart"></span>
      <!-- for accessibility support -->
      <!-- your page content goes here, bounded content is not requried, but is mostly used -->
      <div class="swan-bounded-content"></div>
    </main>
    <!-- footer goes here -->
    <footer>Page footer, generally added via bookends</footer>
  </div>
</body>