Module 3.1 – Themes and Sub-themes

By saroj 18 December, 2025 Difficulty: Intermediate

Module 3.1 is where Acquia checks whether you can choose the right theming approach in a scenario and implement it using Drupal best practices.

Acquia expects you to understand:

  • When to create a theme vs a sub-theme
  • How themes integrate with render arrays and Twig
  • How to attach CSS and JavaScript correctly
  • How theming decisions affect maintainability, performance, and security

This module is not about visual design. It is about correct Drupal theming architecture.

What a theme is in Drupal

A Drupal theme controls presentation:

  • HTML markup (Twig templates)
  • CSS styling
  • JavaScript behaviors (optional)

A theme does not:

  • Provide business logic
  • Query the database
  • Replace modules

Themes consume render arrays and render them into HTML.

What a sub-theme is

A sub-theme is a theme that inherits from a base theme.

You use a sub-theme to:

  • Reuse the base theme templates and CSS
  • Override only what you need
  • Avoid copying an entire theme

This is the most common and most correct approach for Drupal projects.

Base themes you should recognize

Core provides:

  • Olivero (frontend)
  • Claro (admin)

A site typically uses:

  • A custom theme or sub-theme for the frontend
  • Claro for admin (unmodified)

Exam signal:
If a question mentions modifying core themes, that is usually incorrect.

When to create a custom theme vs a sub-theme

Use a sub-theme when

  • You want to start from an existing theme
  • You need to adjust styling or templates
  • You want faster delivery with less risk

Use a custom base theme when

  • You need a design system that does not fit any base theme
  • You want full control of markup structure
  • You are building a reusable theme for multiple sites

Acquia generally expects a sub-theme unless there is a clear reason not to.

Where themes live

Themes typically live at:

  • web/themes/custom/{theme_name}

Contrib themes live at:

  • web/themes/contrib/{theme_name}

Exam signal:
If the scenario is about project-specific branding, use a custom theme under themes/custom.

Minimal theme structure (what files matter)

A basic theme usually includes:

  • {theme}.info.yml
  • {theme}.libraries.yml
  • {theme}.theme (optional)
  • templates/ directory
  • css/ directory
  • js/ directory

Theme info file (required)

The .info.yml tells Drupal:

  • Theme name
  • Base theme
  • Libraries to load
  • Regions

Example: sub-theme info file

name: My Subtheme
type: theme
description: 'Custom sub-theme for the site.'
core_version_requirement: ^11
base theme: olivero

libraries:
  - my_subtheme/global

regions:
  header: Header
  content: Content
  footer: Footer

Key points:

  • base theme defines inheritance
  • libraries attaches global assets
  • regions define block placement areas

Theme libraries file (CSS and JS)

Drupal loads CSS and JS through libraries.

Example: libraries.yml

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

Why this matters:

  • Correct asset attachment
  • Caching and aggregation support
  • Avoids hardcoding assets in Twig

Exam signal:
If a question shows CSS/JS added directly in Twig, that is usually wrong.

Twig templates (what you override)

Twig templates control markup output.

Common templates:

  • page.html.twig
  • node.html.twig
  • block.html.twig
  • views-view.html.twig

Acquia expects you to know that template suggestions exist and should be used.

Preprocess functions (when needed)

Preprocess functions prepare variables for Twig.

They are used to:

  • Add computed variables
  • Clean data
  • Attach libraries conditionally

They should not contain business logic.

Site Builder perspective (why it matters)

Site builders work with themes indirectly through:

  • Block placement in regions
  • View modes and display configuration
  • Layout Builder

A well-designed theme supports site builders by:

  • Providing clear regions
  • Supporting view modes
  • Avoiding hardcoded assumptions

Frontend developer perspective (HTML, CSS, JS)

Frontend developers in Drupal:

  • Work with Twig and render arrays
  • Apply CSS to theme output
  • Add JS through libraries and behaviors

They must keep Twig simple and rely on configuration for display differences.

Git and deployments (why themes matter)

Themes are code.

That means:

  • Theme files go into Git
  • Theme changes go through deployment

Site builder changes (blocks, views) usually go through configuration export.

Exam signal:
If a change needs a deployment, it is code (theme/module).

Real scenario: When a custom theme is needed

Scenario:
A healthcare site has a strict design system. The marketing team requires pixel-consistent layouts, custom typography, and reusable components.

Correct approach:

  • Build a custom theme or sub-theme
  • Use view modes for consistent rendering
  • Override templates where necessary

Incorrect approach:

  • Hardcode HTML in content fields
  • Use WYSIWYG for layout control

Real scenario: Why a sub-theme is often best

Scenario:
A government site needs branding updates and minor layout adjustments but should remain close to core accessibility patterns.

Correct approach:

  • Create a sub-theme of Olivero
  • Override only templates and styles needed

Incorrect approach:

  • Copy Olivero into custom theme and modify

Decoupled and headless context (awareness)

In decoupled/headless setups:

  • Drupal theming is reduced or not used
  • Drupal provides JSON via REST
  • Frontend is built separately (React, Next.js)

Key point:

  • Module 3.1 exam questions focus on traditional Drupal theming
  • Headless affects the decision of whether you theme at all

Scenario:
If Drupal only provides APIs, a custom theme may be unnecessary.

Performance considerations

Good theming supports performance:

  • Use libraries for assets (aggregation)
  • Avoid inline CSS/JS
  • Avoid heavy Twig logic
  • Reuse view modes

Bad theming hurts performance:

  • Duplicated templates
  • Inline assets
  • Large unoptimized images

Security considerations

Twig escapes output automatically.

Theme security best practices:

  • Never trust user input
  • Avoid raw output filters unless necessary
  • Keep logic in modules

Exam signal:
If the scenario involves validation or access control, it is not a theming solution.

Common exam traps in Module 3.1

  • Modifying core themes directly
  • Adding CSS/JS directly in Twig
  • Using Twig for business logic
  • Using multiple content types to achieve different layouts
  • Duplicating templates instead of using view modes

Correct answers favor:

  • Sub-themes
  • Libraries
  • View modes
  • Clean separation

Practice check

  • Need branding and minor overrides: sub-theme
  • Need completely custom markup system: custom base theme
  • Need JS/CSS: libraries.yml
  • Need to pass extra variables to Twig: preprocess
  • Need different display for listings vs pages: view modes