Section flow

Overview

The Section Flow System solves the stacked-boxes problem: pages where every section looks like an isolated card sitting on a white background. By adding a handful of flat design: fields to any section in your page composition, you can create flowing, layered pages where sections blend into one another, float over adjacent sections, reveal on scroll, and transition with shaped dividers.

All flow behavior is managed by the section wrapper (render-sections.html), not by individual block templates. This means the same five fields work identically across every block in the system.

Design Fields Reference

All values are flat scalars under design: — no nested maps or arrays.

Usage Examples

Flush dark hero (edge-to-edge, no padding)

- block: hero
  design:
    spacing: flush
    bg: dark
  content:
    title: "Your headline here"

Overlapping stats band (floats over the previous section)

- block: stats-band
  design:
    overlap: true
    overlap_amount: lg
  content:
    stats:
      - label: Bedrooms
        value: "5"

Wave divider (SVG shape transition to the next section)

- block: full-bleed-split
  design:
    spacing: normal
    bg: light
    divider_after: wave
  content:
    title: "Section with a wave at the bottom"

Scroll-linked parallax (entire section scrolls at a different rate)

- block: full-bleed-split
  design:
    parallax: true            # use default speed (0.15)
  content:
    title: "Subtle parallax depth"

- block: media-text
  design:
    parallax: 0.25            # or set speed directly
  content:
    title: "Medium parallax depth"

Use sparingly — 1–2 parallax sections per page creates depth; more creates nausea. Not recommended for gallery or stats blocks where content alignment matters.

Custom reveal animation (slides in from the left on scroll)

- block: media-text
  design:
    spacing: normal
    wrapper_reveal: slide-left
  content:
    title: "Feature highlight"

Extra padding with zoom reveal

- block: gallery
  design:
    spacing: spacious
    bg: surface-alt
    wrapper_reveal: zoom-in
  content:
    images: []

Adjacent same-background sections (automatic gap collapse)

When two consecutive sections share the same bg value, the gap between them collapses automatically. No extra YAML needed.

- block: gallery
  design:
    bg: surface-alt

- block: testimonials
  design:
    bg: surface-alt
  # No visible gap between gallery and testimonials — backgrounds merge

Theme Overrides

The flow system exposes CSS custom properties so themes can adjust the visual weight of each spacing step, the overlap distances, and divider heights. Override these in your theme’s CSS file:

:root {
  /* Spacing steps */
  --foundry-flow-spacing-flush: 0;
  --foundry-flow-spacing-tight: 1.5rem;
  --foundry-flow-spacing-spacious: 6rem;

  /* Overlap distances */
  --foundry-flow-overlap-sm: 1.5rem;
  --foundry-flow-overlap-md: 3rem;
  --foundry-flow-overlap-lg: 5rem;

  /* Divider heights */
  --foundry-flow-divider-wave-height: 80px;
  --foundry-flow-divider-angle-height: 60px;
  --foundry-flow-divider-curve-height: 80px;
  --foundry-flow-divider-fade-height: 40px;

  /* Parallax default speed (used when parallax: true without parallax_speed) */
  --foundry-flow-parallax-speed: 0.15;
}

Theme CSS uses --foundry-flow-* as the namespace. Any property not overridden falls back to the defaults above.

Compatibility Notes

• Full-bleed blocks manage their own padding. Blocks like full-bleed-split and stats-band manage their own internal padding. Setting spacing on these blocks has no visible effect on inner content padding — it only affects the wrapper gutter.

• Blocks with variant-based backgrounds. Some blocks (e.g., stats-band variant: dark) set their own inner background color. The bg field on the section wrapper controls the gutter area around the block, not its inner palette. Both can coexist.

• Overlap is ignored on the first section. If the first section on a page has overlap: true, the negative margin is not applied — there is nothing above it to overlap.

• Overlap is automatically disabled on mobile. Below 640px viewport width, overlap uses margin-top: 0 to prevent layout issues on small screens.

• Overlap respects prefers-reduced-motion. When the user has enabled reduced-motion preferences, the overlap negative margin is removed along with scroll animations.

• Parallax uses the existing motion engine. foundry-motion.js handles the scroll effect — parallax: true adds data-motion-parallax to the section wrapper. The motion engine already respects prefers-reduced-motion. No new JavaScript.

• Parallax: use sparingly. 1–2 parallax sections per page adds depth. More creates nausea. Not recommended for gallery, stats, or form blocks where alignment is critical.

• divider_after and bg are independent. The divider SVG fills from the section’s background color to the next section’s background. If the next section has a different bg, the shape transition is visible. If they share the same bg, the divider blends invisibly.

For AI Agents and Scaffold Scripts

All flow design values are flat scalars under the design: key in a section entry — no nested maps, no arrays, no special types. This makes them easy to generate programmatically.

The machine-readable reference for all global flow fields is the _global entry in data/foundry/block-options.yaml. Scaffold scripts and AI agents should read this entry to discover available field names, allowed values, and defaults before generating page compositions.

For broader motion planning, parallax limits, profile naming, and reduced-motion requirements, see Foundry Motion Kit Plan. Section flow owns wrapper-level rhythm; Motion Kit owns the cross-block motion contract and future validation rules.

Example of a valid section with flow fields:

- block: cta
  design:
    spacing: tight
    bg: brand
    overlap: true
    overlap_amount: md
  content:
    title: "Schedule a viewing"
    primary_action:
      text: "Contact us"
      url: "/contact"

No other configuration is required. The section wrapper applies all flow behavior automatically when these fields are present.