Migrating to Watson Design System

Introduction

Watson Design System has been around for some time and we are very happy to see its being used in many contexts already. Still we believe that his adoption could be better in Docplanner’s doctor oriented products.

We’ve recently run a set of interviews with developers to try to identify obstacles in achieving a high rate of WDS adoption.

The conclusions can be split into three groups:

The good

Developers seem to value WDS for:

  1. Simplicity: Compared to the UI-Kit, Watson Design System is seen as simpler and more generic.
  2. Good integration: Watson integrates well with existing development processes.
  3. Layout components are great: Developers find the layout components in Watson to be effective.
  4. Figma and Watson enhance design implementation: Watson, combined with Figma, aids in translating designs into implementation by providing developers with necessary design information.
  5. Flexibility: Watson is appreciated for offering flexible components that allow developers to integrate third-party libraries and tools, giving them more freedom in their work.

Overall developers see value in WDS and are mostly eager to migrate to it.

The bad

There are two main pain points in the process of learning WDS

  • Learning new API of components and new ways of creating layout
  • Learning how to replace components with no direct equivalent in Watson

The ugly

The biggest issue though is not related directly to the design system or the library of components, but rather the limited time and resources we can devote to do the migration. This applies especially to more complex products like SaaS. The challenge that was reported the most was not the coding part itself, but rather making the decision on what to migrate and then getting code review of the changes that had been introduced.

OK, so what now?

In this document we will try to suggest a solution to the issues listed above with the biggest emphasis on mitigating the third problem. We believe that we can lower the effort required to increase WDS adoption in several ways. These are:

  • Using different migration strategies depending on the complexity of the product,
  • Using AI and our set of well tested prompts to help and speed up with the migration process,
  • Aiding developers and designers by providing meaningful examples and even better documentation,
  • In the last resort, we offer our help by joining your team and provide direct help with the migration process.

Migration strategies

This was the initial idea that we proposed on our WDS onboarding sessions. We believe that it would be best from the consistency standpoint. Unfortunately this is hardly doable in the real world scenario as most of our product pages are highly complicated, interconnected organisms. Migrating such organisms is a vast coding effort but it is an even greater effort to test, review and validate the outcome.We suggest picking this approach for smaller and easiest pages, where migration and code review won't be too long.

Alternative approach is to migrate a specific component across the entire project. It seems to be a simpler task from the developer’s perspective, especially for components that exist in both libraries. Unfortunately in this scenario the disadvantages remain the same. Reviewing, testing, conflicts across the files and validation the change seems an almost impossible feat as it requires verifying changes done in the scope of the entire project. We don’t recommend this approach at all.

Third approach is a mix of two previous scenarios. We believe that migrating a single component or even several components, but in a limited product scope will lower the required effort to the point it will become affordable to the team to spend time on it. You will have maximum control over all the changes in your product scope.

Migration workflow

In this section we will suggest an example scenario on how to approach the migration process of a specific component.

The process includes:

  • Identifying the component (criteria: most used, has 1:1 equivalent in WDS, amount of logic that has to be altered, etc.)
  • Evaluating the impact:
    • On the design - won’t break the UX of the page
    • On the codebase - changing the component won’t impact views or pages that are not in this scope especially if removing custom styles is involved in the migration.
  • Migration - replacing the component either manually (we will provide a migration guide with differences between components) or with help of AI by using prompts delivered by the Design Systems Team.
  • Validating the results
    • Getting code reviews from the code owners and Design Systems Team
    • Updating tests and verifying if they pass
    • Monitoring Sentry after the code is live

During every step you can reach the Design System Team to get aid from our:

  • designer, when page UI need to be changed and your designer will be overwhelmed
  • devs, when you get blocked with migration process or have some problems between component translations

Other ideas

Using AI to help with the migration process

With GH Copilot and Cursor we got useful tools that help us automate simple but time consuming coding tasks. We find it as an opportunity to speed up the migration process of WDS. Ideally we would like to make it possible to specify a component and make AI to replace it with a WDS of this component with properly translated properties. We're investigating possible ways of achieving that goal. We are not sure if we are going to provide you with ready to use prompts or maybe a general set of rules that could be fed to AI as .cursorrules files.

Examples and documentation

The general experience of using our documentation was positive. Still we got some constructive feedback and several ideas on how we can improve the documentation. We plan to work on those suggestions to make our documentation even better.