ButterflyPress
Architecture

Data Layer → Core & SDKs → Custom Templates

How ButterflyPress eliminates CSS class coupling from Wagtail while preserving infinite visual freedom on the frontend.

1. Semantic Intention Vocabulary

Instead of 12-column grids or custom_css_classes inside Wagtail, ButterflyPress expresses layout intent through finite semantic tokens:

  • Section: surface (default | muted | brand | contrast), density (compact | normal | spacious), containerWidth.
  • Split: role proportions (equal, main-start 60/40, main-end 40/60, sidebar-start, sidebar-end).
  • Grid: intention counts (auto, 2, 3, 4, bento) and gap.
  • Card: composable child streams or flat fields, with mediaRole (cover | background | inline).

2. AST Normalizer & Pure camelCase Contract

@butterflypress/core normalizes every Wagtail REST response at the HTTP boundary via normalizePagePayload() while preserving CSS custom properties (--*) and image renditions keys.

Normalized StreamBlock Payload json
[
  {
    "id": "sec-1",
    "type": "section",
    "value": {
      "surface": "brand",
      "density": "normal",
      "containerWidth": "standard",
      "content": []
    }
  }
]

3. Variant Dispatch & Semantic Fallback

Every framework <BlockRenderer /> resolves blocks in deterministic order: components["type:variant"] → components["type"] → DEFAULT_BLOCK_REGISTRY → SemanticBlockFallback. Circular references are terminated cleanly via ancestor Set cycle detection and MAX_BLOCK_DEPTH = 32.