Modernize Drupal theming with Single Directory Components. Improve DX, reuse UI components, and build scalable design systems with SDC.
While Drupal can handle the backend beautifully, it isn’t as flexible in terms of its frontend capabilities. Drupal theming has been an area long untouched by a radical update. There are a lot of contributed modules available for making the workflow easier, but the out-of-the-box approach has remained more or less the same.
We need a new way of organizing code for Drupal theming that can be more maintainable with a minimal learning curve. Earlier, template discovery relied on Drupal Twig template suggestions and enabling debug modes. Styles and scripts often lived in different locations, attached inconsistently through libraries or preprocess functions. As the frontend world moved toward component‑driven design systems and headless architectures, Drupal’s traditional theme layer lagged behind. Was it really sustainable to keep scaling projects on top of scattered templates and loosely connected assets?
The Single Directory Components (SDC) initiative marks a major breakthrough in Drupal’s evolution. With SDC, Drupal finally embraces a component-based approach that is modern, predictable, and aligned with the expectations of today’s frontend developers.
One of the key practical advantages of this approach is that with the help of SDC, we can allow the frontend to get started without the backend and without deep knowledge of Drupal specifics. We can implement and test UI features quickly, even without the backend involvement, and we can integrate components directly into Storybook or other component library managers.
Importantly, SDC enhances the workflow without disrupting the overall development approach. Each component is self-contained, with its template, styles, and scripts located in a single directory. There is no need to use Twig debug to find the template, search for the relevant CSS or JS file.
The structure also makes data expectations explicit — it’s very clear what data is expected in a component and what data is mandatory. As a result, the frontend team can take responsibility for component structure and discovery.
Single Directory Components is a part of Drupal Core that allows to integrate component-driven architecture into Drupal sites. It simplifies management and code navigation, which is especially useful for large-scale Drupal projects.
Component-based architecture is an approach where the user interface is built using encapsulated elements called “components”. Each component works independently and can be reused throughout the application. This approach is considered a modern way to implement the Design System and establish a DesignOps workflow.
Single Directory Components is a system that lets you define all parts of a component — template, styles, scripts, and component data (props/slots) — inside a single folder.
In earlier Drupal approaches, a component’s Twig template, styles, and scripts could live in different locations and be attached in different ways — for example, through libraries or preprocess functions. This separation made it harder to understand how a component was built and where its pieces were defined.
With SDC, everything related to a component is co-located. An SDC component typically includes Twig, YAML, CSS, and JavaScript files stored together in one directory. Grouping all rendering logic and assets in a single place improves clarity, simplifies maintenance, and makes components easier to reuse and scale across the project.
Each component is described using a YAML plugin. Component metadata is stored in the <module_name>.component.yml file, which describes the structure and libraries of the component. SDC also automatically generates a Drupal library to load CSS/JS when the template is invoked.
A component in SDC is built using Twig’s native functions, such as include, embed, or extends. This allows you to simply call the component inside Twig and pass it the necessary data:
This approach makes development more structured, predictable, and convenient for frontend developers.
An example component folder might look like this:
In addition to templates and assets, each SDC component is defined through a YAML metadata file that describes its structure and behaviour. The SDC component YAML file is required in every component directory, although it can remain empty. It is used to define configuration details such as component name, grouping, props, slots, and library overrides.
Props are structured as an object with defined keys. Each key represents a variable used inside the component template and controls either how the component’s appearance — for example, variations — or what data is rendered inside it.
Slots allow free markup to be passed into the component, so they do not require a predefined schema.
An SDC component is a Drupal plugin responsible solely for defining how a specific UI element is rendered. Components can belong to either a module or a theme. By encapsulating markup, logic, and assets within a single location, SDC helps standardise UI elements and reuse without requiring additional custom Drupal-side logic.
SDC Component and Entity View Display SDC allows components to accept props that are not limited to simple data types, such as strings or numbers. Components can also reference other components at a lower level, enabling the creation of a hierarchical structure of component: organism -> molecule -> atom.
Entity View Display settings make it possible to map entity fields and attributes directly into component props. This makes SDC a powerful and flexible tool for building and customizing page elements using standardized, reusable components.
Previously, it was not possible to assign component props directly to Drupal fields through configuration. If you needed to pass specific values into a component, you had to create a dedicated Twig template — often via a theme suggestion — and manually map the field values inside that template. This meant additional template files, more boilerplate code, and tighter coupling between field rendering and theme-layer overrides.
As a result, even simple presentation changes required creating new Twig templates and explicitly passing variables, instead of configuring the mapping at the display level.
With SDC, Drupal introduces a clear standard for component-based software architecture.
Pre-backend verification becomes possible, improving cross-team collaboration by allowing designers and developers to review and approve components before backend implementation begins.
This also helps reduce bugs and inconsistencies. Development workflows become simpler, and designers can validate the final look and feel early, since layouts built in Storybook closely match the final implementation inside Drupal.
Drupal theming needed a more predictable and structured approach. Single Directory Components provided that foundation.
Before SDC, finding the correct Twig template often required enabling debug mode, checking suggestions, and searching across theme folders. With SDC, you declare the component explicitly, and Drupal knows exactly where it lives.
The outcome is a more predictable theming workflow, eliminating the need for:
Instead, components become predictable and discoverable.
Previously, developers could attach CSS and JavaScript however they wanted via libraries, preprocess functions, or even custom modules. This flexibility often resulted in inconsistency and difficulty understanding where scripts and styles came from.
SDC unifies everything. Each component has:
This structure mirrors modern frameworks like React, Vue, and Web Components, where each component is a self-contained unit.
While Drupal is not headless by default, SDC feels like a step toward a headless architecture. Components behave like frontend bundles that are easy to find, reuse, and understand.
As a result, Drupal frontend developers get many benefits:
In other words, Drupal is still coupled, but the developer experience is significantly closer to headless frameworks.
One of the most powerful features is the ability to assign components directly to render arrays, bypassing the need for theme-level Twig templates entirely.
For example, instead of creating a custom template for a block or field, you can:
Drupal takes care of locating the component and rendering it properly.
This simplifies:
SDC brings strong advantages for teams:
This leads to better developer experience and cleaner projects overall.
SDC brings Drupal theming into a more modern era by introducing a stronger focus on:
Instead of treating UI as a collection of loosely connected templates and assets, SDC allows developers to build interfaces as structured, self-contained units.
For the first time, Drupal theme developers can work with components in a way that is closer to modern JS frameworks. So, everything is in one place, consistent, and logical.
SDC is not just a feature — it represents a new standard for building Drupal projects and improving long-term development sustainability.
The introduction of Single Directory Components is one of the most important advancements in Drupal’s theme system. It finally brings a component-based architecture that aligns with modern development practices, reduces complexity, and dramatically improves clarity and maintainability. Where we previously relied on template suggestions, scattered assets, and inconsistent patterns, SDC introduces structure and sanity. It also positions Drupal as a platform ready for design systems and hybrid/headless workflows.
And this is exactly where a structured design system becomes not just helpful, but strategic. SDC gives the technical foundation, but without a clearly defined component library, governance rules, naming conventions, and scalable architecture, teams can still fall back into chaos over time.
At Attico, we help companies build full-scale design systems on top of Drupal’s modern capabilities. It’s a clear system with shared component logic, proper documentation, usage rules, and a strong connection between Figma, Storybook, and the frontend architecture. Our team helps turn SDC from just a technical feature into a practical tool that supports business growth.
For large brands and multi-brand projects, this is especially important. The Attico specialists build the system in a way that it can grow with the business. New pages, landing pages, and features can be assembled much faster instead of being redesigned and rebuilt from scratch every time.
