Compose a nested hero section

A hero is a static composition of canonical blocks, not a special hero type. Use an outer container for the section treatment and an inner container to constrain and align the copy. The nested children are a heading, text, and button.

Copy this complete tree, then replace the IDs, copy, and destination. The outer display.background is a decorative option; this example uses aurora. display.gap: 24 maps to gap-6, and display.full_width: true makes the section take the available width.

{
  "blocks": [
    {
      "id": "hero-shell",
      "type": "container",
      "display": {
        "layout": "flex",
        "direction": "column",
        "gap": 24,
        "full_width": true,
        "background": "aurora"
      },
      "style": {
        "class": "px-6 py-20 text-center"
      },
      "blocks": [
        {
          "id": "hero-content",
          "type": "container",
          "display": {
            "layout": "flex",
            "direction": "column",
            "gap": "md",
            "full_width": true
          },
          "style": {
            "class": "mx-auto max-w-3xl items-center"
          },
          "blocks": [
            {
              "id": "hero-heading",
              "type": "heading",
              "content": {
                "text": "Make every launch count",
                "level": "h1"
              },
              "style": {
                "class": "text-4xl font-bold tracking-tight md:text-6xl"
              }
            },
            {
              "id": "hero-copy",
              "type": "text",
              "content": {
                "text": "Plan, publish, and improve a polished customer experience from one platform."
              },
              "style": {
                "class": "max-w-2xl text-lg text-muted-foreground"
              }
            },
            {
              "id": "hero-action",
              "type": "button",
              "content": {
                "label": "Start building",
                "href": "/start"
              },
              "display": {
                "variant": "default"
              },
              "style": {
                "class": "mt-2"
              }
            }
          ]
        }
      ]
    }
  ]
}

Style and spacing

Tailwind utilities in style.class do work. frontend/src/app-page-utilities.css is an explicit @source inline safelist, including sm:, md:, lg:, and xl: responsive variants; see docs/style-authoring.md:9-46. That current source supersedes the older warning in docs/page-builder-blocks.md, which should not be changed as part of this recipe.

Use the outer container for section padding and background, then use the inner one for max-w-*, centering, and child alignment. Keep the button’s layout adjustment local to the button. This makes a copy change or a visual variation less likely to disturb the section’s width and vertical rhythm.

What the catalog example does not cover

The existing hero-like example in docs/page-builder-blocks.md is a bare composition with no annotation, no gap, full_width, or spacing rules, and no variation guidance. This recipe supplies those authoring decisions while keeping the same canonical composition approach.

Variations

For a calmer hero, set display.background to none and give the outer container a normal surface class such as bg-muted. For a denser campaign section, keep the same tree, shorten the copy, lower the outer padding, and use a smaller heading utility. Do not invent a hero block: the reusable unit remains the nested container tree.