Storybook and Drupal

Benefits of Design System

Design system is a tool to reduce frontend development cost  in larger projects, with multiple teams working on different apps but within the same brand. 

The problem

For complex organizations, such as a university or a corporation with multiple subsidiaries or brands, it is often necessary to have a large number of websites and/or mobile applications. This can be, for example, the main site of the company and the sites of its divisions or the site of various brands of one company.

Each of these projects  will require designs that are distinctive but must simultaneously remain visually consistent with the organization.

For such types of projects we need a tool that simplifies development, encourages consistency, reduces maintenance effort, and scales quickly and affordably — without hampering flexibility for individual developers or departments.

We need a common design line and a clear collection of elements from which each page can be built.

The solution - design system with component library.

Modern user interfaces are assembled from hundreds of modular UI components that are rearranged to deliver different user experiences.

A design system consolidates common UI components in a central well-maintained repository that gets distributed via a package manager. Developers import standardized UI components instead of pasting the same UI code in multiple projects. Since both designers and developers contribute to the UI components, the design system serves as a bridge between designers, frontend and backend developers teams. Projects can reuse design system components and further customize if needed. 

The Design System consists of different elements, which can be used in different ways and variants. It has different levels of structure: atoms, molecules, organisms, pages. Each atom/molecule/organism can have different variations.

The Design System uses an atomic approach - that allows developers to easily make some changes that will affect all pages/modules/paragraphs.

The Design system makes it easy to add new websites that will initially have a basic master theme at the start and then can have their own fonts/colors/variants.
 

Practical example

We used this approach when working with our partner Taikonauten digital agency on The Hochschule Bonn-Rhein-Sieg, University of Applied Sciences (H-BRS) web site and BASF web site.

Emulsify works as a connector between Drupal and Storybook, it adds settings which allow us to use twig in components. It is also a Drupal theme. It can be used as a standalone prototyping tool with twig templates or inside a Drupal installation.

Emulsify

Emulsify benefits

Modularity

Components we built for a project are reusable not only within that project, but also on others projects, helping us increase speed and efficiency on multiple projects without sacrificing code quality. We can reuse pre-process of data and have the same data structure, can have the same basic theme configuration and project structure.

Parallel development

is the ability to build out the frontend user experience in parallel to backend development and content modeling.

Emulsify is an open-source project that's free for everyone.

Storybook

Storybook is an open source tool for building UI components and pages in isolation. It streamlines UI development, testing, and documentation. This allows you to work on one component at a time. You can develop entire UIs without needing to start up a complex dev stack, force certain data into your database, or navigate around your application.

Storybook is a tool for visualizing the design system.

Storybook benefits

Customization

Storybook is flexible and can easily be customized for project needs. You can add custom breakpoints, grids (for visual testing), check dark and light themes. You can measure element paddings, outline element borders and so on. This is very useful for design checking and helps to get the job done without errors. We can add custom tabs at the top and at the bottom to add more functionality. For example, add brands or theme buttons.

Documentation

Storybook can also be a place to store documentation (how these components can be used, how the grid system should behave, etc.). We can export pages from Confluence as markdown files and then import this information to Storybook.

Controls and actions

We can use actions for checking how elements will behave in different cases (clicking, active state, open modals, etc.). Controls help us to show different elements variations with the same templates.

Design

We can integrate a design preview for each component to make it clear how that element looked in the original design.

Accessibility/visual regression testing

Storybook has a rich ecosystem of addons, one of which gives us accessibility/visual regression testing and feedback tools right in the UI while developing.

Chromatic

Chromatic is free hosting for your Storybook (private or public project). You can publish it and check the components with your team. Chromatic made it possible to include designers in the review flow during development of the actual components. You can create different builds, comment on components, assign reviewers, compare screenshots, different branches and builds.

Usually all design checks are done on the Chromatic side. Designers add comments, developers answer them and can approve or reject components.

You can also use a custom domain for a Chromatic project, but then you need to pay.

How it works

A component library is the central part of a design system. There are small items (like buttons and links) and bigger ones (carousel or text+media block). All these elements are separate and reusable components.

Emulsify Drupal theme runs Storybook inside of Drupal and adds the ability to use Twig templates in Storybook components. The Frontend team create twig templates, component styles and write components Stories using React. React is also used for customizing Storybook.

Backend team works with Drupal modules, create paragraphs and fields, pre-process data and include twig templates with exact path.

If we have multiple site structures (for example different brands) we have one general theme on Drupal and divide it into different themes inside the Storybook. This helps us to have one Storybook for all brands.

The components are completely modular and the entire instance of Storybook can be duplicated in another Drupal site with Emulsify (but you need to change styles and data structure for project needs).

Component-based design goes hand in hand with the practice of atomic design This methodology breaks down elements into five categories: Atoms, Molecules, Organisms, Templates, and Pages. Atoms are the smallest parts of your site. Atoms build molecules, molecules build organisms, etc.

Component structure:

Each component includes:

1. YAML file with data structure
2. twig template with html structure (using predefined variables from a YAML file)
3. component.stories.js - file for component Story (controls, actions, documentation are defined here)
4. .mdx/.md file for documentation
5. .scss file if needed

Approach benefits:

Backend:

• BE developers have a predefined list of fields and fields types (data structure), they can easily understand the list of fields and create it for paragraphs and modules.
• BE developers do similarly clear work, doing only data preprocessing, not developing twig templates and not integrating html code into them.
• Development of complex paragraphs, like infobox or wrapper for other paragraphs (for example, accordion, tabs), become much easier than to do it in the standard way with Drupal theming.
• With the standard Drupal theming approach developers need to define and create many twig templates themselves and pre-process the data to remove unnecessary wrappers of elements and get the data they need. In the Emulsify approach they only need to pre-process the data and include existing twig templates.
• The code becomes more predictable and of higher quality.

Frontend:

• Frontend developers don’t need to have Drupal locally, they don’t need to clean cache every time and import configs with drush commands. They don’t need to make environment settings for Drupal project.
• The website has clean html code, without many Drupal wrappers, and there are no surprises after integrating html code into Drupal, because everything is controlled by frontend and components that were created.
• All site elements are clearly visible in Storybook and can be checked quickly and easily.
• The designers see all elements that they can use on the website (as a result, the element has the same indentation, fonts, etc.)
• It’s easy to make changes: we can change the atom or molecule and it will change everywhere. We have predictable behavior of elements.
• Scalable system

Do you need a design system?

When is it a good idea to use the Emulsify approach?

• If you have a project with the same UI components in different pages/modules/paragraphs or across teams, the Emulsify approach is for you.
• If you have a list of paragraphs and modules, that can be used across all pages.
• You want to standardize the elements
• You want parallel development process
• You have complex multi-level paragraphs
• You have multi-brands structure

If you only have 3 templates (designs of 3 pages) with simple elements, it may be better to use the standard Drupal theme approach.

One of the many draws of using a component library is the ability for front-end developers to start building out pieces of a project before the back-end team has the Drupal site up and running.

Component-driven theming is gaining popularity in Drupal and in the greater front-end development worlds. Taking a component based approach offers greater consistency, flexibility, re-usability and velocity for front-end development.