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-start60/40,main-end40/60,sidebar-start,sidebar-end). - Grid: intention counts (
auto,2,3,4,bento) andgap. - 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.