Mozaic philosophy

Team work and consistency

Designers and developers should work hand in hand to deliver consistent elements. You should choose the way you name thing together, and implement it the same way in the design libraries and in code.

Don't be scared to go back and forth between designer, developers or any party involved to fine tune documentation, code and design elements.

The same goes for libraries developped using Mozaic and dedicated to javascript frameworks for example. A special attention should be given so that the various persons involved going throught the design to HTML/CSS to Vue.js parts of the design system may talk the exact same language.

Sometimes your personnal preferences or habits may drive you away from using a consistant namming convention or implementation, but remember that sharing a common language is far more beneficial at scale.

At Mozaic, we decided to kill as much as possible the waterfall process of delivering a end design to the developers. We try as much as possible to define things together, and review our work in a cross-functional way. This take time, but it worth the effort.

To help you define pattern the best way possible, consider the following key axes of reflection :

Consider and define the uses cases first :

You should consider naming and organizing thing depending on the various uses cases in witch an element is used, instead of categorizing things depending on how they look.

This thinking will drive you to consider splitting some elements, categorizing things diferently.

To give you an example, when developping the tag component, at first we implemented it as we saw it in the design files. It was just one element. But by searching around, we discovered that in fact there was multiple uses-cases, one to display text, another acted like a check box from a list, etc...

We got back to the drawing board with designers and splitting the tag pattern into 4, with each one having specific names, classes names, symbols and use cases.

Some Think about thoses :

  • Functional uses-cases :
    • What a user should be able to do with the pattern ?
    • Is it really one Pattern, or more of a collection of related patterns ?
    • Should I be strict about its usage rules, or keep it open and utilitarian ?
  • Form-factors : what sizes, or variations should be available for a given pattern
  • Responsive : how the element should react on a small phone, a big desktop screen, using mouse/touch.
  • Color-themes : how color help convey meaning to the user, what variations will help create hierachy
  • States : how do the pattern react to mouse/touch events, and even if the pattern as other possible custom states like loading, empty, open / close etc...


Look for the most accessible way of doing things, this can lead to major changes in your thinking process and end pattern.

Accesibility include :

  • Color and contrast managment
  • Readability, text sizing and ease of use with tactile navigation
  • HTML semantic and attributes
  • Screen reader support and aria attributes

Always provide code examples and do and don't rules to help users do it the right way.

In the case of javascript framework, provide props/API and log warning and feedbacks to ensure that those rules are followed properly.


We created Mozaic with modularity in mind, this mean that we need to be careful about patterns interdependence.

We want users to be able to load or use only the parts of the design system they need.

For low level components, we try to never be dependant of another one, meaning we don't include them in one another.

For example, we never use the Flexy grid system classes to set the internal layout of a simple component, instead, we either choose to write custom flex declarations, or use the mixins provided by Mozaic to do it.


We need to take in account that users should be able to customize elements in some way. Mostly colors, fonts and sizes may be customised by users.

Keep that in mind and provide informations regarding the best way to do it.

Dev tips :

One way to do that is using design tokens, each and every values inside design tokens are overidable.

Also provide mixins to help users create new variations of the pattern.

Retro compatibility and stability

We need to be very careful about future changes in the design system. Because a lot of teams may depend on it that do not communicate with each other, we try to think our elements to be versatile and stable. This mean that the reflection time is important and you should take that into account.

This mean all changes made to an element should not require any user action.

If a change require a user action, this mean we need to change the design system version number from 1.x.x to 2.x.x, this is something that we need to avoid as mutch as we can.

Take that into account when modifying something in the design system.

Note: alpha and beta releases are instable by nature, meaning that between a 1.0.0-beta-1 and 1.0.0-beta-2 version, you can have incompatibility without having to notify the end user