Component-based design in Drupal: SDC, Canvas & AI

Component-based design (CBD) breaks a user interface into small, reusable building blocks, designed once and reused anywhere. In Drupal, it is delivered through Single Directory Components (SDC), stable in core since Drupal 10.3 and extended with component variants in Drupal 11.2. SDC also underpins Drupal Canvas, the visual page builder whose AI Assistant assembles pages from your existing components, which makes a well-built component library a foundation for both consistency and AI-driven authoring.

What is component-based design in Drupal?

Component-based design is a methodology that breaks a user interface into small, reusable, and independent building blocks called components, such as buttons, cards, navigation bars, or hero sections. Drawing on atomic design principles, each component is built once and reused anywhere, so a page is assembled from pre-built parts instead of being designed from scratch. Drupal pairs this modular front end with its long-standing backend modularity of blocks, views, and entities.

Component-based design rests on four practical benefits for a Drupal team:

• Consistency: uniform styling and behavior across the whole site.
• Efficiency: faster development and easier updates to shared UI elements.
• Collaboration: designers and developers work in parallel, often through a tool like Storybook.
• Scalability: components are versioned and tested independently, which suits large sites.

What are Single Directory Components (SDC)?

Single Directory Components (SDC) are Drupal's native way to build components, where everything a component needs lives in one directory: a Twig template, a .component.yml file that defines its props (data inputs) and slots (content placeholders), and optional CSS and JavaScript. 

SDC became stable in Drupal core in version 10.3 in 2024, so themes and modules can use components without enabling any extra module. Drupal 11.2 added first-class component variants, letting one component define multiple named styles without duplication.

How did component-based design evolve in Drupal?

Component-based design in Drupal evolved from monolithic templates to a core feature over roughly a decade. Before Drupal 8, theming was template-heavy and repetitive. Drupal 8's adoption of Twig was the turning point, enabling a cleaner, component-like structure.

Through Drupal 9 and 10, contributed modules including UI Patterns and Emulsify proved out the approach. The milestone was Single Directory Components, which started as a contributed module and was merged into Drupal 10.3 core as a stable feature in 2024, bundling a component's Twig, CSS, and JavaScript in one place. Drupal 11.2 then added component variants in 2025, closing a long-standing gap that had forced developers into workaround patterns.

The most consequential step came at the end of 2025. Drupal Canvas (formerly Experience Builder) reached version 1.0 in December 2025, built directly on SDC, giving site builders a visual, drag-and-build interface for assembling pages from components. 

Canvas also ships an AI Assistant that takes a plain-language prompt, scans the site's library of Single Directory Components, and selects and places them to build the requested layout. Component-based design is no longer only a developer practice in Drupal; it is the substrate that visual and AI authoring now run on.

How is Drupal's SDC approach like React components?

Drupal's SDC approach and React share one core philosophy: define a UI piece once and reuse it anywhere, while differing in where and how they render. React components run in a JavaScript runtime; Drupal's Single Directory Components render server-side through Twig. The table below maps the two side by side.

How do you create a component with Single Directory Components?

You create a Single Directory Component by adding a component directory to your theme, defining its schema in a YAML file, and rendering it from Twig or PHP. The steps below build a simple card component with a light and a dark variant.

1. Check your Drupal version. SDC is available from Drupal 10.3, but native component variants require Drupal 11.2 or later (variants shipped in 11.2.0 in 2025). On earlier versions, simulate a variant with a custom variant prop.

2. Create the component directory. In your theme's /components folder, create a /card directory and add a card.component.yml file that defines metadata, variants, props, and slots:

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

Add a card.twig template that applies the variant as a modifier class, plus optional card.css and card.js for the styles and behavior:

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

3. Render the component. Drupal auto-discovers SDC in themes, so you can embed the component directly in a Twig template:

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

Or render it from PHP with a component render element, passing the variant through the #variant key:

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

You can cache at the component level by attaching cache metadata to the render array with the #cache property. This gives granular control through cache tags (invalidate on specific entity or data changes), cache contexts (vary by user role or language), cache keys (unique identifiers), and max-age (time-based expiration), which keeps a component-heavy page fast.

Our view: your component library is now the substrate your AI builds from

Our view: as a Drupal AI Initiative Gold Sponsor, Vardot watches this shift closely, and the change is real. With Drupal Canvas and its AI Assistant now assembling pages from your Single Directory Components, a component library has stopped being a developer convenience. 

It has become the material your site's authoring, both visual and AI-driven, is built from. The teams that benefit most are not the ones with the most components. They are the ones whose components are well-described, accessible, and governed, because an AI agent can only assemble what it can understand, and a marketer in Canvas can only reuse what is documented and consistent.

This reframes where the effort goes. In our work building component libraries on Varbase, the value compounds less from writing more components and more from the metadata and discipline around them: a precise component name and description, a clear schema, accessibility built into the markup, and design tokens that keep everything visually consistent. 

Those were once nice-to-haves for developer experience. With AI selecting components from their descriptions, they are now the difference between a library an agent can build with and one it cannot.

What makes a Drupal component library ready for Canvas and AI?

A component library is ready for Canvas and AI when its components are described, accessible, consistent, documented, and governed, not just functional. Use the checklist below to evaluate a library against that bar.

• Rich descriptions and schema: give every component a clear name, description, and complete prop and slot schema, so both Canvas authors and AI agents can find and use it correctly.
• Accessibility built in: bake keyboard navigation, semantic markup, and focus handling into each component from the start, so accessibility is inherited by every page that reuses it rather than retrofitted per page.
• Design tokens and consistency: drive color, spacing, and typography from shared tokens, following atomic design from atoms to organisms, so reuse stays visually uniform.
• Documentation in Storybook: build and test components in isolation in Storybook, giving designers, developers, and reviewers one source of truth.
• Versioning and governance: treat components as code, with version control, tests (PHPUnit or Storybook interaction tests), and a review process so the library stays trustworthy as it grows.
• Performance discipline: apply component-level caching, lazy-load assets, and avoid over-componentizing, since not every element needs to be a component.

How Vardot builds component-based design into Varbase

Vardot builds component-based design into Varbase, its Drupal distribution, so enterprise projects start with the discipline above already in place. Varbase Storybook lets designers and developers visually build, document, and test components before they reach a Drupal page, and Varbase CBD ships a ready-made library of reusable components built to SDC standards. 

In practice, this shortens delivery time and enforces design consistency and accessibility across large, multilingual sites, which is exactly the foundation an AI-assisted authoring workflow needs to be reliable. It is the same component discipline behind enterprise builds for organizations like UNHCR and Al Jazeera, delivered through Vardot's delivery system, Align, Blueprint, Accelerate, Assure, and Operate.

Component-based design has moved from a theming trend to the layer that Drupal's visual and AI authoring now depend on. If you are planning a new Drupal build or modernizing an existing theme, the component library is the investment that pays back across every page, every channel, and now every AI-assembled layout. That is the work Vardot does with enterprise teams on Varbase.

Photo by Markus Spiske