<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HGSQD2L" height="0" width="0" style="display:none;visibility:hidden" title="GTM"></iframe>

Developers

Getting started

SWAN comes with two APIs, a React API and a Vanilla API. Each has its own setup instructions, but both use the same package, found at @vp/swan.

  • The React components use standard React syntax and are all controlled components.
  • The Vanilla API uses a specific set of HTML and CSS classes for each component.
Foundation

React setup

Instructions to add SWAN in your React project.
Vanilla

Vanilla setup

Instructions to add SWAN in your HTML project.

SWAN components

  • SWAN components are all mobile-friendly and designed to look good on all screen sizes.
  • Smaller components like buttons will typically be inline. Larger blocks (like tiles and banners) will fill their available horizontal space, allowing their container to control their width as part of a responsive page layout.
  • SWAN provides accessibility support at the component level, provided that you follow the accessibility guidelines in the SWAN documentation. (Note that this alone doesn’t mean that your page is fully accessible if it's all made from SWAN components, since much of accessibility is about how and where components are used.)
Components

Components

Reusable building blocks for use in building larger web experiences and patterns.

Keys

SWAN uses "keys" to associate a component with its necessary static files. Instructions on how to add these keys to your page are found in the Configuration pages for React or Vanilla.

  • Most SWAN components have a style key to provide the necessary CSS. You will need to include the style keys for the components you are using.
  • If you are using the Vanilla API (rather than the React API), some components also have a script key to provide the necessary JavaScript.

Page Layout

Page layouts are created using Page Wrappers, BoundedContent, Grid, the Responsive System, and Space. Correct use is essential for maintaining consistent content alignment across pages.

Refer to Page Layout for more information.

SWAN Assets Hosting

All SWAN assets (fonts, icons, illustrations, stylesheets) are hosted in a dedicated S3 bucket and served through optimized CDN URLs. There are two predefined DNS URLs for accessing these assets, depending on your application’s domain:

  • VistaPrint Domain:
    A dedicated proxy is available for any application hosted on vistaprint.tld domains.
    Example URL: http://vistaprint.com/swan
  • Non-vistaprint Domains (SWAN CDN):
    A swan.prod.merch.vpsvc.com CDN is available for all other applications not hosted on vistaprint domains.

For most scenarios, you should use the CDN link returned by the getSwanBaseUrl(tenant, locale) method. This function will automatically resolve the correct asset URL for your environment, ensuring that assets are loaded from the right location for your domain and locale.

Self-Hosting SWAN Assets

If you need to serve SWAN assets from a custom domain or CDN (for example, to serve assets from your own branded domain), you should self-host the assets:

  • The recommended approach is to obtain the assets from the SWAN npm package and host them yourself.
  • This is especially relevant for Cimpress or other brands who want full control over asset delivery.
  • Once self-hosted, supply the appropriate URL to the swanBaseUrl prop (or wherever required in your application configuration) to ensure your application loads assets from your custom CDN link.

Working with design

  • SWAN code is integrated with the SWAN UI Kit in Figma; we aim to have the Figma kit and the code match 1-to-1.
  • In Figma, use the Inspect tool to see the name of that component plus any variants/options used. These names should match the names of the components/features in code.
  • When a design calls for bespoke customization of a SWAN component, ensure you or your designer checks in with the Design System team before you start coding it. We may be able to help find a suitable option in SWAN. In the case of a new pattern, we will want to capture it for potential graduation into.

Developers' guide to Figma

For developers interested in understanding how Figma works and getting acquainted with this new developer tool, we recommend exploring the "Vista Developers' Guide to Figma" training on 360 Learning. This comprehensive course provides invaluable insights into Figma's functionality and its application for developers.

SWAN Overlay

The SWAN Overlay is a browser extension that allows you to see what parts of the VistaPrint UI are using SWAN components and assess the layout and alignment of the page.

Find out more: SWAN Overlay