Submit a new pattern

Good to know

If you are a designer you also need to read the Definition of Done for Sketch symbols contribution page

The creation of a new pattern on Mozaic Design System is usually done via the following workflow:

1. Create a new branch

Creating your new pattern starts with creating a github branch dedicated to it. This branch is ideally named as follows: pattern-xxx.

xxx refers to the name of your pattern (exemple : pattern-flags ou pattern-ratingstars).

2. Create your folder structure using Plop

Plop is a simple generator. We use it to save bootstrapping time when creating new pattern.

To use it, simply type in your terminal npx plop pattern

Then the CLI will ask you 3 questions :

  • the pattern name : use a Capital first letter and no spaces (ex: Buttons)
  • the pattern path : from the src/docs directory with no / at the end (ex: Components)
  • the pattern order : the position of your pattern in the navigation menu (an integer - ex: 4)

At the end of the process Plop will generate the required usage, code, specs, design tabs with helping markdown content.

Here are the details of what is expected in each of these pages:

  • usage: this page will tell you how and when to use the patterns. It will help understand what the pattern allows the user to do so you can use it right
  • code: describe how developers should use the pattern. This is done through:
    • indicate how to implement CSS (list the SCSS files to use/import)
    • show the HTML code of the pattern (use the module <Preview/> made available)
    • show as many examples as possible of the pattern states (basic state, theme variations, size variations, with icons, etc...)
    • list all the BEM modifiers applicable to the pattern
    • indicate how to customize the pattern (variables/mixes to be used)
    • indicate good practices to make the pattern accessible
  • specs: give details of the pattern specs, indicating all the values (variables, tokens, modifiers) associated with each state of the pattern
  • design: this page will be helpful for designers to know how the design file has been created and thought

Plop will also generate a basic preview.

3. Add all the elements (design/code) of your pattern

The documentation should at minimum contain :

  • a well thought pattern name
  • a short and well thought definition
  • what's the pattern to be developed
  • how it should works
  • in what cases it should be used or not

Your folder may also contain an implementation of the pattern's scss/js code with his related live html examples.

4. Push your branch and create a Pull Request

Once you have finished working on your pattern, it is time to push your branch and create a Pull Request associated with your work.

Please respect the Git conventions that we defined before pushing your work.

You will also find in the Git conventions page, the recommended method to make your Pull Request.