The Journey of a Design System

Jahia helps organizations across the world bring customer data and content together to deliver engaging, personalized experiences Learn more

Jahia Solutions is an amazing company that I have had the privilege of being a part of for the last year. We have embarked on the journey many other companies have, the pursuit of a design system. This is my take on our journey so far.

The beginning of the journey

It all started in 2019. Design systems were popping up all over the place. Blogs, companies, and tech influencers everywhere were talking about the benefits of design systems. The buzz and the anticipated benefits were more than enough to start the conversation at Jahia. We, at Jahia, develop several consumer-facing products, and consistent design, paired with faster development, sounded like a dream solution for us. In those early days, we didn’t quite understand the magnitude of work we were signing up for. Looking back, I think our innocence helped us start the journey, but the endless support and understanding from our leadership, product, design, and development teams are the reason we’ve made it as far as we have. For me, one of the biggest takeaways from the entire process has been that it’s extremely important to be aligned on expectations — they’re also dynamic and always shifting. Every person in the organization will have a different understanding and expectation from the process, effort required, and even the end goal. Without clear communication and teamwork, any design system journey is doomed.

Okay! Let’s go!

Once we decided to start the journey at Jahia, the goals were very clear. Everyone knew the benefits of a successful design system and the goal was to complete it as soon as possible. A small team of developers and designers formed a design system task force and, thus, our design system, Moonstone, was born.

moonstone - Jahia design system

Photo by malith d karunarathne on Unsplash

It didn’t take long before the team realized the true amount of work ahead. Over the next several weeks and even months, the design system task force continued to meet whenever possible. Early on, those meetings were an alignment exercise within the team. Everyone shared their ideas and understanding about design systems until, within the team, we had alignment. Once the task force had a good idea of the problem and its potential solutions, we put together a plan that we could share with the rest of the organization. Thinking back, this initial process was very important. It forced us to document our decisions and really dig down into the weeds of the process. During these meetings, I would often ask myself, “if a developer or designer joined the team tomorrow, would they be able to easily onboard and contribute to the design system?”

Making decisions

atomic design theory

Photo by Terry Vlisidis on Unsplash

Breaking apart our web applications

We decided to follow the Atomic Design theory, which, if you are unfamiliar with, I highly recommend looking into. It helped us break down components into smaller chunks which were easier to document and tackle.


Being a company with a production application and an existing customer base, we didn’t have the luxury of starting fresh. We had to come up with a way to seamlessly introduce the new system into our existing products. Our solution was to start with the smallest atoms described by Atomic Design. We created a list of every atom we could think of and began to design and build each one. From there, it was easier to layer on more and more complex combinations of those atoms.


Conveniently, the entire Jahia design team was part of our design system task force. Since our designers work closely with our product managers during the ideation phase of features, they have foresight into which initiatives are coming down the pipeline. With that key information, we were able to prioritize the development of certain components in Moonstone ahead of business deliverables.


Versioning was one of the big issues we faced during our early decisions. Coincidentally (or maybe not coincidentally considering how popular design systems are becoming), I also experienced this issue at the last company I worked for. Versioning is built into the workflow for developers (for example, with npm) because it’s so important to the way developers work with libraries. However, versioning systems for designers (for example, what’s built into Figma, Sketch, and their add-ons) are not yet very mature.

maintain versioning on local server

Photo by Alex Cheung on Unsplash

At Jahia we use Figma, which is an amazing tool for design, but it doesn’t support versioning of files. From my experience at both companies, there are lots of ways to solve this design versioning problem. At the last company, the design team approached the problem by creating a local server on which they manually maintained all of the versions of every individual file. Initially, it worked well despite it being a huge amount of extra work for each designer. However, when that design system started to scale up, they found that people would often forget to coordinate and more than one person would update the same file at the same time. Of course, this lack of coordination led to file conflicts. Ultimately, the system fell apart when one designer abruptly left the company and didn’t upload files that he had been working on.

Suffice it to say, I definitely don’t recommend this approach. The final solution for Jahia was to optimistically move forward for design files. We don’t keep old versions, and therefore, don’t need to manually manage multiple versions of the same file. To this point, it has worked flawlessly and as the adage goes, “if it ain’t broke, don’t fix it.”

Time to execute

Once we had presented our decisions to management and received sign-off, it was time to test our process. The first molecule that we decided to tackle was a text/search input field. After it went through design and was handed off to development, there was a document with design specifications that was to be used to develop the code for the component. However, there was one problem, ideas that were obvious to designers like different states, colours, or spacings weren’t in the document. Although the designers were able to see a colour and know exactly which hex code it was from our branding, the developers could not. The document was handed off with assumptions that weren’t the same between each group. Jahia is a very team-focused organization and an issue like this is quickly addressed through collaboration. We were able to dive back into our discovery meetings and come up with a solution to use a hand-off document that resolved all of our assumptions.

handoff from design to development

Photo by Cytonn Photography on Unsplash

Ever since, this document has been instrumental when handing off new components from design to development. The idea is to clearly define everything like spacing, what atoms or molecules are leveraged, colours, states, and even animations so that nothing is left to a developer’s imagination. Anytime we complete this hand-off, the document acts like a checklist for us to ensure everything is clear between both parties. It has reduced unnecessary back and forth discussion between design and development and has helped speed up our process.

Up to this point, the Moonstone task force had been planning the process and creating documentation, but had only just started creating usable designs and components. Jahia has many initiatives in the pipeline and the team hadn’t been able to quickly churn out new components to keep up with the pace of new features. Since the scrum teams who develop new features move more quickly, we had to come up with a solution to bridge the gap of missing components in our design system.

Introducing Moonstone Alpha

The Moonstone task force had tight deadlines, the scope was defined, and we had limited resources to work on the long-term improvement of the design system. In most cases, that would have meant the end of the design system, or at my past companies, endless overtime hours. At Jahia, I believe we came up with a tidy solution using the means that we had available. Our developers vastly outnumber our designers, and the main challenge was that the cornerstone of a good design system is having a solid and cohesive design. Therefore, each component must go through the design team. To accommodate the tight deadlines, we decided to build a secondary component library called Moonstone Alpha.

Moonstone Alpha is a repository to keep early-stage components that don’t yet exist in the long-term, primary Moonstone library — it’s similar to Material UI’s Lab concept. For a component to be added to Moonstone, its design and interactions are carefully tailored by our UI/UX designers, and the components in Moonstone Alpha don’t need to go through this process from the designers. This secondary component library allows the developers to build upcoming components even if the designers don’t have the necessary bandwidth to review them at the moment. Once the designers do have time to consider a new component for Moonstone, they can see which ones would be most useful by pulling in components that have been added to Moonstone Alpha.

This method has been very effective as it allows the design team to continue working on the primary Moonstone design system without it becoming compromised due to time pressures. It also lets us test out the development of new components, almost like a trial and error testing ground, before we take the best practices and leverage them for our primary Moonstone library. Finally, it enables us as a team and a company to continue to deliver for our business partners, and ultimately, our customers.


Going forward, we will continue building Moonstone towards the never-ending goal of a complete design system. In 2021, we’re planning to migrate all of our components to Typescript, implement CSS-in-JS, and add many more components. Stay tuned for updates on our progress and optimizations.

Thanks for reading!

You can find our design systems/component libraries here:

Vindhya Raviraj
Vindhya Raviraj

Lead Frontend Developer at Jahia.