Drupal Front End Development

Overview

Enable expert-level Drupal front end development capabilities. Provide comprehensive guidance for theme development, Twig templating, preprocessing, responsive design, and asset management for Drupal 8, 9, 10, and 11+.

When to Use This Skill

Invoke this skill when working with:

• •Theme development: Creating or customizing Drupal themes
• •Twig templates: Writing or modifying .twig template files
• •Preprocessing: Implementing preprocess functions for templates
• •Template suggestions: Adding custom template naming patterns
• •CSS/JS libraries: Managing theme assets and dependencies
• •Responsive design: Implementing breakpoints and mobile-first design
• •Rendering system: Understanding Drupal's rendering pipeline
• •Theme hooks: Implementing theme-related hooks and alterations

Core Capabilities

1. Theme Development

Build complete, standards-compliant Drupal themes with proper structure:

Quick start workflow:

1. •Use theme template from assets/theme-template/ as starting point
2. •Replace THEMENAME with your theme's machine name
3. •Replace THEMELABEL with human-readable name
4. •Customize templates, CSS, JS, and libraries
5. •Enable theme and configure via Appearance UI

Theme components:

• •.info.yml - Theme metadata and configuration
• •.libraries.yml - CSS/JS library definitions
• •.theme - Preprocess functions and theme logic
• •.breakpoints.yml - Responsive breakpoints
• •templates/ - Twig template files
• •css/ - Stylesheets
• •js/ - JavaScript files

Reference documentation:

• •references/theming.md - Complete theming guide with examples

2. Twig Template System

Master Twig syntax and Drupal-specific extensions:

Twig fundamentals:

• •{{ variable }} - Print variables
• •{% if/for/set %} - Control structures and logic
• •{# comment #} - Comments and documentation
• •{{ var|filter }} - Apply filters to variables
• •{% extends %} - Template inheritance
• •{% block %} - Define overridable sections

Drupal-specific Twig:

• •{{ 'Text'|t }} - Translate strings
• •{{ attach_library('theme/library') }} - Load CSS/JS
• •{{ url('route.name') }} - Generate URLs
• •{{ path('route.name') }} - Generate paths
• •{{ file_url('public://image.jpg') }} - File URLs
• •{{ content|without('field') }} - Exclude fields

Common templates:

• •page.html.twig - Page layout structure
• •node.html.twig - Node display
• •block.html.twig - Block rendering
• •field.html.twig - Field output
• •views-view.html.twig - Views output

3. Preprocessing Functions

Modify template variables before rendering:

Preprocess pattern:

function THEMENAME_preprocess_HOOK(&$variables) {
  // Add or modify variables
  // Access entities, services, configuration
  // Prepare data for templates
}

Common preprocess hooks:

• •hook_preprocess_page() - Page-level variables
• •hook_preprocess_node() - Node-specific data
• •hook_preprocess_block() - Block modifications
• •hook_preprocess_field() - Field alterations
• •hook_preprocess_html() - HTML document

Best practices:

• •Keep logic in preprocess, markup in templates
• •Use dependency injection when possible
• •Cache properly with cache contexts/tags
• •Document complex preprocessing

4. Template Suggestions

Provide specific templates for different contexts:

Suggestion patterns:

page--front.html.twig                  # Homepage
page--node--{nid}.html.twig            # Specific node
page--node--{type}.html.twig           # Content type
node--{type}--{viewmode}.html.twig     # Type + view mode
block--{plugin-id}.html.twig           # Specific block
field--{entity}--{field}.html.twig     # Specific field

Adding suggestions:

function THEMENAME_theme_suggestions_HOOK_alter(array &$suggestions, array $variables) {
  // Add custom suggestions
  $suggestions[] = 'custom__suggestion';
}

5. CSS & JavaScript Management

Organize and load theme assets efficiently:

Library definition:

# THEMENAME.libraries.yml
global-styling:
  version: 1.0
  css:
    base:
      css/base/reset.css: {}
    theme:
      css/theme/styles.css: {}
  js:
    js/custom.js: {}
  dependencies:
    - core/drupal

Loading libraries:

• •Global: Define in .info.yml
• •Conditional: Use attach_library() in templates
• •Preprocessed: Attach in preprocess functions

Best practices:

• •Separate CSS into layers (base, layout, component, theme)
• •Use CSS aggregation in production
• •Minimize JavaScript dependencies
• •Leverage Drupal's asset library system

6. Responsive Design

Implement mobile-first, accessible designs:

Breakpoints definition:

# THEMENAME.breakpoints.yml
THEMENAME.mobile:
  label: Mobile
  mediaQuery: 'screen and (min-width: 0px)'
  weight: 0

THEMENAME.tablet:
  label: Tablet
  mediaQuery: 'screen and (min-width: 768px)'
  weight: 1

THEMENAME.desktop:
  label: Desktop
  mediaQuery: 'screen and (min-width: 1024px)'
  weight: 2

Mobile-first approach:

1. •Design for smallest screens first
2. •Enhance for larger viewports
3. •Use responsive images
4. •Test across devices
5. •Follow accessibility standards (WCAG)

Development Workflow

Creating a New Theme

1. •

   Scaffold the theme:

   bash

   cp -r assets/theme-template/ /path/to/drupal/themes/custom/mytheme/
   cd /path/to/drupal/themes/custom/mytheme/
   
   # Rename files
   mv THEMENAME.info.yml mytheme.info.yml
   mv THEMENAME.libraries.yml mytheme.libraries.yml
   mv THEMENAME.theme mytheme.theme
   

2. •

   Update theme configuration:

   • •Edit mytheme.info.yml - Set name, regions, base theme
   • •Edit mytheme.libraries.yml - Define CSS/JS libraries
   • •Replace THEMENAME with your machine name
   • •Replace THEMELABEL with your label
3. •

   Enable the theme:

   bash

   ddev drush cr
   # Enable via UI at /admin/appearance or:
   ddev drush config:set system.theme default mytheme -y
   

4. •

   Enable Twig debugging:

   • •Copy sites/default/default.services.yml to sites/default/services.yml
   • •Set twig.config.debug: true
   • •Set twig.config.auto_reload: true
   • •Set twig.config.cache: false
   • •Run ddev drush cr
5. •

   Develop and iterate:

   • •Modify templates in templates/
   • •Update CSS in css/
   • •Clear cache frequently: ddev drush cr
   • •Check browser console for errors

Standard Development Workflow

1. •Enable development settings (Twig debug, disable CSS/JS aggregation)
2. •Create/modify templates based on suggestions from Twig debug
3. •Implement preprocessing in .theme file for complex data manipulation
4. •Add CSS/JS via libraries system
5. •Test across browsers and devices
6. •Clear cache after changes: ddev drush cr

Finding Template Names

With Twig debugging enabled, inspect HTML source:

<!-- FILE NAME SUGGESTIONS:
   * page--node--123.html.twig
   * page--node--article.html.twig
   * page--node.html.twig
   x page.html.twig
-->

The x indicates the active template. Others are suggestions you can create.

Common Patterns

Adding Custom Variables in Preprocess

function mytheme_preprocess_page(&$variables) {
  // Add site slogan
  $variables['site_slogan'] = \Drupal::config('system.site')->get('slogan');

  // Add current user
  $variables['is_logged_in'] = \Drupal::currentUser()->isAuthenticated();

  // Add custom class
  $variables['attributes']['class'][] = 'custom-page-class';
}

Template Inheritance

{# templates/page--article.html.twig #}
{% extends "page.html.twig" %}

{% block content %}
  <div class="article-wrapper">
    {{ parent() }}
  </div>
{% endblock %}

Conditional Library Loading

function mytheme_preprocess_node(&$variables) {
  if ($variables['node']->bundle() == 'article') {
    $variables['#attached']['library'][] = 'mytheme/article-styles';
  }
}

Accessing Field Values in Twig

{# Get field value #}
{{ node.field_custom.value }}

{# Check if field has value #}
{% if node.field_image|render %}
  {{ content.field_image }}
{% endif %}

{# Loop through multi-value field #}
{% for item in node.field_tags %}
  {{ item.entity.label }}
{% endfor %}

Best Practices

Theme Development

1. •Base theme: Choose appropriate base (Olivero, Claro, or none)
2. •Structure: Organize CSS logically (base, layout, components, theme)
3. •Naming: Use BEM or similar CSS methodology
4. •Comments: Document complex Twig logic and preprocessing
5. •Performance: Optimize images, minimize CSS/JS, lazy load when possible

Twig Templates

1. •Logic: Keep complex logic in preprocess, not templates
2. •Filters: Use appropriate filters (|t, |clean_class, |safe_join)
3. •Whitespace: Use {% spaceless %} to control output
4. •Debugging: Enable Twig debugging during development only
5. •Suggestions: Use specific templates only when needed

Preprocessing

1. •Services: Use dependency injection in theme service subscribers
2. •Caching: Add proper cache contexts and tags
3. •Performance: Avoid heavy operations in frequently-called preprocessors
4. •Organization: Group related preprocessing logically

CSS & JavaScript

1. •Libraries: Group related assets into logical libraries
2. •Dependencies: Declare all library dependencies
3. •Loading: Load globally only when necessary
4. •Aggregation: Enable in production for performance

Accessibility

1. •Semantic HTML: Use proper elements (header, nav, main, etc.)
2. •ARIA: Add labels and roles when needed
3. •Keyboard: Ensure keyboard navigation works
4. •Contrast: Meet WCAG color contrast requirements
5. •Alt text: Provide for all images

Responsive Design

1. •Mobile-first: Design for small screens, enhance for large
2. •Breakpoints: Define logical breakpoints
3. •Images: Use responsive image styles
4. •Testing: Test across devices and screen sizes
5. •Performance: Optimize for mobile networks

Troubleshooting

Template Changes Not Showing

• •Clear cache: ddev drush cr
• •Verify file location and naming
• •Check Twig debug for active template
• •Ensure library is properly defined

CSS/JS Not Loading

• •Check library definition in .libraries.yml
• •Verify file paths are correct
• •Ensure library is attached (globally or conditionally)
• •Clear cache and check browser console

Variables Not Available in Template

• •Check preprocess function naming
• •Verify variables are being set correctly
• •Use Twig debugging: {{ dump() }}
• •Clear cache after preprocessing changes

Twig Debugging Not Working

• •Verify sites/default/services.yml exists
• •Check twig.config.debug: true is set
• •Clear cache: ddev drush cr
• •Check file permissions

Resources

Reference Documentation

• •references/theming.md - Comprehensive theming guide
  • •Twig syntax and filters
  • •Template suggestions
  • •Preprocessing patterns
  • •Library management
  • •Responsive design
  • •Best practices

Asset Templates

• •assets/theme-template/ - Complete theme scaffold
  • •.info.yml with regions and configuration
  • •.libraries.yml with CSS/JS examples
  • •.theme with preprocess examples
  • •Page template
  • •CSS and JS starter files

Searching References

# Find specific Twig filter
grep -r "clean_class" references/

# Find preprocessing examples
grep -r "preprocess_node" references/

# Find library patterns
grep -r "libraries.yml" references/

Version Compatibility

Drupal 8 vs 9 vs 10 vs 11

• •Twig syntax: Consistent across all versions
• •Base themes: Some legacy themes removed in 10+
• •Libraries: Same structure across versions
• •jQuery: Drupal 9+ doesn't load jQuery by default
• •Claro: Admin theme standard in 9+
• •Olivero: Frontend theme standard in 10+

Migration Notes

• •When upgrading, check for deprecated base themes
• •Review jQuery dependencies
• •Test with current Twig version
• •Check for removed core templates

See Also

• •drupal-backend - Module development, hooks, APIs
• •drupal-tooling - DDEV and Drush development tools
• •Drupal Theming Guide - Official documentation
• •Twig Documentation - Twig syntax reference