Skip to main content

Lunar Fusion

Drupal Design System
Emerging Technologies

Having worked with Drupal for over 10 years, I am a serious fan of this CMS. It's unrivaled in flexibility and is supported by a open-source community full of eager mentors.

However, as a designer, I have struggled with Drupal's lack of design system integration. Drupal wasn't structured to use existing design systems or to support the development of themes based on design system best practices. Now, that has changed.

Since late 2024, I've been on a deep-dive into the recently introduced tools and methods that will allow Drupal to utilize well-structured design systems and support the development of new, Drupal-native design system themes. I've built several themes which I used to test these tools and provide feedback to my community. This page is a living document for my notes and research projects.

Jump to a Topic

SDC (Single Directory Components)

What Are SDC (Single Directory Components)?

Enables Drupal Themes to use Design System Technologies

As of Drupal 10, Single Directory Components is now part of Drupal's core software. This approach structures a site’s theme to include individual component folders which each contain all the code needed to use that component.

Rather than including the code for each component as a library, it's all contained in that component's directory. This modular approach means that components can be used only as they are needed.

Single Directory Components allows us to structure our theme/design system components in the same way that Component Libraries (such as Patternlab and Storybook) do. Each folder contains all the component's code:

  • component.twig (structure)
  • component.css (style)
  • component.js (interaction)
  • component.yml (configuration information)

Component Library (n)

A design system is typically encapsulated in a component library, which is a web application that displays visual demos of each variant, provides usable front-end code, and includes documentation needed for usage and contribution. A component library is the platform we use to build, test, and maintain a design system.

Examples of component library tools:

a screenshot of component files and folders
SDC component file structure

UI Suite

What is the UI Suite?

Design System Library Tools Inside of Drupal

The UI Suite is a collection of Drupal modules which facilitate building a Drupal design system. It is supported by a community of developers who contribute to it and test it by building design system themes which leverage these modules.

UI Suite Modules:

UI Patterns

"The UI Patterns Library sub-module generates a pattern library page to be used as documentation for content editors or as a showcase for business and clients". UI Patterns @Drupal.org

UI Styles

Allows developers to define styles from modules and themes and site builders to use them from Drupal admin interface. UI Styles @Drupal.org

UI Skins

Facilitates CSS variables (collections of colors, sizes, fonts, etc) and themes (color collections for different sub-brands, or size collections for different devices). UI Skins @Drupal.org

UI Examples

Allows developers to provide example pages from modules or themes by defining render arrays in a YAML files. UI Examples @Drupal.org

💡

The Drupal UI Suite is fully functional and can serve as a Drupal-native tool to replace Storybook.

UI Suite Contributed Themes

None inspire confidence so far - appear to be new and in WIP mode, or complex to install and use. Many are only available for Drupal 10 and are only in beginning development stages. Some throw too many errors to be worth further investigation at this time.

a screenshot of a website with rows of color swatches on right and links to style types on left
Skeleton Theme displaying use of the UI Styles module, which displays a library of utility classes. The classes in this example represent CSS variables, such as color and spacing. (shown in light mode)
a screenshot of a component library with a menu of components on left, and details and visuals for each component on right
The UI Patterns module displaying my component library for Skeleton theme (shown in light mode)

Design System = Theme?

Design System

A design system is comprised of styles, settings, rules, and components which are used to build a piece of software. Most design systems use an atomic approach, wherein the more complex components are constructed out of the simpler components, making them far more efficient and resilient than bespoke designs.

Theme

In Drupal, a theme is a package of styles, templates, settings, and assets (images, fonts, etc.) that customize the display and functionality of a Drupal site.

A Drupal theme may use an existing design system by adapting that system as a Drupal theme (such as UI Suite Daisy and UI Suite Adobe Spectrum.) A Drupal theme may also be constructed using design system methodology (such as Skeleton Repo), such that the theme is a design system theme.

My UI Suite Research

Experimental Themes

I have multiple experimental themes in progress which utilize the UI Suite. These themes are not intended to be shipped code (which would require deep QA and peer review), but are rather tools for learning, testing, and collaboration.

Adobe Spectrum

Under Active Development

Having previously worked on the Adobe Spectrum CSS project, this design system is close to my heart. It's well structured and it features a robust CSS variable system. Converting this design system to a Drupal theme using the UI Patterns module has been an excellent learning tool. Under active development, contributions welcome.

UI Suite Adobe Spectrum

Academica 2

Partially Active

A theme intended as a neutral starting point for educational sites. After initially building Academica 1 using Storybook, I switched to a UI Patterns implementation for Academica 2.

Academica 2 Includes:

  • A color variable system with primitive and semantic layers
  • Dark mode support
  • Approximately 20 components
Academica 2 Repo

Skeleton

Under Active Development

A simple, playful theme for learning to build and implement components.

Skeleton Includes:

  • A color variable system with primitive and semantic layers
  • Dark mode support
  • 10+ components
  • Components implemented as paragraph module templates
  • Color utilities for the UI Styles module
Skeleton Repo
screenshot of Spectrum UI Patterns
Adobe Spectrum theme
screenshot of Academica theme in dark mode
Academica theme (shown in dark mode)
screenshot of Academica
Academica theme UI Patterns component library (shown in dark mode)
screenshot of Skeleton theme component library
Skeleton theme UI Patterns component library (shown in dark mode)

Storybook for Drupal

Storybook

Design System Library Tool

Storybook is the leading open-source software that developers use to build the components of a design system in isolation from the software that uses the components.

This allows developers to see:

  1. The full library of components and how they display
  2. How the components can be combined
  3. Variants of each component
  4. Documentation about how they should be used
  5. Front-end code needed to implement each component

Storybook is a type of software we often refer to as "component library", "pattern library", or "front-end workshop". I spent some time researching whether Storybook can be used as part of a Drupal theme to display a library of Single Directory Components.

Tools such as the Drupal Storybook module and Emulsify from Four Kitchens may help teams who wish to use Storybook for their Drupal design system.

Notably, the developers at UCLA have created UCLA Surface, which uses Storybook to display a component library which is compatible with their Drupal theme. Developer Mario Hernandez provided excellent instructions here on how they did it.

Storybook Resources

screenshot of Adobe Spectrum Storybook library
An example of a Storybook Pattern Library from Adobe
screenshot of UCLA Surface Storybook library
An example of a Storybook Pattern Library from UCLA, which is compatible with Drupal.

SDC-ADDON

Simplifies Storybook for Drupal

Storybook normally requires an additional stories.js file for each component.

SDC-Addon is an open source tool developed by Ivan Berdinsky. This addon allows us to build our components without the additional stories.js file.

Project Lead

Ivan Berdinsky

📁 Storybook Component

  • component.twig
  • component.css
  • component.js
  • component.yml
  • component.stories.js (not needed with the add-on!)

SDC-Addon Resources

screenshot of component files
Storybook with SDC-Addon requires one less file for each component.

My Storybook for Drupal Research

Experimental Theme Development

I spent some time researching this by building a theme using Storybook and the SDC add-on. I found that as I added more components, Storybook became so slow that continuing the project was not a productive for me at that time.

The sdc add-on is in active development and is being continuously improved by the developer. Teams who find Storybook to be their ideal component library solution may find that the issues I have had will be resolved in the coming months.

Academica

Inactive

This is the first version of Academica that I created before building Academica 2.

Academica Repo
screenshot of Academica Storybook
Academica theme Storybook

Emulsify

Open-source Drupal Toolset

Emulsify is an open-source tool created by Four Kitchens to enable a Drupal theme to be built with a design system and with Storybook. It provides a base theme and UI component collection which can then be customized and extended by a developer. It helps to connect Drupal with Storybook.

Emulsify includes the BEM Twig extension, which helps to modernize component styling in Drupal to use BEM CSS architecture.

By contributing this tool to the open source community, Four Kitchens demonstrates their dedication and integrity. They are putting real work into helping our open source tools continue to grow and serve our needs as developers. Hats off to them!

  • Emulsify uses Drupal's SDC feature
  • Incorporates Storybook into a Drupal Theme
  • Has an example basic component collection to get started with (Compound)
  • Has an example theme to use as a scaffold for a custom theme

NOTE: I encountered several errors while trying to implement this tool which may or may not be related to Emulsify itself. I put a pin in this research with plans to circle back later.

Emulsify Resources

screenshot
Emulsify provides Storybook for a Drupal Theme, along with additional controls so that component variant options can be explored in the Storybook display.

Additional Resources

For Storybook for Drupal

Articles

University Design Systems Using Storybook

Other Component Libraries

There has been some work done to help Drupal integration with PatternLab (Storybook's living ancestor). Of partivular interest is the BEM Twig extension, which helps Drupal to use correct modern CSS formatting (BEM) for integration with a PatternLab component library.

SDC Styleguide

Drupal Pattern Library Module

Drupal architect Alejandro Madrigal Leiva built the SDC Styleguide as a design system component library solution (alternative to Storybook and UI Patterns).

To use this tool:

  1. Install the module and enable it
  2. In your Drupal site, go to /styleguide/explorer (ddev local example: https://my-local-dev.ddev.site/styleguide/explorer)

SDC Styleguide Resources

screenshot of Skeleton theme SDC Styleguide
I tested SDC Styleguide with my Skeleton theme. Shown is the styleguide in action, along with custom CSS overrides to align with my theme.

SDC Shared Components

Drupal Module

Alejandro Madrigal Leiva is also working on a project to allow components to be shared between Drupal themes, so that a developer may create an SDC component which can be used on multiple projects.

Today, many open source themes are available for Drupal. We may be looking at a future in which developers can also share individual components, which could help improve accessibility for teams that lack the resources to develop and maintain all their components from scratch. This could also help new Drupal developers who may be unfamiliar with how to build an SDC component.

Imagine using a component library for Drupal as easily as you can use a CSS framework like Tailwind!

Shared Component CSS and Theme CSS

If we develop conventions around how we structure our component CSS, we may even be able to build components that plug easily into a range of themes and reflect the theme's CSS. For example, I've included here the CSS for my details component from Skeleton. The component variables I used are repeated at the top of the file and renamed for that component. A developer only needs to change the values of these variables at the top to match their theme.

Sharable Single Directory Components

/* renamed system variables for this component */
.details {
  /* colors */
  --details-color-text: var(--skeleton-color-fg-base);
  --details-color-border: var(--skeleton-color-border-neutral-extra-subdued);
  --details-color-background: var(--skeleton-color-bg-neutral-extra-subdued);
  --details-color-background-content: var(--skeleton-color-bg-base);
  --details-color-marker: var(--skeleton-color-fg-subdued);

  /* colors theme primary */
  --details-theme-primary-color-border: var(--skeleton-color-border-primary);
  --details-theme-primary-color-background: var(--skeleton-color-bg-primary);
  --details-theme-primary-color-marker: var(--skeleton-color-fg-primary);

  /* space and size */
  --details-border-radius: var(--skeleton-size-radius-sm);
  --details-transition-marker: var(--skeleton-transition-basic);
  --details-width-border: 2px;
}

/* styles for this component */
.details {
  border: var(--details-width-border) solid var(--details-color-border);
  /* border width is smaller when in a group */
  border-block-width: calc(var(--details-width-border) * 0.25);
  background-color: var(--details-color-background);

  &__summary {
    position: relative;
    font-size: 1.2rem;
    line-height: 1.3;
    font-weight: 600;
    vertical-align: middle;
    padding: 1rem;
    padding-inline-start: 1.5rem;
    color: var(--details-color-text);
    overflow: hidden;

    span {
      margin-inline-start: 0.25rem;
    }

    &::marker {
      color: var(--details-color-marker);
      margin-inline-end: 0.5rem;
    }
  }

  &__content {
    padding: 1.5rem;
    background-color: var(--details-color-background-content);
    font-size: 1rem;
    line-height: 1.4;
    display: block;
    border-end-start-radius: var(--details-border-radius);
    border-end-end-radius: var(--details-border-radius);
    overflow: hidden;
  }

  /* border radius only top and bottom */
  &:first-of-type {
    border-start-start-radius: var(--details-border-radius);
    border-start-end-radius: var(--details-border-radius);
    border-block-start-width: var(--details-width-border);
  }

  &:last-of-type {
    border-end-start-radius: var(--details-border-radius);
    border-end-end-radius: var(--details-border-radius);
    border-block-end-width: var(--details-width-border);
  }

  &:open {
    .details__summary::before {
      transform: rotate(90deg);
    }
  }

  /*** Variants - color themes ***/
  &--theme-primary {
    --details-color-border: var(--details-theme-primary-color-border);
    --details-color-background: var(--details-theme-primary-color-background);
    --details-color-marker: var(--details-theme-primary-color-marker);
  }

  /*** Variants - FontAwesome marker ***/
  &--style-fa-marker {
    .details__summary {
      padding-inline-start: 3rem;

      span {
        margin-inline-start: 0;
      }

      /* hide default marker */
      &::marker {
        color: var(--details-color-marker);
        content: " ";
      }

      /* customize marker */
      &::before {
        position: absolute;
        top: 50%;
        bottom: 50%;
        left: 1rem;
        height: 1.2rem;
        width: 1.2rem;
        margin: auto;
        display: inline-flex;
        align-items: center;
        justify-content: center;
        font-size: 1.2rem;
        line-height: 1;
        color: var(--details-color-marker);
        transform-origin: 50% 50%;
        transition: var(--details-transition-marker);
        font-family: "FontAwesome";
        content: "\f105";
      }
    }
  }
}

What's Next?

Additional Tools to Explore

SDC Component Library

I recently read an article on the Drupal-SDC-Storybook topic written by Pri Scarabelli for Pivale. It brought to my attention a module called SDC Component Library, which appears to be another Drupal-native component library solution.

After installing the module, all my components are listed on a page at /components (ddev example: my-local-site.ddev.site/components). However, this module requires that each component have a .story.twig file. My themes so far have been set up to use story.yml files rather than story.twig files. I'll have to do some more work to see if using the SDC Component Library module and story.twig files has any advantage.

The display also has some issues for me. It doesn't support my dark mode theme due to the background colors in the display.

screenshot of Skeleton theme SDC Component Library module
The SDC Component Library module will not display my components without a story.twig file, and is illegible due to backgrounds interfering with my dark mode support.

My Drupal Themes

Experimental, Work-in-Progress Drupal 11 Themes

Adobe Spectrum theme screenshot
Drupal Design System

Adobe Spectrum Theme

The Adobe Spectrum design system adapted as a Drupal 11 theme with SDC.
skeleton theme screenshot
Drupal Design System

Skeleton Theme

Skeleton is a work-in-progress, experimental theme for researching SDC and Drupal design systems.
academica theme screenshot
Drupal with Storybook

Academica Theme

Academica is an experimental theme for researching SDC and Storybook for Drupal.
academica theme screenshot
Drupal with UI Patterns

Academica 2 Theme

Academica is an experimental theme for researching SDC and Drupal design systems using the UI Patterns Module.

Drupal Articles

Things I've Written about Drupal

drupal logo, heart, storybook logo
Drupal Design Systems

Your Drupal Site Needs a Storybook Design System

A non-developer’s introduction to Single Directory Components and current best practices in front-end design for Drupal.
symbolic Drual drop shape with symbolic atomic system within
Drupal Design Systems

Designing for Drupal

This illustrated introduction to basic Drupal concepts will help you collaborate with your developers for results that both align with your designs and leverage Drupal's powerful features. Written for the Sparkbox Foundry.

Drupal Videos

Introductory Drupal Development