Creating a Custom Drupal Theme From Scratch

A maintainable Drupal theme is a translation layer between render arrays and a coherent design system. This portfolio began with semantic landmarks and content regions, then added tokens, components, and progressive JavaScript.

Define the theme contract

The info file declares regions and global libraries. Libraries keep CSS and JavaScript dependencies explicit, cacheable, and attachable only where needed. Twig templates should shape markup without querying storage or implementing business rules.

Build from tokens outward

Colors, spacing, typography, surfaces, and focus treatment belong in shared custom properties. Components consume those tokens, which is why the accent picker can change the whole visual system without duplicating selectors.

Responsive design starts with flexible grids and readable measures. Breakpoints should respond to layout pressure rather than a list of devices.

Performance and accessibility are features

Avoid shipping JavaScript for behavior CSS already handles. Preserve visible focus, reduced-motion preferences, semantic headings, and sufficient contrast in every color mode. Version libraries when assets change so Drupal and downstream caches agree.

Working example

global:
  version: 1.0.0
  css:
    theme:
      css/style.css: {}
  js:
    js/site.js: {}
  dependencies:
    - core/drupal
    - core/once

Key Takeaways

• Treat regions and libraries as the public contract of the theme.
• Use design tokens to keep variants consistent.
• Design responsive and accessible behavior before decoration.

Further Reading

• Drupal documentation
• Drupal API documentation