Marmalade

Eventbrite is a worldwide platform enabling users to easily create, discover, and attend events of all kinds. Our mission is to unite the world through shared experiences, spanning concerts, marathons, networking, gaming, and even air guitar contests.

Design System Name

• Marmalade

Design System team size

• 2 people

Design System team make-up

• One Principal Designer
• One Senior Content Designer

Governance model

• Federated

Level of documentation

Level of detail 

• UX rules
• Anatomy
• Behaviors
• Tone and voice
• Usage guidelines
• Writing guidelines
• Accessibility guidelines
• Content guidelines
• Tech guidelines
• States
• Related patterns
• Props
• API
• Implementation
• UI rules
• Options

Brand elements

• Logo
• Colors
• Fonts
• Icons
• Borders
• Illustrations
• Photographs

Components

• Actions (buttons, links, etc)
• Alerts (pop-up, snackbar, toaster, etc)
• Forms (radio, checkbox, dropdown, inputs, etc)
• Status (progress bar, badges, loader, etc)
• Utilities (to accomplish specific tasks)

Documentation architecture overview

We organized our website’s navigation into broad categories (overview, foundations, components, brand, content, patterns, and resources) to help users find information easily. Each of these sections leads to more detailed content.

Our documentation is structured based on meaning rather than function, so we use categories like Foundations, Patterns, and Components instead of separating design and engineering. We aim to unite different user groups and ensure they all consistently use the system. This approach prevents isolated pockets of information within our documentation.

Structuring the documentation this way creates a shared experience for users. It’s easier to share information because a designer can, for example, just share the component they’re viewing, and their engineering partner can find what they need, too. Additionally, we integrate content and brand at the highest level and reference them throughout the site. This integration helps prevent users from experiencing disjointed interactions within our product. In essence, our documentation is designed with collaboration at its core.

Who document

• Designers
• Engineers
• Content

Documentation process

Our documentation functions in theme areas. We build out a series of components that work towards a larger pattern. Then, the pattern creation becomes the penultimate moment in each theme area.

So, for example, when working on “Forms,” the team built out input components such as Radio, Checkbox, and Select Field. These components all come together in our “Forms” pattern. And the “Forms” pattern is what we present, launch, and educate on.

When presenting our work to product teams and stakeholders, this creates a clear story. It also clarifies how components, foundations, and patterns all work together. It also makes education and launch clearer for ourselves and our product team. Combining our creation process with our documentation narrative is one of the ways we create harmony in our system.

The other thing we do is leave room for ambiguity. Our system is a framework that aims to support, not restrict. Our system, or any system, can’t account for every possible situation. And it shouldn’t! Systems for humans need to allow for imperfection because human beings are wonderfully imperfect. Sometimes, we document an update on a random Tuesday because it fills a need – and that’s OK. Leaving space for our humanity is a feature of our system, not a bug. 

Each section of the system has its own method of documentation, suited to the content being communicated. For instance, components follow a template, while patterns do not (because patterns are more variable and less commonly documented than components in our system).

However, there are principles that all parts of our documentation follow.

We cater primarily to a highly visual audience, so our documentation reflects that in our approach. Our strategy focuses on using visuals whenever possible, an abundance of organization, and intuitive communication design.

We advocate for the concept of “living documentation.” This means that we embed explanations of how to conceptualize, utilize, and implement Marmalade directly into the parts of the system that will be consistently touched in a workflow (i.e. component, token, prop, and variant naming). An example of this would be our Inline Alert component which defines each variant as the placeholder text. By doing this, users can learn how they should use each component while they are using them.

Maintenance and contribution

The creation of Marmalade encourages ideas from everyone, but the documentation is intentionally closed. Only core team members have access to edit the documentation site, and just one person (myself, the team’s Content Designer) acts as the supervisor of all documentation. 

This method allows unfiltered creative input to flourish without chaos emerging. Much like a script supervisor on a movie set, the documentation supervisor ensures that all voices, opinions, and contributions come together in a harmonious and clear single source of truth. She does not control the truth, she simply moderates, organizes, researches, updates, launches, and clarifies all system information into a fluid, documented narrative.

While one person does the physical documentation, the conceptualization is done by everyone. A sound system will change, grow, and adapt – in this spirit, we ask our product team to consistently provide feedback and ideas. It’s like having a network of spies who always scout the system in the wild. They report their findings to the core team, and the core team takes all that information into account before initiating updates.

You can visualize this process in the infographic below.

On the design part

As mentioned before, our documentation reflects the visual nature of our designers. To enhance understanding, we incorporate images, examples, and recently, we’ve introduced clickable infographics. Less words and more pictures is may feel counterintuitive to “documentation” but it has led to more adoption, sharing, and appreciation of Marmalade across Eventbrite.

We also have found that our designers like options. They want to be able to be creative, but to provide this creativity it means we would have an overwhelming amount of things to read which goes against the “less words” mentality of our designer documentation. To combat this we utilize narrative structures in our documentation of patterns and foundations.

In designer heavy areas of Marmalade, each section builds upon the previous one. This allows individuals who are entirely new to these concepts to follow along as if they were following step-by-step instructions. Simultaneously, it offers experienced users the flexibility to jump to specific sections, knowing that the information will align with more detailed decisions as they delve deeper. This approach ensures ease of navigation for users at all levels of expertise and a lower feeling of density (even when there is a dense amount of information needed).

Moreover, we strive to use terminology that aligns with users’ practical questions rather than relying on specialized jargon, recognizing that most of our users are not seasoned system professionals.

We find through these methods, and more, we are able to connect with our designers and make them feel not only clear in the system, but a part of it.

On the tech part

Through our research, we found that where designers enjoy open options, engineers want their information to be concise and efficient.

We use an inverted pyramid inspired by journalism, which organizes information by diminishing importance and level of detail (less detail up front, more below). This keeps engineers moving swiftly.

We also utilize Storybook in our documentation. Not only keeping props there, but organizing props by importance, defining props, keeping them consistent across components, and using stories to emphasize use cases.

Overall

Once, because I thought it would be fun, I decided to make Ratatouille for the first time ever using a recipe entirely in French. It went pretty much as you would expect: I ended up ordering pizza.

Moral of this story? 

It’s hard to do something new when you don’t understand the instructions.

Design systems are built on new components, patterns, foundations, and ideas. So, successful documentation should combat that by feeling familiar and natural.

That is the foundation on which Marmalade’s documentation was founded. 

We don’t give more than what’s needed. We keep things kind, especially if they are hard. We don’t confuse documentation with writing words. We don’t let the false narrative of perfection get in the way of improvement. And we always make sure our users can understand the instructions.