Creating a Drupal 11 Theme with Single Directory Components

Single Directory Components (SDC) in Drupal 11 provide a component-first approach to theming that keeps templates, styles, scripts, and metadata together in one place. This structure improves maintainability, encourages reuse, and reduces the friction between backend rendering and frontend design systems.

What Single Directory Components Are

Single Directory Components group everything needed to render a UI component inside a single folder. A typical component includes a Twig template, optional CSS/JS, and a component definition file that documents properties and enables tooling support.

SDC aligns well with modern frontend practices: components become portable building blocks, and component APIs become explicit through defined props.

Why SDC Helps Theme Development

• Consistency: Component conventions reduce ad-hoc theming patterns across templates.
• Encapsulation: Styles and markup live together, limiting unintended cross-component side effects.
• Reusability: Components can be used across node templates, views, blocks, and layout sections.
• Documentation: Component metadata makes intended usage and inputs clear.
• Team workflow: Backend and frontend work can converge on stable component interfaces.

Theme Structure for SDC

A Drupal 11 theme can adopt SDC by creating a dedicated components directory. The exact structure can vary, but a clear convention helps long-term scalability.

Example component-oriented structure:

• themes/custom/example_theme/
  • example_theme.info.yml
  • example_theme.libraries.yml
  • components/
    • button/
      • button.twig
      • button.component.yml
      • button.css
      • button.js
    • card/
      • card.twig
      • card.component.yml
      • card.css
  • templates/
  • css/
  • js/

Component folders contain only what the component needs. Global assets remain possible, but SDC encourages moving UI-specific assets closer to the template that requires them.

Defining a Component

An SDC component typically includes:

Twig template

Defines markup and consumes props passed to the component.

Component definition file

Declares props and component metadata for discoverability and validation.

Optional CSS/JS

Scoped assets that implement the visual and behavioral aspects of the component.

Component Metadata and Props

A component definition file documents the component API. Keeping prop names stable and meaningful reduces theme coupling and simplifies refactoring.

• Prefer explicit props such as label, url, variant, icon.
• Use safe defaults for optional props to prevent rendering edge cases.
• Constrain variants to a known set (example: primary, secondary, ghost) for predictable styling.

Rendering Components in Twig

Once components exist, templates can be refactored to compose pages from smaller parts. This approach works well for node templates, field templates, Views templates, and layout templates.

Practical guidance for component composition:

• Keep components small and focused on a single UI responsibility.
• Avoid embedding business logic in components; perform data shaping upstream.
• Pass only what is needed to keep component APIs clean.

Example: Card Component Usage

A card component can accept props such as title, summary, image, and link. Node and View templates can map Drupal render arrays or fields into these props, resulting in consistent UI across multiple contexts.

Managing Assets with SDC

SDC supports component-level assets, improving maintainability by keeping styles and scripts close to their usage. Several patterns can work in Drupal 11 themes:

• Component-local CSS/JS for encapsulated behavior and styling.
• Shared utilities for layout primitives, typography scales, and tokens.
• Hybrid approach where global foundation styles remain global, while component styling stays within components.

Recommendations for CSS Organization

• Use a naming convention such as BEM or a utility-first approach, and apply it consistently.
• Prefer low specificity to reduce conflicts and ease overrides.
• Isolate variants with modifier classes rather than deeply nested selectors.

Mapping Drupal Data to Component Props

Drupal content often arrives as render arrays, fields, and preprocess variables. The goal is to translate these into clean component props.

• Preprocess functions can normalize data, set defaults, and compute variants.
• Field templates can pass field values into components for consistent rendering.
• View modes can provide predictable data shapes per context (teaser vs full).

Preprocess Strategy

Prop shaping belongs in preprocess layers rather than inside Twig. This keeps Twig focused on presentation and reduces duplication across templates that share the same component.

Component Documentation and Governance

SDC becomes significantly more valuable when treated as a theme-level design system. A small amount of governance prevents component sprawl.

• Define component categories such as atoms (button), molecules (card), and organisms (header).
• Write prop descriptions and keep examples of expected values.
• Set deprecation practices when prop names or variants need to change.

Principle: A component should be easier to reuse than to reimplement.

Testing and QA Considerations

Component-driven theming can improve QA by making UI behavior more predictable.

• Visual review: verify components in multiple contexts (node, view, block).
• Accessibility: ensure correct semantics, focus states, and keyboard support.
• Performance: avoid unnecessary JS per component; prefer progressive enhancement.

Accessibility Checklist for Common Components

• Buttons and links use correct elements for intent.
• Images provide meaningful alternative text when appropriate.
• Interactive elements include visible focus and work without a mouse.

Migration Path: Refactoring an Existing Theme

Adopting SDC does not require a full rewrite. A gradual approach reduces risk.

1. Start with one or two shared components such as buttons and cards.
2. Refactor the highest-traffic templates to consume components.
3. Consolidate variants and remove duplicated markup across templates.
4. Move component-specific CSS out of global stylesheets where feasible.
5. Document component APIs and enforce consistent usage.

Common Pitfalls

• Over-componentization: creating components for trivial markup can increase complexity.
• Leaky abstractions: passing entire render arrays into components instead of clean props.
• Inconsistent variants: multiple names for the same visual intent.
• Global CSS overrides: high-specificity rules that undermine encapsulation.

Conclusion

Single Directory Components in Drupal 11 enable a modern, scalable theming workflow built on reusable UI building blocks. By defining clear component APIs, keeping assets close to templates, and shaping Drupal data into clean props, a theme can evolve into a maintainable design system that supports long-term site growth.

SDC rewards incremental adoption: begin with foundational components, standardize patterns, and expand the library as repeated UI needs emerge.