Contributing

High-quality, thoughtful design is what keeps Watson evolving. Designers across teams help us spot gaps, improve components, and make the system more useful for everyone. Your contributions shape how thousands of people build products every day.

This page explains how to get started, how the contribution workflow works, and the guidelines that help us maintain a consistent and accessible system.

---

Start here

• If you think something is missing, unclear, or could be improved, open a ticket in Watson board or though #tech-proj-watson channel. Share the problem you’re facing and the context around it. We’ll help you quickly understand whether the system already supports your need or if a contribution is the right path.
• Not every need requires a new component or an enhancement. Use our quick decision checklist to confirm whether a contribution is needed.
• Still unsure? Post your question in #tech-proj-watson, we’ll help you decide in minutes.
  

Proposing a design or an enhancement

Design contributions are key to keeping the Watson Design System consistent, accessible, and practical. This workflow outlines the steps to follow, from initial idea to final release, but you can find a more extensive overview though this FigJam file.

1. 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 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 playground file is created for the work.
2. Contribution work: In this step is where the design work happens. The design is explored and refined, including states, variants, behavior, and accessibility, while following system principles. A DS designer provides support throughout to ensure consistency. 
   The handoff is then prepared with specs, tokens, and annotations. Engineering may be involved to confirm feasibility and answer questions.
3. 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.
4. 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.

---

Guidelines

When contributing, please follow these guidelines to keep the system consistent and easy to maintain:

• Generality and reusability: Design components to be as general and reusable as possible. A component should solve a need for multiple teams, not only for a single feature. Before adding unique behaviors or app-specific details, consider whether they truly belong in the system or should remain local to your product.
• Component naming: Use clear, descriptive, and system-aligned names. The naming used should be consistent in design, implementations and documentation. 
• Sub-components: When creating complex components, consider breaking them into smaller, reusable sub-components. This supports maintainability, flexibility, and consistent behaviour across variations. Subcomponents are never published, as they only belong to a single component, so do not forget about adding a (_) before the name, to prevent them from being published. E.g _SubNav_Item
• Variants and props: Variants help keep components flexible yet unified. Use variant properties only when they represent true functional or semantic distinctions (e.g., state, size, type). Avoid creating variants based solely on cosmetic differences unless they serve a clear purpose.
• Styles: Use the built-in styles from the Watson Design System library for all components. This includes typography, colors, spacings, … If a required style is missing, consult with the DS team to determine whether a new style should be added globally rather than creating a local version.
• Layout and spacing: Apply autolayout, be aware about the resizing options for the resources and use Watson spacing values and spacing tokens for component padding and margins.
• Layers and groups: Organize layers and groups clearly to make components maintainable and reusable. Name layers and groups descriptively to reflect their purpose or content. Avoid generic names like Frame or Group. Group layers that belong together, and ensure each group contains at least two meaningful items. Avoid unnecessary nesting or single-item groups. Remove empty layers, hidden layers, or redundant groups.
• Component information: If creating a new component, be sure the component has been provided with a custom description and make sure the component has been added to a frame with a header explaining its purpose. It is necessary to be consistent on how we display the information to other stakeholders that would access our libraries.

---

Community library

In addition to the main library, there is a collaborative space where designers can share resources they create that may be useful to other product teams.

This space is ideal for experiments and solutions, and its resources are maintained directly by the designers. The Watson team periodically reviews this space to evaluate which elements could be incorporated or not into the global library based on their usefulness, consistency, and adoption.

Access to Community library

---

Design tools

To support your work, the Watson Design System provides a set of design resources and libraries in Figma, including:

---

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.