Contributing

Help us improve the design system by submitting anything from small fixes and documentation updates to brand-new components. We're a living system, and we can't wait to see what you'll bring to it!

Beta version
Contribution model is currently in a beta phase. It’s being shared in early stages to gather feedback and improve it. Feedback is welcome to help better adapt the framework to different needs, share it in our slack channel: #tech-proj-watson

Watson is built and owned by all of us at Docplanner. Product teams play a critical role in evolving the system to support scalable and efficient design and development.
If you have a new idea or you're working on a feature that might require updates to Watson, this page will guide you on how to start, what type of contribution you might be making, and what the process looks like.

Why contributing matters:

Avoid gaps: design-only, code-only, or undocumented changes create gaps that slow down teams' work.

Consistency is key to building trust: when Watson stays up to date and accurate with its content, it allows teams to adopt it with confidence and trust.

Maintain quality: treating design, code, and documentation together when addressing a contribution prevents regressions and maintains the robustness of the system.

Types of contribution

Below is a simplified contribution classification of the different ways teams can contribute to Watson:

By Feedback

Use this flow when you're not creating something new, but something needs Watson’s attention and care.

New or enhanced resource request	Request a feature or improvement that doesn't exist in our resources (components, documentation, templates, patterns, …)	Drop a message in #tech-proj-watson or open a Jira ticket so Watson team prioritizes it.
Report issues or bugs	Report something broken or inconsistent in our resources (components, documentation, templates, patterns, …)	Drop a message in #tech-proj-watson or open a Jira ticket so Watson team prioritizes it.

Please note that context is essential for all requests in order to provide the most appropriate support. Always include sufficient context in your requests, such as design explorations and rationale behind the decisions, so that we can deliver the most accurate and effective solution.

By Creation

Users can actively collaborate in the creation or evolution of resources. Take a look at the different areas of contribution.

New resource	When a new component, pattern, template, token, or documentation that does not exist is needed.	Open a Jira ticket with the information from Requirement Document for contribution so the Watson team can provide you support. Follow the contribution flow.
New enhancement	When an update or expanded functionality in an existing resource is needed.	Open a Jira ticket with the information from Requirement Document for contribution so the Watson team can provide you support. Follow the contribution flow.

What contributing looks like

Check out our different contribution flows. They show the usual delivery process with any extra Watson activities when contributing, it’s pretty straightforward.

How to start?

Before you get started with any detailed work, drop us a message in #tech-proj-watson about your need. We’ll help you understand whether your team needs to contribute any changes to Watson or whether we can take care of the work.

Contributing with feedback

Not every contribution requires creating or designing something new. Often, the most impactful contributions come from identifying issues, proposing improvements, or helping us understand unmet needs.

Feedback keeps Watson healthy, reliable, and aligned with real product work. Here’s how to share feedback effectively:

Open a Jira ticket under Watson board or through the #tech-proj-watson channel.

Share the information needed for having enough context about the request. It is important that you share a timeline with us, this would help us to prioritize the tickets.

What to expect: All requests are evaluated during our weekly review. We’ll provide feedback once the item is assigned and may schedule a short alignment session if needed.

Contributing creating resources

When facing a new need for a component or feature, you may discover that you need a design token, component, pattern, or template.

Before assuming that we need to build something new, it’s good to check:

Does it already exist in Watson?
Explore existing Watson resources before starting to create anything.

Is it planned on the Watson roadmap?
Some things might already be underway or scheduled.

Has someone else recently raised a similar need?
Avoid duplicating work, we can align and combine efforts.

You can use the following checklist to know if a contribution is needed or not.

If nothing covers your use case that’s your signal that a contribution may be needed. And we’re here to guide you through that process from the very beginning.

The process described may vary depending on the type of contribution you need to do, but in general it looks like this:

Contribution prep: Every contribution begins with a conversation through the #tech-proj-watson channel. A ticket with this information should be open in Watson jira board. We would contact you to align on the problem you’re trying to solve, confirm that the design system can’t already support it, and agree on scope, expectations, and involvement. Once aligned, a dedicated branch or workspace is created for the work.

Contribution work: This phase covers all the collaborative work needed to bring the contribution to life; design exploration, refinement with the DS team, preparing specs and handoff materials, and engineering implementation. Throughout this phase, we work together to ensure the contribution meets system standards for consistency, accessibility, and quality.

Launch: Once complete, the contribution is added to the library and published in all relevant documentation and tooling. This makes the new or updated resource discoverable and ready for use.

Communication and celebration: Finally, we communicate the contribution across the company channels, explaining what’s new, why it matters, and how teams can adopt it. We believe contributions deserve recognition, we’ll highlight them in our portal, announcements and release notes.

For the entire process, you can refer to the following figma document, which outlines all the stages and includes associated checklists so you don't forget anything!

Useful guides

These resources help you contribute effectively and keep your work aligned with the system:

Contribution checklist: Make sure your designs and code are ready to go with the collaboration checklist.
Includes: tokens, states, accessibility, documentation, Storybook, and other requirements.
Go to file

Requirement Document for Contribution: A structured template to help you express your problem, context, and intended solution clearly. Ensure this is attached to every contribution ticket.
Go to document

Design Principles & Best Practices: A set of foundational rules that guide how Watson components behave, look, and interact. Useful when proposing new assets or enhancements.
Go to page

Accessibility guide: A reference for designers and engineers listing the minimum accessibility expectations Watson enforces.
Go to page

In the near future, we will also have naming rules and a glossary of terms so that you are clear about what terminology to use and what naming patterns to follow.

Beyond contributions: Get involved

You can collaborate with Watson without requesting or building a new features:

Join the conversation: Get involved with design reviews and discussions for components and updates. Every quarter, the Watson team performs different activities and workshops where you can share your feedback and test new resources!

Advocate for Watson: Have a positive experience using Watson? Share your stories! Demonstrating how the system helps solve real-world design challenges encourages adoption, inspires other teams to use the system, and highlights the value of Watson across the organization. Being an advocate helps grow the system’s impact, ensures consistency across products, and reinforces a culture of shared design excellence.

Provide feedback: Help improve the system by sharing your thoughts through surveys, feedback sessions, or direct conversations with the Watson team. Your input ensures that components, patterns, and documentation evolve in ways that are practical and useful for all users.

Mentor and assist teammates: Use your knowledge of Watson to help colleagues get started, troubleshoot issues, or integrate components into their work. Whether it’s answering questions in internal channels, reviewing usage in projects, or guiding newcomers, supporting others strengthens the community and accelerates adoption.

Need support?

We're here to chat and make contributing smooth, clear, and enjoyable, whether you're a first-time contributor or bringing a complex proposal.

Drop us a message in #tech-proj-watson, here’s how we can help:

Ask questions anytime: Not sure if your idea belongs in Watson? Send us a message, we’ll help you evaluate it quickly.

Feature kick-off support: Share your initial problem or early mockups. We’ll help you understand whether the system already supports your needs or whether a contribution makes sense.

Pairing sessions (design or engineering): We can walk you through: creating a Figma proposal, understanding tokens usage, setting up the dev environment, preparing a compliant PR, ...

You can also schedule a call with us during our office hours, so we can discuss any issues you wish to share with us in detail.

Stay updated: We share release updates, improvements, and upcoming work in our portal and in Slack so you’re always informed about what’s new in Watson.