Upgrading from Drupal 10 to Drupal 11: what actually changes
Drupal 11 is a far smaller step than the Drupal 7 to 9 migration was. Here is what the upgrade touches, what breaks, and the order to do it in.
ZooBieDoo Infotech Engineering TeamRead
Key takeaways
- Override the templates that matter rather than fighting Drupal's markup in CSS.
- Keep components self-contained; they render data, they do not fetch it.
- Preprocess functions shape data — business logic belongs in a service.
- Most accessibility defects originate in the theme layer.
Start from the markup you want
Drupal will happily produce deeply nested wrappers around every field. Rather than fighting that in CSS, override the templates that matter and emit the markup your design system expects.
Twig debugging output tells you exactly which template is responsible and which suggestions are available. Turn it on in development and use the suggestions rather than guessing.
Component thinking
Single Directory Components bring the template, styles and behaviour for a component into one folder, which makes ownership obvious and removes the usual hunt across three directories.
Even without them, keep a clear boundary: a component knows how to render itself given data, and does not reach into global state or query for its own content.
Preprocess with restraint
Preprocess functions are useful for shaping data before it reaches the template. They become a problem when they contain business logic, run queries, or grow to hundreds of lines.
If a preprocess function is doing real work, that work usually belongs in a service the function calls. This keeps templates thin and the logic testable.
Accessibility and the theme layer
Most accessibility defects are introduced in the theme: heading levels that skip, links that say “read more” with no context, form labels detached from inputs, and colour contrast that fails on secondary text.
Fix these in the templates and the design tokens rather than patching them per page. A theme that is accessible by construction saves an audit cycle on every subsequent project.
Front-end tooling and build output
Drupal is agnostic about how your CSS and JavaScript are produced, which means the decision is yours to make badly. A modern build using Vite or a similar bundler, producing hashed asset filenames, is straightforward and pays for itself in cache behaviour.
Attach assets through Drupal's libraries system rather than adding tags in templates. Libraries let you declare dependencies, load assets only on the pages that need them, and let Drupal handle aggregation. A theme that loads its entire stylesheet and every script on every page is leaving a large amount of performance on the table.
Keep the built output out of version control where the pipeline can produce it, and in version control where the deployment target cannot run a build. Both are defensible; what causes problems is being unclear about which one you have chosen.
Frequently asked questions
Starting from Drupal's own starter theme is usually sensible: it gives you sane defaults and accessible markup without imposing a design. Heavy contributed base themes save time initially and tend to cost more later, because you inherit markup and styling decisions you did not make.
Define design tokens for colour, spacing and type, and build components from those tokens rather than from raw values. When a new page needs something that does not exist, add it to the component set deliberately rather than styling it locally.
Often yes, and it usually improves the result. Twig is readable, and a designer who can adjust a template directly removes a whole class of translation errors between design and implementation.
