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, to my great excitement, 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.
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:
- PatternLab - patternlab.io/
- Storybook - storybook.js.org/
UI Suite
What is the UI Suite?
Design System Library Tools Inside of Drupal
The Design System Initiative has developed the UI Suite, a collection of Drupal modules which facilitate building a Drupal design system.
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
UI Suite Resources
- UI Suite @Drupal.org
- UI Patterns @Drupal.org
- UI Styles @Drupal.org
- UI Skins @Drupal.org
- 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.
My UI Suite Research
Experimental Themes
I have multiple experimental themes in progress which utilize the UI Suite.
Adobe Spectrum
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.
Academica 2
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
Skeleton
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
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:
- The full library of components and how they display
- How the components can be combined
- Variants of each component
- Documentation about how they should be used
- 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.
Storybook Resources
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
📁 Storybook Component
- component.twig
- component.css
- component.js
- component.yml
component.stories.js(not needed with the add-on!)
SDC-Addon Resources
My Drupal Storybook and SDC-Addon Research
I spent some time researching this method 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.
This 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.
You can see how far I got in my experimental theme repos:
Emulsify
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
SDC Styleguide and Shared Components
Drupal architect Alejandro Madrigal Leiva built the SDC Styleguide as a design system component library solution (alternative to Storybook and UI Patterns).
He is also working 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.
I'm excited about Alejandro's work and I have enjoyed testing his tools with my Skeleton theme.
The idea that we may be able to build individual components and share them with our community is especially innovative. This could help improve our accessibility and save time and frustration for new Drupal developers who may be unfamiliar with how to build an SDC component.
SDC Styleguide
Sharable Single Directory Components
My Drupal Themes
Experimental, Work-in-Progress Drupal 11 Themes
Drupal Articles
Things I've Written about Drupal
Drupal Videos
Introductory Drupal Development