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.
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.)
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.
Layout
- Most page content should go inside a Bounded Content component, which puts horizontal space between the page content and the edge of the browser window. Notable exceptions include top of the page heroes/banners, which often want to go all the way out to the edge of the browser window; these should not go inside a Bounded Content.
- SWAN has a layout Grid as a foundational component. Nearly every page on the site will want to use it for its basic page layout. It provides 12 possible columns of content, with a standard “gutter” in between them, for a consistent horizontal layout from page to page.
- While most horizontal spacing between page sections will be provided by the Grid (see above), vertical spacing is something you’ll need to add, since most SWAN components do not provide any external vertical spacing. SWAN has a “spacing system” for this, where you can add margin or padding in one of 13 standard values. Rather than putting this spacing onto a SWAN component directly, it’s safer to put it on a wrapper element around a component. This guarantees that your spacing won’t mess up any margin or padding inherent to the component.
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 check 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.
