Link copied!

Contributing

This guide describes the whole process of ideating, designing, and contributing components, patterns, and templates for the Emarsys Design System.

If you have a question regarding this process, reach out to the Design System team via Slack: #team-design-system

When designing a new product inside Emarsys, you’ll want to solve certain problems and achieve specific goals. For the most part, our Design System provides you with tons of handy basics: colour swatches, text styles, grids, icons, containers, buttons, etc.

But eventually, you might bump into some sort of challenge you can’t instantly tackle using the Design System — maybe it’s a new way of using our existing component, or feel like you need something entirely new.

While we encourage everyone to use our Design System as much as possible, of course we want to to make it better, and adapt it to handle emerging challenges — to expand the existing components with new functionalities, and to add useful new components to the system.

Constraints

Try to keep these in mind when designing for Emarsys:

1. Utilize off-the-shelf solutions

You should try using the components present in the Emarsys Design System in your design, in a way they meant to be used.

When used properly, the Design System should dramatically help both the design and implementation phase of the product — its purpose is to remove overhead, not to limit you in your work.

2. Think systematically

Avoid designing and implementing “one-off” interfaces that serve only a single use case, and couldn’t be used properly anywhere else.

It saves a lot of development time making components which are reusable in the future — not just by you, but by other developers as well. The time saved here can be spent on working on the logic that powers the product itself.

3. Iterate and grow

The Design System is not carved in stone — it can be changed and expanded! So if you have a specific need, don’t hesitate to discuss it with the Design System team.

Existing components can be expanded with new functionalities, and new components can be added, too — as long as they serve the system.

Just keep in mind the Design System team's resources are limited, so we won’t be able to take on everything, sadly.

Expanding the Design System

First of all, ask yourself the following questions:

  • Do we really need a new component for this?
  • Can’t another similar component be used instead, with trivial compromises?
  • Can’t another existing component be expanded to achieve the goal?
  • How this component could be used elsewhere?

To have all the info to answer these questions, please go ahead and:

  • Ask the Design System team for advice.
  • Please ping us via Slack (#team-design-system), email, or visit us in person!
  • Browse this Design System page for a comprehensive list of components and patterns.
  • Take a look around Emarsys for existing components and patterns.

Specify your needs

Write a short brief about the component — emphasis on brief, you don’t have to write too much (if you don’t want to):

  • Goal: what sort of problems this component will solve?
  • Context: describe the context the component will be in, e.g. on which page.
  • Behaviour: describe how the component will behave.
  • Sketches: if there are any visual concepts or examples from other UIs, please attach those images as well.

Example brief:

Goal: The user should be able to quickly add and remove entries from a list of versions. We’d need an expandable list component for this.

Context: While editing an email campaign, the user can make multiple versions for testing on the “Versions” side panel.

Behaviour: The list will contain all the existing versions. Each list item has a few action buttons — edit, rename, remove. The user can easily expand the list with new versions by pressing the “plus” button. The user can rename the list items easily.

Open a ticket in Jira that contains this little brief with the following parameters:

  • Project: Enhanced Marketer Experience
  • Issue Type: Story
  • Summary: “Component request - {name of your component}”
  • Assignee: Gabor Soos or Norbert Levajsics
  • Team: Design System
  • Description: Paste your component’s brief here.

Opening a ticket is really beneficial because your request won't get lost, and we all can keep tracking it.
Please also notify us about the ticket in the #team-design-system Slack channel and mention the team with @design-system-devs.

Guidelines for designing a new component

  • Use as many atomic parts as you can (e.g. use our buttons instead of coming up with new buttons).
  • Always aim to make the new component part of the system — both visually (e.g. colors, borders, padding, shadows, etc.) and functionally (e.g. flow, interactions).
  • Check-in with Design System team often! (We love helping you!)
  • Follow our naming/prefixing guideline

Adding a new component to the Design System

  • Developers make and add the component to the Design System.
  • Once the component is in the Design System, it has to be added in our Sketch UI Kit as well.
    • The component should be taken apart to atomic parts — atoms, molecules, organisms.

FAQ

Why should I use the Design System instead of making my own UI from scratch?

1: Emarsys is a huge, sprawling suite, with a ton of different apps and pages. To keep all these pages and apps coherent and consistent, we need a common system.

Imagine if every team would start doing their “own thing”, and every page would look and behave differently? The teams’ intentions would still be noble: they just want to make the best product they can. Yet, these differences would just infinitely confuse and frustrate our users. The Design Systems helps with that.

2: Emarsys ships a lot of new features. In order to keep that up, you need to minimise overhead as much as you can. And by using ready-made components from the Design System, you can cut out the monkey work and focus on delivering value.

Imagine if every team would have the develop their own logic for rendering a data table? Days or even entire iterations would be wasted on just that. And every team would have to do it, for every project. That's time and money spent in a bad way. The Design System helps with this, too.

Are coherence and consistency that important?

Yes! From the user experience standpoint, coherence and consistency are important.

Easier to learn: one behaviour or analogy only needs to be learned once, which the user can leverage again and again elsewhere in the software.

Less frustrating: the user knows what to expect, they’ll feel more in control, and be less frustrated using the software.

Keeps the quality above water: coherence and consistency don’t directly increase the quality of software — but being incoherent and inconsistent hurts quality big time. In other words: people aren’t going to thank your for shipping coherent UI; but people will be mad at you if you don’t.

In order to make Emarsys have a high-quality UI, however, coherence and consistency aren’t enough: we have to make high-quality components and patterns — ones that get the job done, pleasure to use, and pleasant to look at. Luckily, that’s also our job.

But what is it in for me?

Simply put: you’ll save a ton of time and effort. And you’ll need that time to work on more important parts of the product.

One of the Design System’s purpose is to remove overhead — you don’t have to do the low-level monkey work every time you work on a project (e.g. writing the style and logic for rendering a data table), you just pop-in our very own component that already knows everything you need.

In a similar manner, this will also reduce maintenance costs — when the Design System team updates a component in the Design System, it can be implemented with minimal effort. In certain cases, it might even happen automatically!

How long it takes for my component to appear in the Design System?

It depends on the complexity of the component — it varies on a case-by-case basis, so make sure to talk to the Design System team about the roadmap.

Designing, developing, and testing even a simple component usually takes a few iterations (2 weeks).

Please make sure to check-in early and check-in often! (Again, we love working with you!)