How we work together to build faster, better, and more consistent experiences.
We are building shared, robust, and versatile building blocks that work across Vista so teams don’t have to reinvent the same solutions over and over. The more we collaborate, the faster SWAN gets smarter, and the less custom code teams need to own.
Use what exists first
SWAN provides accessible, consistent, and brand-aligned UI that is ready to use in design and code. Always start with what’s already available to ship experiences to our customers faster before reaching for custom styling, tokens, or one-off components.
Even if you can’t use all of SWAN, use as much of it as possible and build with our foundational components, tokens, interaction patterns, and accessibility guidelines. Using what we already maintain helps ensure consistency, reduces your overhead, and ensures a consistent experience for our customers.
All live components + usage guidelines are available in vista.design/swan.
If SWAN doesn’t fit, talk to us early
Reach out to the Design System team before creating or customizing any components. Early conversations help us avoid dead ends and keep design, engineering, and product aligned.
When you reach out, please share your timeline and include product, design, and engineering partners so we can move fast and give guidance that works for everyone. We’ll help you figure out one of three things:
- If it actually is possible with SWAN – we’ll show you how.
- If it’s not currently supported by SWAN – we’ll advise on next steps, how to build what you need safely, and/or where the work should live (SWAN, expansion packs, libraries, your own repo, etc).
- If it reveals a system-wide gap – we’ll explore updating SWAN to fill it so everyone benefits from the change.
We’ll always close the loop with clear next steps to help you move toward your goal.
What to expect when you come to us
We are here to help you find solutions that scale across Vista while keeping SWAN stable, accessible, and maintainable. To do this, we ask a lot of questions to understand your context fully and allow us to make informed decisions.
We need to heavily consider the ramifications before modifying or adding to SWAN. Because SWAN has a large, complex API, it’s susceptible to challenges like combinatorial explosions, component overload, and other forms of unintended complexity. Doing our due diligence up front helps reduce this risk and improves the experience for our consumers. And since removing from SWAN is extremely difficult – requiring a migration path, significant time and guidance, and only possible in major versions released at least 12 months apart – it’s essential that we get decisions right the first time
If the outcome of the conversation is that a product team owns the solution, we will still help you build it in a way that’s stable, accessible, and easy to maintain as SWAN updates.
How to reach us
We’re flexible and will adapt to whatever communication style helps you move faster!
- Slack is the fastest way to get help.
- Post in #help-swan for quick questions, guidance, and feedback.
- Create a shared Slack channel (e.g. teamname-swan-collaboration) for ongoing component or feature work.
- DM any Design System team member and we’ll route your question to the right people.
- We are also always happy to meet with you!
- Set up a design review when you want SWAN-specific or accessibility-focused feedback.
- Invite us to your team’s design crits if you’d like support earlier in the process – it’s never too early.
- Schedule ad-hoc working sessions to sort through complex problems together.
Why this matters (and a few ground rules)
- Accessibility isn’t optional. Everything we release on our site must meet at least WCAG 2.2 AA standards. If a change risks violating accessibility requirements, we will work together to find a compliant alternative that still meets your goal.
- Consistency creates trust. Customers shouldn’t have to re-learn how Vista works from one page to another. SWAN provides that continuity in shared patterns, behavior, and visuals. If you’re considering customizing or rebuilding a component, start by talking to us; we can usually achieve what you need with SWAN, or evolve it if there’s a true gap.
- SWAN is product-agnostic: we design and build for everyone. If something doesn’t feel right, please reach out and tell us why. It may uncover a usability issue, a missing variant, or a guideline that needs clarity. System-level decisions have to work across many teams and contexts, which means we’re intentional about when and how we evolve SWAN to ensure stability, accessibility, and versatility. Together, we’ll use data, user needs, and context to decide whether it should become part of SWAN, built as ashared expansion pack, or stay a product-specific solution.
- We help you move with velocity. Momentum matters. SWAN is the fastest path to ship, even when it doesn’t seem like a perfect fit. The system is often more flexible than it appears, and there’s often a way forward within SWAN once we look at the problem together. If something feels off, talk to us early so we can keep you unblocked, aligned, and moving quickly: the earlier you bring us in, the faster and smoother things go!
