Component-Based Design in Drupal

Component-based design (CBD) is a cornerstone in building scalable, maintainable, and efficient modern websites. It's a transformative methodology that aligns with Drupal's modular architecture and positions Drupal theming philosophy amongst the most recent best practices in architecting user interfaces.

Understanding how Component-based design works and how to implement it will supercharge (and transform) website building process. We will delve into the principles, tools, implementation strategies, best practices, and future directions on how to create reusable, consistent, and high-performing components backing Drupal websites, and we will also also go over Varbase Component-based design features.

What is Component-Based Design?

Component-based design is a modern methodology that breaks user interfaces down into small, reusable, and independent building blocks called components. Components can be buttons, cards, navigation bars, or hero sections. Inspired by principles of atomic design, CBD components are treated as LEGO bricks that you design once and reuse anywhere.

The main philosophy behind CBD is modularity; instead of designing an entire page from scratch, you assemble pages using pre-built components.

By following this UI architecture, we emphasize and promote the four pillars:

• Consistency: Uniform styling and behavior across the site.
• Efficiency: Faster development and easier updates to UI elements.
• Collaboration: Designers and developers can work in tandem, often using tools like Storybook.
• Scalability: CBD is ideal for large websites as components can be versioned and tested independently.

Additionally, Drupal's backend modularity through blocks, views, and entities is now backed by a modular frontend emphasizing the concept of Don't Repeat Yourself.

The Evolution of Component-Based Design in Drupal

Pre-Drupal 8, theming was template-heavy and monolithic. With Drupal 8 adoption of Twig as a templating engine, UI marked a turning point in Drupal by enabling a much cleaner and component-like structure.

By Drupal 9 and 10, contributed modules like UI Patterns and Emulsify paved the way for true CBD effect. A major milestone came with Single Directory Component (SDC), which also started as a contributed module and was integrated into Drupal 10.3 core in 2024. This update made CBD a first-class feature in Drupal, allowing components to bundle Twig templates, CSS, and JS in a single directory.

In 2025, Drupal introduced supporting variants through root-level configuration, enabling developers to define multiple styles or behaviors for a single component without duplication. And with Drupal's AI integration, AI agents are able to create component on-demand, which is a game-changer in rapid prototyping that the near future will show.

A notable theme that accelerated CBD with a modern component-driven structure was the Space Design System. Drupal is aiming to bridge the gap between designers and developers and move away from siloed collaboration workflows with a component-first approach.

Drupal vs React: A shared Mindset

While both Drupal and React are fundamentally different - React components run in a JS runtime while Drupal's SDS components are rendered server-side with Twig - they share the same fundamental philosophy in component-based design: define it once, and reuse it anywhere. React developers create reusable components using JSX, encapsulating markup, logic, and style with a single unit. In

Drupal's Single Directory Component (SDC) approach, the concept is remarkably similar; the Twig template, YAML configs, CSS, and JS are bundled together in one directory.

Both approaches promote

• Encapsulation: All files and logic related to the UI piece are bundled together.
• Reusability: Components can be reused across different pages, projects, or applications.
• Consistency: Design tokens, styles, and language remain uniform.
• Scalability: Teams can manage larger codebases by working on independent components.

Key Tools and Modules for Component-Based Design in Drupal

Drupal has a vibrant CBD ecosystem from core to community

Core

• Single Directory Components (SDC): Each component lives in its own directory with a .component.yml file defining props (data inputs) and slots (content placeholders).
• Twig Templating: Drupal's engine for rendering components.

Contrib Modules

• Components Module: Registers Twig namespaces for themes and modules, organizing components hierarchically.
• UI Patterns: Exposes patterns as field formatters, blocks, or layouts, integrating seamlessly with Layout Builder.
• Emulsify: A Storybook integration for Drupal, allowing designers to build and test components in isolation.
• Site Studio (Acquia): A low-code/no-code tool for creating component-based design systems, ideal for enterprise sites.

Integrations

• Storybook: Pair it with Drupal for a design system hub, where components are documented and prototyped.
• Layout Builder: Assemble pages using components as blocks, enhancing modularity.

Implementing Component-Based Design: A Step-by-Step Guide

Let's walk through creating and using a simple card component in Drupal using SDC.

1. Set Up Environment: Ensure you're on Drupal 11.2+ for native variant support (SDC itself is available from 10.3+, but variants were added in 11.2.0 released in June 2025). If using an earlier version, enable the SDC module and consider simulating variants via a custom 'variant' prop.

2. Create the Component Directory: In your theme's /components folder, make a /card directory. Inside, add:

• card.component.yml: Defines metadata, including variants for grouped configurations with titles and descriptions.

name: Card
template: card
library: mytheme/card
variants:
  default:
    title: Default
    description: The standard light mode card.
  dark:
    title: Dark Mode
    description: A dark-themed variant for low-light environments.
props:
  title:
    type: string
  content:
    type: string
slots:
  image:
    title: Image Slot

• card.twig: The template, using the variant to conditionally apply styles (e.g., classes).

<div class="card{% if variant and variant != 'default' %} card--{{ variant }}{% endif %}">
  <h2>{{ title }}</h2>
  {% if image %}
    {{ image }}
  {% endif %}
  <p>{{ content }}</p>
</div>

• card.css and card.js: Optional styles and scripts (e.g., define .card--dark in CSS for dark mode).

3. Register the Component: Drupal auto-discovers SDC in themes. Attach the library in mytheme.libraries.yml.

4. Render the Component: In a Twig file:

{% embed 'mytheme:card' with {
  variant: 'dark',
  title: 'My Card',
  content: 'Lorem ipsum.'
} only %}
  {% block image %}
    <img src="https://www.vardot.com/image.jpg" alt="Image">
  {% endblock %}
{% endembed %}

Or in PHP:

$build = [
  '#type' => 'component',
  '#component' => 'mytheme:card',
  '#variant' => 'dark',
  '#props' => [
    'title' => 'My Card',
    'content' => 'Lorem ipsum.',
  ],
];

The variant is injected as a prop (props.variant), allowing conditional logic in the template without breaking existing components.

5. Integrate with Layout Builder: Expose the component as a block for drag-and-drop page assembly, where variants can be selected via configuration options.

Best Practices for Component-Based Design in Drupal

• Follow Atomic Design principles: Start with atoms (buttons), then build molecules (forms), then evolve to organisms (headers), and then templates/pages.
• Document Everything: Use Storybook or Drupal's docs for component libraries.
• Version Control: Treat components as code.
• Performance Optimization: Lazy-load JS/CSS, minify assets.
• Accessibility: Integrate keyboard navigation into components from the beginning
• Test: Unit test components with PHPUnit or Storybook's interaction tests.
• Collaborate: Developers and designers collaborate early on. Tools like Emulsify allow frontend work without backend dependency.
• Don't over-complicate: Not everything needs to be a component; maintain a balance of reusability and simplicity.

Benefits of CBD

• Faster iterations: Breaks down silos and saves time on redesigns.
• Consistency: In large teams/projects
• Cost efficiency: Reusability reduces development hours by reusing components across projects.

Challenges and Solutions

• Learning Curve: Twig and YAML can be intimidating at the beginning - you can start with Acquia's Site Studio.
• Integration with Legacy Code: Older Drupal sites may need code refactoring.
• Performance: Too many components can bloat renders, utilize caching.
• System Maintenance: Keep components updated by using automation tools.

Varbase Storybook and Varbase CBD

Varbase, our Drupal distribution, embraces CBD; it integrates modern frontend workflows right out of the box. With Varbase Storybook, designers and developers can collaborate and visually build, document, and test components before integrating them into Drupal pages.

Varbase CBD extends a ready-made library of reusable components following SDC standards, which accelerated our project delivery, as well as enforced design consistency and maintainability across websites. The combination of Varbase Storybook and Varbase CDB brings a joyful starting point for building more UI optimized components for our projects in a full Drupal-native environment.

Photo by Markus Spiske