Theming is where a Drupal site stops being a data model and starts being something a person uses. It is also the layer most often underestimated, because from the outside it looks like CSS — and a great deal of the work is not CSS at all.
A Drupal theme decides what markup gets produced, how content is grouped, what a screen reader announces, what loads before the first paint, and how much of the design a content editor can accidentally break. Those are structural decisions, and they are hard to reverse once a site is live.
This page covers how Drupal theming actually works, the decisions that determine whether a theme survives its first redesign, and where the line sits between work a front-end developer can own and work that needs Drupal-specific knowledge.
What Drupal Theming Actually Involves
A theme in Drupal is responsible for four things:
- Templates — Twig files that turn structured data into markup.
- Libraries — the CSS and JavaScript, declared so Drupal can attach them only where needed.
- Preprocessing — PHP that prepares variables before a template renders them.
- Regions and layout — the named areas a site builder can place blocks into.
What a theme is not responsible for is business logic, access control, or data retrieval. Those belong in modules. Every time that boundary is crossed, the site becomes harder to re-theme later, because logic has to be found and moved before the design can change.
Why Theming Is Not Just CSS
You can style an existing Drupal site with CSS alone, and for small changes that is the right answer. The moment the requirement is "this content should be arranged differently" rather than "this should look different", you are in template territory.
The distinction matters because CSS-only solutions to structural problems tend to be fragile. Reordering visually with flexbox order while leaving the DOM in the original sequence means keyboard users tab through the page in an order that no longer matches what they see. Hiding elements with display: none still sends them to the browser, and screen readers may or may not announce them depending on how it was done.
Structural problems want structural fixes, which means templates.
Start From a Base Theme, Not From Scratch
Drupal core ships base themes, and the contributed space offers many more. Starting from one gives you accessible defaults, a sensible region structure, and years of edge cases already handled.
Building a theme from nothing is occasionally the right call for a heavily bespoke design, but it means owning every detail a base theme would have given you: form element markup, status message regions, pagers, breadcrumbs, and the accessibility behaviour of each. That is a lot of surface to maintain for the sake of a clean starting point.
A sub-theme lets you override precisely what needs to change and inherit the rest, which also means core improvements to the base theme reach your site instead of stopping at your custom code.
Twig Templates and the Naming System
Drupal chooses templates through a suggestion system, from most specific to most general. A node might look for node--article--teaser.html.twig, then node--article.html.twig, then node--teaser.html.twig, then node.html.twig.
Understanding this ordering is what separates a theme that overrides one thing from a theme that accidentally overrides everything. Copying node.html.twig into your theme to change how one content type displays means every node on the site now renders through your copy — including future content types nobody has created yet.
Enabling Twig debugging during development prints the candidate template names into the HTML source as comments, which removes the guesswork entirely:
FILE NAME SUGGESTIONS:
* node--article--teaser.html.twig
* node--article.html.twig
x node.html.twigRender Arrays Are the Contract
Drupal does not build HTML strings and pass them around. It builds nested arrays describing what should be rendered, and converts them to markup at the last possible moment.
This matters in the theme layer because a render array carries more than content. It carries cache metadata, attached libraries, and access information. Flattening one to a string too early — a common instinct when something is hard to style — discards all of that.
The practical rule: manipulate the array, do not render it early. If a template needs a value in a different shape, prepare it in preprocess rather than rendering markup and parsing it back.
Preprocess Functions: Useful, and Easy to Abuse
Preprocess functions let you add or modify variables before a template runs. They are the correct place to compute something a template needs.
They are also where business logic quietly accumulates. A preprocess function that queries the database, checks a user's role, and decides what to display has become a module in the wrong file. It cannot be tested, it will not be found by anyone reading the module layer, and it disappears the day the site is re-themed.
A good test: if the logic would still be needed with a completely different design, it does not belong in the theme.
Libraries: How CSS and JavaScript Should Be Attached
Drupal expects assets to be declared as libraries and attached where they are needed, rather than loaded globally:
global-styling:
css:
theme:
css/base.css: {}
js:
js/behaviors.js: {}
dependencies:
- core/drupal
- core/onceAttaching a library to a specific template or render array means it loads only on pages that use it. Dumping everything into a global library is simpler on day one and gets steadily more expensive, because every page pays for every feature.
The core/once dependency is worth calling out: it is the supported way to ensure JavaScript initialises an element exactly once, which matters because Drupal re-runs behaviours after AJAX. Code that binds handlers without it accumulates duplicate listeners as a user interacts with the page.
Component Thinking in a Drupal Theme
Modern front-end work is organised around components, and Drupal accommodates this well — a component is a Twig template, a CSS file, and optionally a JavaScript file, kept together and attached as a library.
The friction comes from Drupal's rendering model, which is field-based rather than component-based. Bridging that means deciding deliberately where components map onto Drupal's structures: view modes, field formatters, paragraph types, or layout regions. Made deliberately, that mapping is a genuine architecture. Left implicit, the theme becomes a collection of one-off overrides.
Accessibility Is a Theming Responsibility
Most accessibility outcomes are decided in the theme, because the theme decides the markup.
The things that matter most are unglamorous: a heading order that descends without skipping levels, form labels genuinely associated with their inputs, focus states that are visible and not removed for aesthetics, link text that means something out of context, and images marked decorative when they are decorative rather than given invented alt text.
That last one is worth stating clearly, because it is usually done backwards: a purely decorative image should carry alt="", which tells assistive technology to skip it. Inventing a description for a background texture adds noise for the people relying on it.
Automated tools catch perhaps half of what matters. Keyboard-only navigation through a page finds most of the rest in about five minutes: tab from the top and check that focus is always visible, that the order matches the visual layout, that nothing traps you, and that any menu or dialog can be opened and closed without a mouse.
Colour contrast is the other half-hour worth spending, and it is best settled while the design is still a design. Retrofitting contrast onto a brand palette after launch means either changing the brand or accepting an exception, and neither conversation improves with age.
If your own theme is missing some of this, a theme review tells you which gaps are worth closing first. Request a quote and describe what you are seeing.
Responsive Work Beyond Breakpoints
Responsive design in a content-managed site is harder than in a static mock-up, because the content varies. A card layout that looks right with a four-word heading has to survive the fourteen-word heading an editor will eventually write.
Design for the content that will exist, not the content in the design file. Test with the longest title in the database, with a missing image, with an empty field, and with translated text that runs longer than the English.
Images deserve particular attention. Drupal's responsive image support ties image styles to breakpoints so browsers download an appropriately sized file. Skipping it means mobile users download desktop-sized images, which is one of the most common and most fixable performance problems on a Drupal site.
Performance in the Theme Layer
The theme controls a large share of what a visitor waits for. Fonts that block rendering, oversized images, render-blocking CSS, and JavaScript that runs before it needs to all live here.
The highest-value habits are straightforward: keep critical CSS small, load fonts with font-display: swap so text is visible while they arrive, size images through image styles rather than in CSS, and defer JavaScript that is not needed for the first paint.
Theme-level caching matters too. Templates render inside Drupal's cache system, and a template that renders something user-specific without declaring the right cache context will either be cached and shown to the wrong person, or force caching off entirely.
Common Theming Mistakes
- Editing a base theme's files directly. The changes vanish at the next update. Override in a sub-theme.
- Overriding a broad template to change one narrow thing — the copied
node.html.twigproblem. - Removing focus outlines because they clash with the design, which makes the site unusable by keyboard.
- Business logic in preprocess, invisible to everyone reading the modules.
- One global CSS file that grows until nobody can safely delete anything from it.
- Markup produced in a module, so presentation changes need a back-end developer.
Keeping a Theme Upgradeable
Themes carry upgrade debt just as modules do. Templates copied from core drift out of sync as core changes its own; a template copied from an older version keeps rendering old markup and quietly misses accessibility and structural improvements.
The maintainable pattern is to override as little as possible, and to record why each override exists. A template with a comment explaining what it changes and why can be re-based against a newer core version in minutes. One with no explanation has to be reverse-engineered.
If you have inherited a theme and cannot tell which templates are deliberate overrides and which are stale copies, that is a common and solvable problem — a short review will usually sort it out faster than working through it in isolation.
When to Bring in a Themer
A capable front-end developer can do a great deal in a Drupal theme without Drupal-specific expertise, particularly styling work against existing markup.
It is worth bringing in Drupal-specific help when the markup itself has to change and it is not obvious which template produces it; when a design needs structures Drupal does not produce naturally; when accessibility has to be demonstrated rather than assumed; when a theme has to work across many sites with different content; or when an upgrade has to be done and nobody knows which templates were overridden on purpose.
The signal that usually means it is time: the CSS has begun to work around the markup instead of styling it.
Next Steps
If you are assessing your own theme, the fastest useful exercise is to list every template it overrides and, for each, say in one sentence why. The ones nobody can explain are your upgrade risk, and the list is usually shorter than expected.
If you would rather have help, the practical options are a theme review with a written report, a defined piece of theming work, or a full sub-theme build on a base theme chosen for your requirements. The Drupal themer page covers the approach in more detail, and there are examples in the portfolio.
I have worked in web development since 2005, and I am the author of Drupal themes and modules — you can look through them on my drupal.org profile before we speak.
To start, request a quote describing your site and the design work you have in mind, or get in touch to talk it through. Knowing your Drupal version, your base theme, and whether the design already exists will make the first conversation a short one.
