drupal-conventions

name	drupal-conventions
description	Load Drupal-specific conventions (translations, CSS, error handling) on demand. Use when working on theming, translations, or exception handling.
metadata	{"status":"stable","drupal-version":"10+","last-reviewed":"2026-04"}

Drupal Conventions (JIT)

Load these conventions only when relevant to the current task.

Translation Rules

• Wrap all user-facing text in t() or TranslatableMarkup.
• Use module name as context (PHP string, not constant).
• English in code, translations in /translations/*.po files with msgctxt.
• Twig: |t filter for strings, {% trans %} blocks for placeholders.
• PO format: msgctxt "my_module" / msgid "English" / msgstr "Translated".

CSS Conventions

• Target specific elements (.parent .child), not parent containers.
• BEM: block__element--modifier strictly for custom classes.
• Use {{ attach_library('my_theme/component') }} for all assets.
• Every asset bundle needs a matching *.libraries.yml entry.
• Mobile-first responsive design. Use Drupal breakpoints for responsive images.

Error Handling

• Always use exceptions for errors, not NULL/FALSE returns.
• Never catch \Exception — catch the narrowest exception you can handle.
• Avoid catching just to log (unless error doesn't affect caller).
• Always return early with clear error messages (fail fast).

// Good: specific exception, early return.
if (!$entity) {
  throw new EntityNotFoundException("Entity $id not found.");
}

// Bad: silently swallowing errors.
try {
  $result = $service->process();
} catch (\Exception $e) {
  // Never do this.
}