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.

React setup

Instructions to add SWAN in your React project.

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

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 to applications through different base URLs depending on your application's tenant context:

• Tenant-specific domains (Proxy to SWAN S3):
  For applications hosted on a tenant's domain, a dedicated proxy routes requests to the SWAN S3 bucket.
  Example: https://vistaprint.com/swan for applications on vistaprint.tld domains.
• Non-tenant domains (SWAN CDN):
  For applications not hosted on a tenant domain, assets are served directly from the SWAN CDN, which also points to the SWAN S3 bucket.
  Example: https://swan.prod.merch.vpsvc.com
• In UBIK applications:
  UBIK does not load fonts and stylesheets from the SWAN S3 bucket. Instead, UBIK hosts and serves these assets through its own dedicated CDN.

For most scenarios, you should use the CDN link returned by the getSwanBaseUrl(tenant, locale) method. This function automatically resolves the correct asset URL for your environment, ensuring assets are loaded from the correct 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.