SWAN constants providing base URLs viz. SWAN_BASE_CDN_URL, SWAN_BASE_URL_MAP and SWAN_BASE_URL_LIST are deprecated. Use the SWAN utility function getSwanBaseUrl to get a URL to fetch SWAN assets. Refer getSwanBaseUrl
SWAN asset URL generators getSwanJsUrl, getSwanStylesheetUrl, getSwanIllustrationUrl, getSwanImageUrl, getSwanIconUrl, getSwanFontUrl are deprecated in favour of getSwanAssetUrl (refer below).
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 reuse 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. To install the package, you need to ensure your project’s .npmrc file is correctly configured.
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.
<!DOCTYPEhtml>
<htmllang="en-IE">
<!--
en-IE is for Ireland and English specifically;
use the value appropriate for the user's locale and language
-->
</html>
Configuring Head
Before you proceed on integrating SWAN on your page, it's advisable to refer to SWAN Assets Hosting and getSwanBaseUrl. SWAN exposes the utility getSwanAssetUrl which can be used to get appropriate asset URLs.
Most pages will need only 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.)
SWAN exports utility methods to retrieve the URLs for the hosted stylesheets, as shown below. Using these, you can add either hashed or versioned files.
If you are manually typing the URLs, it's advisable to use the versioned one.
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:
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
getSwanAssetUrl
Resolves the URL for a given SWAN asset (fonts, stylesheets, illustrations, icons, etc.) based on the asset type and key.
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.
<bodyclass="swan">
<!-- this tag should be the first child of the body tag -->
<divclass="swan-site-content">
<!--Skip Link should be first focusable element for accessibility-->
<ahref="#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>
<mainclass="swan-site-main">
<spanid="maincontentstart"></span>
<!-- for accessibility support -->
<!-- your page content goes here, bounded content is not requried, but is mostly used -->
<divclass="swan-bounded-content"></div>
</main>
<!-- footer goes here -->
<footer>Page footer, generally added via bookends</footer>
