In Drupal 10 and Drupal 11, the theme layer is responsible for presentation — not business logic. Drupal follows a strict separation of concerns: modules handle data and logic, while themes handle markup and styling. Understanding theme architecture is critical for passing the Acquia Certified Drupal Front End Specialist exam and for working as a senior frontend Drupal developer.

This article explains:

• Required and optional theme files
• How Drupal discovers and registers themes
• The full render flow from request to HTML output
• Where core logic lives
• Drupal 11 compatibility notes
• Exam and interview preparation points

1. How Drupal Loads a Theme

When a request hits Drupal:

1. Routing determines controller.
2. Controller returns a render array.
3. The Renderer service processes it.
4. The Theme Manager selects a theme hook.
5. Twig template renders final HTML.

Core classes involved:

• Drupal\Core\Theme\ThemeManager
• Drupal\Core\Render\Renderer
• Drupal\Core\Extension\ThemeHandler

These live in:

core/lib/Drupal/Core/

Drupal 11 keeps this architecture unchanged.

2. Required Theme Files

A minimal Drupal 10/11 theme requires:

2.1 theme_name.info.yml (REQUIRED)

This is the most important file.

Example:

name: My Theme
type: theme
description: Custom Drupal 10/11 theme
core_version_requirement: ^10 || ^11
base theme: stable9
libraries:
  - my_theme/global
regions:
  header: Header
  content: Content
  footer: Footer

Why Drupal uses it:

• Registers the theme
• Defines regions
• Declares libraries
• Declares base theme

Core parser:

Drupal\Core\Extension\InfoParser

Without this file, Drupal will not recognize the theme.

2.2 theme_name.libraries.yml (Practically Required)

Defines CSS and JS assets.

Example:

global:
  css:
    theme:
      css/style.css: {}
  js:
    js/script.js: {}
  dependencies:
    - core/drupal
    - core/once

Why Drupal uses libraries:

• Asset dependency management
• Conditional loading
• Aggregation support
• Prevent duplication

Core system:

• AssetResolver.php
• LibraryDiscoveryParser.php

Drupal 11 still uses this exact system.

3. Optional but Common Files

3.1 theme_name.theme

Contains PHP logic like preprocess functions.

Example:

function my_theme_preprocess_page(&$variables) {
  $variables['custom_message'] = 'Hello Drupal';
}

Used for:

• Passing variables to Twig
• Adding libraries conditionally
• Altering theme suggestions

Not strictly required — but almost every real theme uses it.

3.2 breakpoints.yml

Defines breakpoints for responsive images.

my_theme.mobile:
  label: mobile
  mediaQuery: '(max-width: 768px)'
  weight: 0

Used with Responsive Image module.

Optional — only needed if using responsive image styles.

3.3 templates/ Directory

Contains Twig files like:

• page.html.twig
• node.html.twig
• block.html.twig
• field.html.twig

Not required initially — but required once you override markup.

4. Base Themes in Drupal 10 & 11

Common base themes:

• stable9 (recommended)
• olivero (frontend-focused)

Declared in info.yml:

base theme: stable9

Why base themes exist:

• Provide stable template structure
• Provide minimal CSS
• Avoid duplicating core markup

Drupal 11 removed legacy themes like Classy.

Exam tip: Know when to sub-theme vs build from scratch.

5. Render Flow (Architect Level Understanding)

Example flow when visiting a node page:

1. Route loads NodeController
2. NodeController returns render array
3. Renderer builds tree
4. Theme hook "node" is invoked
5. Template suggestion selected
6. node.html.twig renders output
7. page.html.twig wraps layout
8. html.html.twig wraps final structure

This layered rendering is why preprocess functions exist.

6. Required vs Optional Summary

7. Why Drupal Uses This Architecture

Drupal uses:

• Render arrays instead of echo statements
• Twig instead of PHP templates
• Libraries instead of inline CSS/JS

Because:

• Enables caching
• Enables security (auto-escape)
• Enables dependency management
• Enables performance optimization

This is why logic must never live inside Twig.

8. Common Mistakes (Exam + Real Projects)

❌ Adding CSS directly inside templates
❌ Using inline JS instead of libraries
❌ Putting heavy database queries inside preprocess
❌ Not defining core_version_requirement correctly
❌ Forgetting dependencies in libraries.yml

9. Interview Questions

1. What is the purpose of the .info.yml file in Drupal 10/11?
2. Explain the difference between render arrays and Twig templates.
3. Why does Drupal use a libraries system instead of inline CSS/JS?
4. When would you create a sub-theme instead of a standalone theme?
5. Explain the rendering flow from controller to final HTML.

10. Exam-Style Questions

Q1: Which file is required for Drupal to recognize a theme?
A. libraries.yml
B. theme.theme
C. theme.info.yml
D. breakpoints.yml

Correct: C

Q2: Where should CSS be defined in a Drupal theme?
A. Inside Twig file
B. Inside theme.info.yml
C. Inside libraries.yml
D. Inside block template

Correct: C

Q3: Which service manages theme suggestions?
A. Renderer
B. ThemeManager
C. FormBuilder
D. ControllerResolver

Correct: B

11. Quick Cheat Sheet

• Required file → .info.yml
• Assets → libraries.yml
• Logic → theme.theme
• Markup → Twig templates
• Rendering → Render arrays → Theme hook → Twig
• Drupal 11 → Same theming system as Drupal 10

Final Thoughts

Mastering theme architecture is the foundation for everything else in Drupal frontend development. Without understanding how Drupal registers, loads, and renders a theme, deeper topics like preprocess functions, template suggestions, and performance tuning will not make sense.