This document provides an introduction to what Expansion Packs are, and how they fit in with SWAN. For those looking for usage documentation for existing Expansion Packs, see the EP Documentation Hub.
Expansion Packs (EPs) provide a paved path for sharing Bespoke UI Components and Patterns that are specific to a business problem and do not contain data fetching.
Each is managed by a federated working group (EP Maintainer) comprised of product teams close to the relevant scenario. Components are individually owned by single product teams (Component Maintainer).
The SWAN Ecosystem
SWAN Core (aka SWAN, @vp/swan) and SWAN Expansion Packs (aka Expansion Packs, EPs, @vp/ep-*) make up the SWAN Ecosystem. The goal of Expansion Packs is to enable the delivery of a consistent and intuitive customer experience by colocating and increasing visibility of UI that is not owned by the Design System team.
Domain knowledge is incredibly advantageous to creating the best solution for users. Teams closer to the problem have a better idea of what could work, context on broader problems, better historical knowledge, and more. We, as the Design System Team, often don’t have this insight. We should all work together to guarantee that the UI across the VistaPrint website remains consistent, cohesive, and intuitive.
Expansion Packs are not meant for any and all code sharing. They have a focus on modular and reusable UI with minimal external dependencies (e.g. data fetching, app state, etc). similar to the requirements for a SWAN component.
Core or Expansion Pack?
Maintained in SWAN Core
When a solution can be composed of one or a few SWAN components, business input is limited, and the use case is global, such as the Search Input component, the Design System team will maintain the component in SWAN.
Maintained in an Expansion Pack
When a solution requires significant configuration with high input from the business, including the potential for continuous and frequent changes and explorations, such as Tile-related components, it should be maintained in an Expansion Pack.
How do I create an Expansion Pack?
All Expansion Packs live in the Expansion Pack monorepo. The monorepo provides a dedicated space for each Expansion Pack as well as infrastructure for testing, building, and releasing those Expansion Packs as NPM packages.
Each Expansion Pack is owned by the appropriate working group, with individual components within the Expansion Pack owned by individual product teams. Note that each Expansion Pack contains one or more components.
Currently there are X Expansion Packs:
- List coming soon…
Contribution guidelines are available on Gitlab. This contains relevant information creating a new Expansion Pack, best practices on testing, developer commands, making a release, etc.
EPs all exist within a single repository, but each EP will be released as an individual package in Artifactory with its own individual release pace.
How do I create a component in an Expansion Pack?
Expansion Packs should lean on SWAN as much as possible, in both Figma and code. By using SWAN tokens and components to create a solution, any system updates flow through with less work. Additionally, it brings a greater sense of cohesion and consistency to the site, even if the final result does not live within SWAN. As such, exports from an expansion pack should tend towards ‘larger’ composed UI pieces.
As Expansion Packs become more developed, the Design System Team will offer additional guidance on best practices, as well as common utilities as needs arise.
Figma
Code is just one part an Expansion Pack, the other is design. All EP components are located in a single Figma library, with said components created and owned by EP Maintainers. Each component has its own page within the section, accompanied with a Title card containing a short summary of the component, ownership details, links to documentation, etc. Additionally, the documentation for each component provides a link to the component in this Figma library.
Designers publish components in lockstep with code releases, ensuring that they’re only publishing updates to components they own. Having a single library allows EP consumers to find EP components easily, and allow the Design System Team to enable the library by default in all new Figma files, similar to SWAN.
Documentation
Expansion Packs have a paved path for documentation, utilising Storybook. This is to reduce the effort required for EP Maintainers, while also improving the discoverability of components for EP Consumers.
The Design System Team owns the EP Documentation Hub, a single Storybook that compiles other EP-level Storybooks together, offering a single place for EP Consumers to find components regardless of who owns the component.
Each EP has its own Storybook, following a template that adds visibility to standard library documentation - ownership information, changelog, etc. Individual components have their own MDX-powered documentation page, following a consistent format, similar to the SWAN docsite. This allows Component Maintainers to add bespoke, necessary documentation to each component with minimal friction.
Glossary
Bespoke Component: A reusable, custom component or UI created and owned by a product team that solves a specific design or functional need. If widely adopted, these may be considered for graduation to SWAN.
Pattern: Reusable best practices for combining SWAN features to solve common user problems, such as filtering or onboarding.
EP Maintainer: The creator and owner of an individual Expansion Pack. Represented by cross-discipline members from multiple product teams.
Component Maintainer: A subset of EP Maintainers, typically a single product team, who are the owner of an individual component inside of an Expansion Pack. Includes both engineers and designers.
