Contributing to Resonance

Welcome! We’re thrilled you’re interested in contributing to Resonance. Whether you’re a designer or an engineer, it’d be great to have you involved. After all, Resonance grows, adapts, and changes to meet the needs of our products, and of the people who make those products—that’s you.

In this document, we’re going to outline a few ways you can contribute to Resonance, and some things to expect along the way. If you have any suggestions for how to improve this document, or if you have any questions about anything in here, let us know! You can find the Resonance team in the #chorus-resonance Slack channel.

What to know before getting started

Resonance is a design system, a platform that supports and sustains the interfaces for all of Vox Product’s internal applications. As such, we’re always looking for new contributions—ideas, bugfixes, and design patterns that have been successful not only in your product, but that will also flourish across the Resonance ecosystem.

As such, the Resonance team reviews new contributions to ensure that they’ll work within the broader platform. We expect every contribution to Resonance will be accessible, well-researched, modular, and visually consistent.

• An accessible contribution should be compliant with WCAG 2.1’s AA guidelines. (Vox Media’s Accessibility Guidelines can help!)
• A well-researched contribution should solve a proven need within your application. And that solution should be a clear improvement over those offered by existing Resonance patterns.
• A modular contribution will be highly reusable, allowing other Resonance products to incorporate it across different parts of their interfaces.
• A visually consistent contribution will adhere to Resonance style, ensuring that your work feels like it’s a cohesive part of the broader Resonance pattern library.

And perhaps most importantly, please note that all contributions are expected to adhere Vox Media’s Code of Conduct.

Types of contributions

A contribution could be a feature request, some code, a mockup, some documentation—or some combination of all four. But across all those mediums, we generally see three kinds of contributions: minor, medium, and major. Each is distinguished by the level of effort and review they require.

Minor contributions

Despite the name, minor contributions are still important! But they’ll only require minimal amounts of review, as their changes are fairly small. Examples of minor contributions include adding a new icon, changing a design token, or updating some of our documentation.

Medium contributions

Medium contributions require more review and feedback, and have a more noticeable impact. Examples of medium contributions include significant updates to our documentation, proposing a functional change to an existing component, or adding a design variation to an existing component.

Major contributions

These contributions have the most impact, and will likely involve considerable amounts of review or feedback. Examples of major contributions include adding a new component to Resonance, significantly changing the functionality of an existing component, or updating our Sketch UI kit.

How do I contribute?

The sky is, as they say, the limit! If it helps, here are the most common contribution scenarios we see, and how those contributions can start.

(And if you have any questions about this, reach out to us in the #chorus-resonance Slack channel at any time.)

Editing documentation

If you spot a typo in the Resonance documentation, or think of a way to improve a specific page, feel free to open a PR in the repository for our documentation site.

Editing an existing component

If you’d like to fix a bug you’ve found in Resonance, or implement a new feature on an existing component, start by dropping us a line in the #chorus-resonance Slack channel—it’s possible there’s something in Resonance that might address the issue you’ve encountered.

But if not, we’d love for you to contribute some code! At this point, your contribution should begin its life in the context of your product. Address the need there, and research how effective that fix is for your product’s users. Once it’s been vetted in the context of your product, reach out to us! Create a branch in our repository, implement the fix there, and open a pull request. We’ll schedule a review from there.

Creating a new component

If you’d like to create a new component for Resonance, that’s a significant undertaking—and one we’d love to discuss with you. Propose your idea to the #chorus-resonance Slack channel, and let us know what you have in mind. We’ll discuss the idea, ask questions about your plan, and talk about how to proceed.

If we think there’s value in the component you’ve proposed, the next step would be for you to implement your new component in the context of your product, and gather data on its effectiveness. Iterate over the component, and validate your initial assumptions.

Once it’s been vetted, reach out to us again in the #chorus-resonance Slack channel, and we’ll schedule another review to discuss what you’ve learned.

Creating an entirely new Resonance component is a major contribution, so there might be multiple rounds of review and iteration. But once we’ve approved your contribution (and its documentation), you can create a branch in our repository, implement new component, and open a pull request.

Who will review my contribution?

Your work will be reviewed by the Resonance team:

• Katie Kovalcin, design owner
• Miriam Nadler, engineering owner
• Ethan Marcotte, design systems tech lead

(As always, you can find us in the #chorus-resonance Slack channel. Come say hi, or ask a question!)

What kind of questions should I expect in a review?

Once you approach the team with a contribution, the Resonance team will schedule a time to review it. From that review, we might schedule time to discuss it in more detail over Zoom.

This isn’t an exhaustive list, but here are some questions we’ve commonly asked:

• Can we see this contribution implemented in the application you’re working on?
• What does this new contribution do? Why is it designed this way? What use cases does it address?
• Can you show us any research you’ve done on why Resonance needs this contribution?
• What kind of accessibility testing have you done?
• If this is a bugfix, what issues did you encounter? What workarounds did you attempt before you landed on this solution?
• Will this contribution introduce breaking changes in other products across the Resonance ecosystem?
  • Note: if your contribution introduces breaking changes, that won’t block your contribution! But it will impact the length of the review process, and will also introduce new communication requirements before we can incorporate your changes.

In this review, the team will work with you to determine if your contribution should be brought into Resonance. If it should be, we’ll likely give some feedback: there might be requests for changes or updates, as well as clearly-defined next steps for a subsequent review.

When is my contribution finished?

A contribution can be considered “finished” once your design revisions, your feature request, and/or your documentation edits have been approved.

If you’re contributing code, your contribution will be finished once it’s been approved, once it’s been documented, and once your code has been merged into Resonance’s codebase. If you’re making a change to existing Resonance components, or if you’re creating a new Resonance component, your contribution should include the necessary updates to Resonance’s documentation.

Of course, if the team decides not to include your contribution in Resonance, the contribution will be considered “finished” at that point, with our heartfelt thanks and gratitude for all your hard work.

How should I write my documentation?

If you’re creating a new component, we’ve created a blank reference document that shows how our documentation is structured. Make a copy of that reference document, fill in the blanks, and let’s discuss it during a review.

Got questions? Ask us!

If you’re not sure how sizable your contribution is, or if you’re not sure how to get started—that’s okay! Feel free to ask a question in the #chorus-resonance Slack channel, or open an issue for discussion in Resonance’s Jira board to describe your idea. We can ask a few questions about your contribution, and help you figure out how best to move it forward.