Bricks and reusable composition

Purpose

Foundry needs a reusable composition layer that is stronger than a simple ordered sections list.

Public/editor language should use:

• sections for page-level placed items
• compositions for reusable named page structures

The current technical compatibility layer for that concept is bricks.

Plain-language rule

• blocks are framework primitives
• sections are placed page instances
• compositions are reusable named structures
• bricks are the current technical structure behind compositions

Why this exists

sections are ideal for straightforward page assembly, but some sites need reusable named structures without duplicating large objects in front matter.

That is where compositions fit.

Current brick structure

Foundry currently supports a bricks map plus bricks_order.

bricks:
  hero_main:
    block: hero
    content:
      title: "Headline"
  stats_main:
    block: stats-grid
    content:
      stats:
        - value: "10+"
          label: "Years"
bricks_order:
  - hero_main
  - stats_main

If sections is empty and bricks exists, Foundry renders bricks in bricks_order or in map order if no order array is provided.

Recommended positioning

For public docs and future editor UX:

• describe the concept as compositions
• keep bricks as the current technical/storage term for compatibility

This avoids making Foundry sound like a toy builder while preserving the existing syntax.

When to use sections

Use sections when:

• the page is mostly unique
• reuse is low
• a simple ordered page structure is easiest to maintain

When to use compositions

Use compositions when:

• the same configured content structure will appear more than once
• you want reusable named units
• you want a page to reference structured content without repeating it inline

Approved reuse model

The current approved public reuse model is:

• use inline sections for page-local structure
• use composition refs for reusable configured structures
• use shared content refs for reusable shared content that should not be duplicated inline

This is the intended public distinction even while bricks remains the current technical compatibility layer behind compositions.

Current capability

Today, the supported composition behavior is:

• one named configured block instance per brick entry
• ordered rendering through bricks_order

Planned evolution

Foundry should evolve this concept beyond simple named block instances.

Target direction:

• a composition may represent one configured block
• a composition may represent a reusable multi-block assembly
• compositions may reference other compositions

Illustrative future direction:

bricks:
  service_intro:
    kind: composition
    items:
      - block: hero
        preset: editorial
        content:
          title: "Service headline"
      - block: trust-badges
        content:
          items:
            - name: "Trusted"

Compatibility rule

Foundry should keep the current bricks syntax working while the public model evolves toward compositions.

That gives the framework a stronger identity without forcing immediate content rewrites.

Removal gate

Do not remove legacy bricks terminology or syntax until all of the following are true:

• a stable bundle ships composition as the public path
• migration docs exist
• starter and demo repos have updated public examples
• at least one real consumer site has upgraded without manual repair