Skip to content

STD-DRUPAL-002: Drupal Composition & Theme Governance Doctrine

Status: Approved Governing Standard
Authority: Thomas P. Scola Jr. — Drupal Architecture Direction
Date: 2026-09-23
Bead: bc-um0w / bc-opt2

1. Prime Directive: Sites are Consumers, Not Implementation Grounds

Consumer Drupal sites (bluefly.io, contextcontrol-ai, etc.) must be assembled via composition, not bespoke custom code or bloated custom themes.

UPSTREAM DRUPAL CMS + CONTRIB + CANVAS + SDC + RECIPES + SITE TEMPLATES + MINIMAL THEME

Invariants:

  1. DRUPAL_SITES_ARE_CONSUMERS = YES
  2. BUILD_WITH_CONFIGURATION = YES
  3. UPSTREAM_FIRST = YES
  4. CONTRIB_FIRST = YES
  5. RECIPES_BEFORE_CUSTOM_SETUP = YES
  6. CANVAS_SDC_BEFORE_TWIG_OVERRIDES = YES
  7. CUSTOM_CODE_LAST = YES
  8. EDIT_ACTIVE_WEB_FOLDER = NO
  9. GAS_CITY_WORKTREE_ONLY = YES
  10. IS_THE_NEXT_RUN_GETTING_CHEAPER_AND_MORE_REUSABLE = YES (Acceptance gate)

2. Re-architecting Theme vs. Composition Boundaries

Custom sub-themes (bluefly_theme) MUST be strictly reduced to a thin branding shell.

Legitimate Theme Responsibilities:

  • Design tokens / CSS custom properties overrides.
  • Brand assets (logos, favicons).
  • Truly site-unique presentation adjustments that cannot be achieved via SDC/Canvas.

Prohibited in Theme (Must be Moved to Upstream/Composition):

  • Page layout logic (belongs in Canvas / Site Templates).
  • Content type templates / Twig overrides (belongs in Canvas Content Templates / Entity View Displays).
  • Generic components (belongs in Core SDCs or contrib SDC libraries).
  • Duplicated design system compilation (must consume compiled packages from agentic_canvas or @bluefly/studio-ui).
  • Content modeling & business rules (belongs in Drupal Recipes / Config).

3. Site Templates & Canvas Authority

  1. Drupal CMS Site Templates: Site functionality and page patterns should be defined as recipes and exported via drush site:export into reusable Site Templates.
  2. Canvas CLI vs. Theme Inheritance:
  3. Theme inheritance passes CSS/JS libraries and base templates down the Drupal theme tree.
  4. Canvas CLI manages Canvas code components, pages, content templates, and global styling.
  5. Do not conflate theme inheritance with Canvas CLI synchronization.

4. Single-Directory Components (SDC)

SDC is part of Drupal Core. Reusable server-rendered components must use SDC contracts: - component.yml (schema, props, slots) - component.twig - Component-scoped CSS/JS (only when necessary) - No proliferation of global unstructured CSS.