v0.2.5 core current Public

Block reference

Inspect the shipped block contracts and implementation-side authoring details.

Owner: Foundry Core
Source: core/docs/BLOCKS.md
Ref: v0.1.21
Policy: release-bound

Component pins for v0.2.5

Component	Role	Version
core	runtime	`v0.1.21`
theme-shield	theme	`v0.1.15`
starter	reference	`v0.1.3`
docs	reference	`v0.1.4`
distribution	tooling	`v0.3.3`
restricted-component-1	consumer-reference	`v0.1.10`
restricted-component-2	consumer-reference	`v1.1.21`

Block Index

How blocks work

Foundry pages define an ordered sections array in front matter. The render pipeline is:

layouts/partials/framework/render-sections.html iterates sections.
It resolves each block name through data/foundry/block-registry.yaml.
The mapped partial in layouts/partials/blocks/ is rendered with { page, section } context.
The block partial reads content, design, and id, then renders BEM-structured HTML.

sections:
  - block: hero
    id: homepage-hero
    content:
      title: "Build with Foundry"
      text: "Composable Hugo blocks rendered from front matter."
      primary_action:
        text: "Get Started"
        url: "/contact/"
    design:
      variant: centered
      css_class: ""

Block families

Family ownership is machine-checked in data/foundry/block-family-manifest.json. Each family exists because it solves a reusable shared job, not because the blocks happened to look similar during implementation.

Family	Why it exists	Representative blocks
`heroes-intros`	Shared page-opening and section-opening surfaces so sites do not fork hero logic locally.	`hero`, `post-hero`, `section-header`, `video-hero`, `motion-hero`, `coming-soon-hero`
`property-hospitality`	Dedicated property and hospitality storytelling surfaces instead of hiding them inside generic media/layout groups.	`property-hero`, `property-amenities`, `property-photo-tour`, `property-cards`
`layout-flow`	Reusable section rhythm and composition-shape controls that belong above any one visual theme.	`divider`, `columns`, `full-bleed-split`
`search-discovery`	Shared search and discovery mechanics that should stay framework-owned.	`search`, `content-feed`, `topic-chip-nav`
`lists-collections`	Reusable collection renderers for posts, pages, and related content.	`page-list`, `post-list`, `related-posts`
`narrative-editorial`	Text-first editorial and annotation surfaces that go beyond raw markdown output.	`rich-text`, `prose-panel`, `quote`, `pullquote`, `callout`
`navigation-disclosure`	In-page wayfinding and controlled-disclosure patterns with predictable shared behavior.	`content-sidebar-nav`, `table-of-contents`, `tabs`, `accordion`, `faq-accordion`
`media-gallery`	Core visual storytelling primitives across image, video, audio, embeds, and guided media sequences.	`media-text`, `media-break`, `media-sequence`, `pinned-media-story`, `slideshow`, `image-feature`, `masonry-gallery`, `gallery`, `video-embed`, `audio-player`, `embed`, `illustration-panel`, `before-after`
`features-highlights`	Quick-scan benefit and capability framing distinct from trust, pricing, or CTA surfaces.	`features`, `icon-grid`, `resource-downloads`, `logo-trust`
`trust-authority`	Proof, credibility, and amplification surfaces that should stay distinct from features and bios.	`trust-badges`, `testimonials`, `testimonials-carousel`, `logos`, `case-studies`, `certification-badges`, `social-share`
`process-data`	Sequential, temporal, metric, and map-like explanatory surfaces.	`steps`, `timeline`, `onboarding-timeline`, `stats-band`, `stats-grid`, `map-coverage`
`conversion-cta`	Shared prompt and next-step surfaces that move a visitor toward action.	`newsletter-inline`, `cta`, `faq-cta`, `lead-magnet`, `cta-image-paragraph`, `cta-button-list`
`forms-contact`	Contact capture and managed form surfaces with integration implications.	`managed-form`, `contact-split`
`pricing-comparison`	Decision-support surfaces whose semantics differ from generic feature or card modules.	`comparison-table`, `pricing-tiers`, `pricing-comparison`
`people-profiles`	Shared person/profile patterns that are not interchangeable with testimonials or logos.	`author-bio`, `team-grid`, `founder-profile`
`launch-coming-soon`	A lightweight temporary-launch lane so pre-release experiences do not devolve into throwaway one-offs.	`coming-soon-cta`, `coming-soon-trust`, `coming-soon-footer`

Some stable blocks are intentionally more specialized and do not yet have a repo starter, composition, or fixture proof. Those cases are tracked explicitly in data/foundry/block-governance.json so “unproven” does not silently turn into “unowned”.

Block standards (BEM, CSS vars, context extraction)

Every block follows the same context extraction contract:

{{ $section := .section }}
{{ $content := index $section "content" | default dict }}
{{ $design  := index $section "design"  | default dict }}
{{ $id      := index $section "id"      | default "" }}
{{ $class   := index $design  "css_class" | default "" }}
{{ $ui      := index hugo.Data.foundry "classes" | default dict }}

BEM naming convention:

Block root: foundry-[block-name]
Elements: foundry-[block-name]__[element]
Modifiers: foundry-[block-name]--[modifier]

Example (media-text): foundry-media-text, foundry-media-text__inner, foundry-media-text__title, foundry-media-text__actions.

Color theming uses CSS variables via inline style attributes (not utility class overrides):

<h2 class="foundry-example__title" style="color: var(--foundry-text, #0f172a)">Title</h2>
<p class="foundry-example__text" style="color: var(--foundry-text-muted, #475569)">Body copy</p>
<div class="foundry-example__panel" style="background: var(--foundry-surface, #ffffff); border-color: var(--foundry-border, #e2e8f0)"></div>

CSS variable system

assets/css/foundry-base.css defines neutral fallback tokens. Theme modules (for example theme-shield) override these at runtime.

Variable	Purpose	Base value
`--foundry-bg`	Page background color.	`#ffffff`
`--foundry-border`	Default border color.	`#e2e8f0`
`--foundry-border-strong`	High-contrast border color.	`#cbd5e1`
`--foundry-brand-accent`	Secondary accent color.	`#3b82f6`
`--foundry-brand-primary`	Primary brand accent used for key UI elements.	`#0f172a`
`--foundry-duration-base`	Base motion duration token.	`200ms`
`--foundry-ease-standard`	Default easing curve for transitions.	`cubic-bezier(0.2, 0, 0, 1)`
`--foundry-radius`	Default radius token.	`1rem`
`--foundry-radius-lg`	Large radius token.	`1.5rem`
`--foundry-radius-sm`	Small radius token.	`0.5rem`
`--foundry-shadow-md`	Medium elevation shadow token.	`0 4px 12px rgba(0, 0, 0, 0.1)`
`--foundry-shadow-sm`	Small elevation shadow token.	`0 1px 3px rgba(0, 0, 0, 0.1)`
`--foundry-surface`	Primary surface/card background.	`#ffffff`
`--foundry-surface-soft`	Subtle section and muted surface background.	`#f8fafc`
`--foundry-text`	Primary text color.	`#0f172a`
`--foundry-text-muted`	Secondary/muted text color.	`#475569`

Motion CSS variables

assets/css/foundry-motion.css defines additional motion-specific tokens.

Variable	Purpose	Default
`--foundry-motion-distance`	Default reveal translate distance.	`16px`
`--foundry-motion-duration`	Resolved animation duration token.	`var(--foundry-duration-base, 200ms)`
`--foundry-motion-ease`	Resolved easing curve for reveal transitions.	`var(--foundry-ease-standard, cubic-bezier(0.2, 0, 0, 1))`
`--foundry-motion-kb-duration`	Ken Burns animation duration.	`12s`
`--foundry-motion-kb-scale`	Ken Burns target scale value.	`1.06`
`--foundry-motion-marquee-pause-state`	Default marquee animation play state.	`running`
`--foundry-motion-opacity-start`	Starting opacity for reveal/stagger items.	`0`
`--foundry-motion-parallax-max`	Maximum parallax translate clamp (px).	`80px`
`--foundry-motion-scale-start`	Starting scale for zoom reveals.	`0.98`
`--foundry-motion-stagger-step`	Delay step between staggered children.	`80ms`

Motion attributes

The Motion Toolkit loader lives at layouts/partials/framework/foundry-motion.html and activates in sites that include the body-end hook.

Attribute	Engine	Accepted values	Behavior
`data-motion-kenburns`	Engine E: Ken Burns	Boolean attribute	Enables image zoom/pan crossfade behavior.
`data-motion-kenburns-interval`	Engine E: Ken Burns	Milliseconds (default `6000`)	Sets crossfade interval for multi-image containers.
`data-motion-marquee`	Engine D: Marquee	Boolean attribute	Initializes seamless marquee track cloning and animation.
`data-motion-marquee-dir`	Engine D: Marquee	`left` (default), `right`, `up`, `down`	Controls marquee animation direction.
`data-motion-marquee-pause`	Engine D: Marquee	`hover`	Pauses animation on hover/focus when set to `hover`.
`data-motion-marquee-speed`	Engine D: Marquee	Positive number (px/sec, default `40`)	Controls marquee travel speed.
`data-motion-parallax`	Engine B: Parallax	Float `0.0` to `0.8` (default `0.35`)	Parallax translateY multiplier, clamped by `--foundry-motion-parallax-max`.
`data-motion-parallax-dir`	Engine B: Parallax	`1` (default) or `-1`	Inverts parallax direction when negative.
`data-motion-reveal`	Engine A: Reveal	`fade-up` (default), `fade-in`, `slide-left`, `slide-right`, `zoom-in`	Applies entry animation; `is-in-view` is added by observer.
`data-motion-scrub`	Engine C: Scrub	Conventionally `progress`	Enables scroll-linked scrub behavior on target element.
`data-motion-scrub-prop`	Engine C: Scrub	`width` (default), `height`, `scaleX`, `opacity`	Selects property controlled by section scroll progress.
`data-motion-stagger`	Engine A: Stagger	Boolean attribute	Applies stagger delay to direct children when parent enters viewport.

Block catalog (alphabetical)

accordion

Minimum required: items — everything else is optional. Expandable content panels with optional single-open enforcement.

sections:
- block: accordion
  id: accordion-example
  content:
    items:
    - title: Item title
      text: Item description.
    text: Example supporting text.
    title: Example title
  design:
    variant: bordered
    allow_multiple: true
    css_class: ''

Design options

Field	Details
`variants`	`bordered`, `minimal`, `cards`
`variant`	bordered \| minimal \| cards — accordion container style
`allow_multiple`	true \| false — allow opening more than one item
`css_class`	extra CSS classes on outer section

BEM classes

foundry-accordion
foundry-accordion__body
foundry-accordion__empty
foundry-accordion__inner
foundry-accordion__item
foundry-accordion__list
foundry-accordion__subtitle
foundry-accordion__summary
foundry-accordion__title

audio-player

Minimum required: url, title — everything else is optional. Custom audio player block with progress, speed, and transcript support.

sections:
- block: audio-player
  id: audio-player-example
  content:
    date: '2026-02-22'
    description: Short descriptive paragraph.
    download: true
    duration: '42:17'
    image: "/images/example.jpg"
    show: Example Group
    title: Example title
    transcript: Transcript excerpt goes here.
    url: https://example.com
  design:
    variant: card
    css_class: ''

Design options

Field	Details
`variants`	`card`, `minimal`, `podcast`
`variant`	card \| minimal \| podcast — audio player presentation
`css_class`	extra CSS classes on outer section

BEM classes

foundry-audio-player
foundry-audio-player__content
foundry-audio-player__controls
foundry-audio-player__cover
foundry-audio-player__description
foundry-audio-player__download
foundry-audio-player__empty
foundry-audio-player__inner
foundry-audio-player__layout
foundry-audio-player__meta
foundry-audio-player__primary
foundry-audio-player__progress
foundry-audio-player__secondary
foundry-audio-player__shell
foundry-audio-player__show
foundry-audio-player__speed
foundry-audio-player__time
foundry-audio-player__timeline
foundry-audio-player__title
foundry-audio-player__toggle
foundry-audio-player__transcript
foundry-audio-player__volume

author-bio

Minimum required: name, bio — everything else is optional. Compact author profile block for article footers and about sections.

sections:
- block: author-bio
  id: author-bio-example
  content:
    bio: Example value
    company: Example Group
    image: "/images/example.jpg"
    links:
    - platform: linkedin
      url: https://example.com
    more_from:
      text: Learn more
      url: "/contact/"
    name: Example value
    role: Role or title
  design:
    variant: card
    css_class: ''

Design options

Field	Details
`variants`	`card`, `inline`, `minimal`
`variant`	card \| inline \| minimal — author module layout
`css_class`	extra CSS classes on outer section

BEM classes

foundry-author-bio
foundry-author-bio__card
foundry-author-bio__empty
foundry-author-bio__inner
foundry-author-bio__links

before-after

Minimum required: before, after — everything else is optional. Comparison block for before/after state storytelling.

sections:
- block: before-after
  id: before-after-example
  content:
    after: Example value
    before: Example value
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variant`	`cards` \| `table` \| `stacked` — cards: 2-col side-by-side (default); table: 3-col comparison using `rows[]{label,before,after}`; stacked: vertical before→after with arrow divider
`row_label`	header label for the label column in table variant (default: Feature)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-before-after
foundry-before-after__arrow
foundry-before-after__inner
foundry-before-after__label
foundry-before-after__panels
foundry-before-after__stack
foundry-before-after__table
foundry-before-after__title

callout

Minimum required: text — everything else is optional. Inline semantic notice block for info, warning, success, and related states.

sections:
- block: callout
  id: callout-example
  content:
    text: Example supporting text.
    title: Example title
  design:
    type: default
    icon: default
    css_class: ''

Design options

Field	Details
`variant`	`inline` \| `banner` \| `subtle` — inline: left accent border card (default); banner: full-width announcement strip with optional CTA button; subtle: no border, light tint, less intrusive
`type`	`info` \| `tip` \| `warning` \| `danger` \| `note` \| `success` — semantic intent style (controls color and default icon)
`icon`	icon name override (optional)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-callout
foundry-callout-accent
foundry-callout-bg
foundry-callout__box
foundry-callout__content
foundry-callout__icon
foundry-callout__inner
foundry-callout__text
foundry-callout__title

case-studies

Minimum required: cases — everything else is optional. Case study list/grid block with outcomes and project context.

sections:
- block: case-studies
  id: case-studies-example
  content:
    cases: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-case-studies
foundry-case-studies__badge
foundry-case-studies__card
foundry-case-studies__case-title
foundry-case-studies__grid
foundry-case-studies__inner
foundry-case-studies__result-icon
foundry-case-studies__result-item
foundry-case-studies__result-text
foundry-case-studies__results
foundry-case-studies__section
foundry-case-studies__section--problem
foundry-case-studies__section--results
foundry-case-studies__section--solution
foundry-case-studies__section-text
foundry-case-studies__section-title
foundry-case-studies__title

certification-badges

Minimum required: badges — everything else is optional. Certification and credential badge display block.

sections:
- block: certification-badges
  id: certification-badges-example
  content:
    badges: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-certification-badges
foundry-certification-badges__grid
foundry-certification-badges__inner
foundry-certification-badges__item
foundry-certification-badges__title

columns

Minimum required: columns — everything else is optional. Free-form multi-column markdown content block.

sections:
- block: columns
  id: columns-example
  content:
    columns:
    - heading: Column heading
      text: Column markdown content.
    - heading: Column heading
      text: Column markdown content.
  design:
    count: '3'
    gap: md
    dividers: true
    align: center
    css_class: ''

Design options

Field	Details
`variants`	`prose`, `feature`, `stat`
`variant`	prose \| feature \| stat — prose: markdown content (default); feature: icon + heading + text; stat: large value + label
`count`	2 \| 3 — column count
`gap`	sm \| md \| lg — column gap
`dividers`	true \| false — vertical separators between columns
`align`	top \| center — vertical alignment of column content
`css_class`	extra CSS classes on outer section

BEM classes

foundry-columns
foundry-columns__column
foundry-columns__empty
foundry-columns__grid
foundry-columns__inner

coming-soon-cta

Minimum required: title — everything else is optional. Coming-soon CTA block for waitlist or early access capture.

sections:
- block: coming-soon-cta
  id: coming-soon-cta-example
  content:
    primary_action:
      text: Learn more
      url: "/contact/"
    secondary_action:
      text: Learn more
      url: "/contact/"
    support_note: Example value
    text: Example supporting text.
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-coming-soon-cta
foundry-coming-soon-cta__actions
foundry-coming-soon-cta__inner
foundry-coming-soon-cta__text
foundry-coming-soon-cta__title

Minimum required: (none) — everything else is optional. Minimal coming-soon footer block with links and legal copy.

sections:
- block: coming-soon-footer
  id: coming-soon-footer-example
  content:
    address_lines: Example value
    bottom_note: Example value
    contact_title: Example value
    copyright: Example value
    email: Example value
    email_url: Example value
    legal_note: Example value
    legal_title: Example value
    likestyle_url: Example value
    logo: Example value
    phone: Example value
    phone_url: Example value
    preview_label: Example value
    preview_url: Example value
    privacy_url: Example value
    tagline: Example value
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-coming-soon-footer
foundry-coming-soon-footer__brand
foundry-coming-soon-footer__copy
foundry-coming-soon-footer__inner
foundry-coming-soon-footer__links

coming-soon-hero

Minimum required: title — everything else is optional. Coming-soon hero block with launch positioning and signup focus.

sections:
- block: coming-soon-hero
  id: coming-soon-hero-example
  content:
    badge_text: Example value
    email_label: Example value
    email_placeholder: Example value
    first_name_label: Example value
    first_name_placeholder: Example value
    form_action: "/api/submit"
    form_headline: Example value
    form_name: Example value
    likestyle_cta: Example value
    likestyle_kicker: Example value
    likestyle_meta: Example value
    likestyle_text: Example value
    likestyle_url: Example value
    logo: Example value
    privacy_text: Example value
    submit_text: Example value
    subtitle: Example value
    title: Example title
    trust_badges: Example value
  design:
    css_class: ''

Legacy mode uses form_action. Managed mode uses content.form and the same Foundry Control contract as managed-form.

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-coming-soon-hero
foundry-coming-soon-hero__form
foundry-coming-soon-hero__inner
foundry-coming-soon-hero__text
foundry-coming-soon-hero__title

coming-soon-trust

Minimum required: logos — everything else is optional. Coming-soon trust signal block for early credibility.

sections:
- block: coming-soon-trust
  id: coming-soon-trust-example
  content:
    badges: Example value
    logos:
    - name: Partner Name
    stats:
    - label: Metric
      value: 95%
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-coming-soon-trust
foundry-coming-soon-trust__inner
foundry-coming-soon-trust__item
foundry-coming-soon-trust__items
foundry-coming-soon-trust__title

comparison-table

Minimum required: rows — everything else is optional. Feature comparison table block across options or providers.

sections:
- block: comparison-table
  id: comparison-table-example
  content:
    footnote: Example value
    headers: Example value
    rows: Example value
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-comparison-table
foundry-comparison-table__cell
foundry-comparison-table__inner
foundry-comparison-table__row
foundry-comparison-table__table
foundry-comparison-table__title

contact-split

Minimum required: none — everything else is optional. Two-column contact block with details and either a legacy inline form or a managed Foundry Control form.

sections:
- block: contact-split
  id: contact-split-example
  content:
    address: Example value
    email: Example value
    fields: Example value
    form_action: "/api/submit"
    form:
      mode: managed
      form_key: contact-intake
    form_method: Example value
    form_text: Example value
    form_title: Example value
    hours: Example value
    phone: Example value
    privacy_note: No spam. Unsubscribe anytime.
    submit_text: Example value
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Legacy mode uses form_action, form_method, fields, and submit_text. Managed mode uses content.form with the same stable contract as the managed-form block and resolves base_url / site_key from site.Params.foundry.control when not provided inline.

Design options

Field	Details
`variant`	`split` \| `centered` \| `minimal` — split: 2-col left meta+form (default); centered: stacked headline+chips+form, max-w-2xl; minimal: form only, no meta panel, max-w-xl
`css_class`	extra CSS classes on outer section

BEM classes

foundry-contact-split
foundry-contact-split__content
foundry-contact-split__control
foundry-contact-split__control--textarea
foundry-contact-split__field
foundry-contact-split__form
foundry-contact-split__form-panel
foundry-contact-split__form-text
foundry-contact-split__form-title
foundry-contact-split__inner
foundry-contact-split__meta-card
foundry-contact-split__meta-card--address
foundry-contact-split__meta-card--email
foundry-contact-split__meta-card--hours
foundry-contact-split__meta-card--phone
foundry-contact-split__meta-label
foundry-contact-split__meta-link
foundry-contact-split__meta-list
foundry-contact-split__meta-value
foundry-contact-split__privacy
foundry-contact-split__submit
foundry-contact-split__subtitle
foundry-contact-split__title

content-sidebar-nav

Minimum required: items — everything else is optional. Content layout block with sidebar anchor/navigation area.

sections:
- block: content-sidebar-nav
  id: content-sidebar-nav-example
  content:
    items:
    - title: Item title
      text: Item description.
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-content-sidebar-nav
foundry-content-sidebar-nav__content
foundry-content-sidebar-nav__inner
foundry-content-sidebar-nav__nav
foundry-content-sidebar-nav__nav-item

cta

Minimum required: title — everything else is optional. Focused call-to-action block with copy and action buttons.

sections:
- block: cta
  id: cta-example
  content:
    primary_action:
      text: Learn more
      url: "/contact/"
    secondary_action:
      text: Learn more
      url: "/contact/"
    text: Example supporting text.
    title: Example title
  design:
    variant: centered
    css_class: ''

Design options

Field	Details
`variants`	`centered`, `left`
`variant`	centered \| left — text and action alignment
`css_class`	extra CSS classes on outer section

BEM classes

foundry-cta
foundry-cta__actions
foundry-cta__inner
foundry-cta__panel
foundry-cta__text
foundry-cta__title

cta-button-list

Minimum required: buttons — everything else is optional. CTA block presenting multiple button actions as a grouped list.

sections:
- block: cta-button-list
  id: cta-button-list-example
  content:
    buttons: Example value
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-cta-button-list
foundry-cta-button-list__grid
foundry-cta-button-list__inner
foundry-cta-button-list__item
foundry-cta-button-list__text
foundry-cta-button-list__title

cta-image-paragraph

Minimum required: items — everything else is optional. CTA block pairing image support with concise conversion copy.

sections:
- block: cta-image-paragraph
  id: cta-image-paragraph-example
  content:
    items:
    - title: Item title
      text: Item description.
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-cta-image-paragraph
foundry-cta-image-paragraph__actions
foundry-cta-image-paragraph__content
foundry-cta-image-paragraph__inner
foundry-cta-image-paragraph__media
foundry-cta-image-paragraph__text
foundry-cta-image-paragraph__title

divider

Minimum required: (none) — everything else is optional. Visual separator block for rhythm and transitions between sections.

sections:
- block: divider
  id: divider-example
  content:
    text: Example supporting text.
  design:
    variant: line
    spacing: md
    css_class: ''

Design options

Field	Details
`variants`	`line`, `gradient`, `wave`, `spacer`
`variant`	line \| gradient \| wave \| spacer — divider style
`spacing`	sm \| md \| lg \| xl — vertical rhythm
`css_class`	extra CSS classes on divider wrapper

BEM classes

foundry-divider
foundry-divider__inner

embed

Minimum required: url — everything else is optional. Safe iframe embed block for maps, tools, and third-party widgets.

sections:
- block: embed
  id: embed-example
  content:
    fallback_text: Open source link
    fallback_url: https://example.com/fallback
    text: Example supporting text.
    title: Example title
    url: https://example.com
  design:
    variant: card
    aspect: '16:9'
    height: default
    css_class: ''

Design options

Field	Details
`variants`	`card`, `flush`, `minimal`
`variant`	card \| flush \| minimal — iframe wrapper style
`aspect`	16:9 \| 4:3 \| 1:1 \| map — default ratio when height is unset
`height`	fixed height value (for example: 450px), overrides aspect
`css_class`	extra CSS classes on outer section

BEM classes

foundry-embed
foundry-embed__empty
foundry-embed__fallback
foundry-embed__figure
foundry-embed__frame
foundry-embed__frame-wrap
foundry-embed__inner
foundry-embed__shell
foundry-embed__subtitle
foundry-embed__title

faq-accordion

Minimum required: items — everything else is optional. FAQ-specific accordion block with question/answer structure.

sections:
- block: faq-accordion
  id: faq-accordion-example
  content:
    items:
    - title: Item title
      text: Item description.
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	`cards`, `flush`, `grouped`
`variant`	cards \| flush \| grouped — cards: rounded card per item (default); flush: divider-only, no card backgrounds; grouped: items with optional `group` field rendered as section headings
`css_class`	extra CSS classes on outer section

For grouped, add a group field to each item to place it under a heading. Items without a group are rendered first with no heading.

BEM classes

foundry-faq-accordion
foundry-faq-accordion__answer
foundry-faq-accordion__group
foundry-faq-accordion__inner
foundry-faq-accordion__item
foundry-faq-accordion__list
foundry-faq-accordion__question
foundry-faq-accordion__title

faq-cta

Minimum required: items, cta_title, cta_action — everything else is optional. FAQ companion CTA block used to drive follow-up actions.

sections:
- block: faq-cta
  id: faq-cta-example
  content:
    cta_action: Example value
    cta_secondary_action: Example value
    cta_text: Example value
    cta_title: Example value
    items:
    - title: Item title
      text: Item description.
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-faq-cta
foundry-faq-cta__actions
foundry-faq-cta__inner
foundry-faq-cta__text
foundry-faq-cta__title

features

Minimum required: items — everything else is optional. Feature list/grid block with optional card presentation, linked-card support, and icon support.

sections:
- block: features
  id: features-example
  content:
    eyebrow: Example eyebrow
    items:
    - name: Item title
      description: Item description.
      url: /about/
      cta: Read more
      css_class: example-item
    text: Example supporting text.
    title: Example title
  design:
    variant: linked-cards
    columns: '3'
    css_class: ''

Content fields

eyebrow or kicker for a small label above the title
item name or title
item description or text
item url and cta for the linked-cards variant
item css_class for per-card styling hooks

Design options

Field	Details
`variants`	`cards`, `plain`, `linked-cards`
`variant`	cards \| plain \| linked-cards — card styling, borderless, or linked CTA cards
`columns`	2 \| 3 \| 4 — grid columns (default: 3)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-features
foundry-features__eyebrow
foundry-features__grid
foundry-features__inner
foundry-features__item
foundry-features__item-cta
foundry-features__item-icon
foundry-features__item-link
foundry-features__item-text
foundry-features__item-title
foundry-features__text
foundry-features__title

founder-profile

Minimum required: name — everything else is optional. Founder spotlight/profile block with media and narrative copy.

sections:
- block: founder-profile
  id: founder-profile-example
  content:
    contact_email_href: Example value
    contact_email_label: Example value
    contact_phone_href: Example value
    contact_phone_label: Example value
    highlights: Example value
    image: "/images/example.jpg"
    image_alt: Descriptive alt text
    image_height: Example value
    image_sizes: Example value
    image_srcset: Example value
    image_webp_srcset: Example value
    image_width: Example value
    name: Example value
    paragraphs: Example value
    role: Role or title
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-founder-profile
foundry-founder-profile__content
foundry-founder-profile__inner
foundry-founder-profile__media
foundry-founder-profile__text
foundry-founder-profile__title

gallery

Minimum required: images — everything else is optional. Uniform image grid with optional captions and lightbox navigation.

sections:
- block: gallery
  id: gallery-example
  content:
    images:
    - src: "/images/gallery-1.jpg"
      alt: Gallery image
      caption: Optional caption
    images_data: "site.section.images"
    text: Example supporting text.
    title: Example title
  design:
    columns: '3'
    gap: md
    aspect: '16:9'
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`columns`	2 \| 3 \| 4 — gallery columns
`gap`	sm \| md \| lg — spacing between items
`aspect`	square \| landscape \| auto — thumbnail ratio
`css_class`	extra CSS classes on outer section

BEM classes

foundry-gallery
foundry-gallery__close
foundry-gallery__dialog
foundry-gallery__dialog-actions
foundry-gallery__dialog-caption
foundry-gallery__dialog-image
foundry-gallery__dialog-inner
foundry-gallery__dialog-meta
foundry-gallery__empty
foundry-gallery__grid
foundry-gallery__image
foundry-gallery__inner
foundry-gallery__item
foundry-gallery__open
foundry-gallery__subtitle
foundry-gallery__title

hero

Minimum required: title — everything else is optional. Primary hero section with headline, supporting copy, and one or two CTAs.

sections:
- block: hero
  id: hero-example
  content:
    primary_action:
      text: Learn more
      url: "/contact/"
    secondary_action:
      text: Learn more
      url: "/contact/"
    text: Example supporting text.
    title: Example title
  design:
    variant: centered
    css_class: ''

Design options

Field	Details
`variants`	`centered`, `left`
`variant`	centered \| left — text and action alignment
`css_class`	extra CSS classes on outer section

BEM classes

foundry-hero
foundry-hero__actions
foundry-hero__inner
foundry-hero__text
foundry-hero__title

icon-grid

Minimum required: items — everything else is optional. Icon-led capability grid with configurable columns and card styles.

sections:
- block: icon-grid
  id: icon-grid-example
  content:
    items:
    - title: Item title
      text: Item description.
    text: Example supporting text.
    title: Example title
  design:
    variant: plain
    columns: '3'
    css_class: ''

Design options

Field	Details
`variants`	`plain`, `cards`, `centered`
`variant`	plain \| cards \| centered — plain: icon left + content right (default); cards: card background per item; centered: icon centered above content, centered text
`columns`	2 \| 3 \| 4 — grid columns
`css_class`	extra CSS classes on outer section

BEM classes

foundry-icon-grid
foundry-icon-grid__content
foundry-icon-grid__grid
foundry-icon-grid__icon
foundry-icon-grid__inner
foundry-icon-grid__item
foundry-icon-grid__item-inner
foundry-icon-grid__item-text
foundry-icon-grid__item-title
foundry-icon-grid__subtitle
foundry-icon-grid__title

illustration-panel

Minimum required: image — everything else is optional. Panel block that combines illustration media with explanatory text.

sections:
- block: illustration-panel
  id: illustration-panel-example
  content:
    caption: Optional caption text.
    image: "/images/example.jpg"
    image_alt: Descriptive alt text
    panel_width: Example value
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-illustration-panel
foundry-illustration-panel__content
foundry-illustration-panel__inner
foundry-illustration-panel__media
foundry-illustration-panel__text

image-feature

Minimum required: src, alt — everything else is optional. Single editorial image block with layout, caption, and lightbox options.

sections:
- block: image-feature
  id: image-feature-example
  content:
    alt: Descriptive alt text
    caption: Optional caption text.
    credit: 'Photo: Team'
    src: "/images/example.jpg"
  design:
    variant: contained
    aspect: '16:9'
    rounded: true
    shadow: true
    lightbox: true
    css_class: ''

Design options

Field	Details
`variants`	`contained`, `wide`, `full-bleed`, `float-left`, `float-right`
`variant`	contained \| wide \| full-bleed \| float-left \| float-right — image placement
`aspect`	16:9 \| 4:3 \| 3:2 \| square \| auto — media aspect ratio
`rounded`	true \| false — rounded corners on media
`shadow`	true \| false — shadow on media frame
`lightbox`	true \| false — open image in dialog lightbox
`css_class`	extra CSS classes on outer section

BEM classes

foundry-image-feature
foundry-image-feature__caption
foundry-image-feature__close
foundry-image-feature__dialog
foundry-image-feature__dialog-inner
foundry-image-feature__empty
foundry-image-feature__figure
foundry-image-feature__inner
foundry-image-feature__media

lead-magnet

Minimum required: offer_title — everything else is optional. Lead magnet signup block combining offer copy and form capture.

sections:
- block: lead-magnet
  id: lead-magnet-example
  content:
    download_url: Example value
    fields: Example value
    form_action: "/api/submit"
    form_method: Example value
    form_text: Example value
    form_title: Example value
    offer_text: Example value
    offer_title: Example value
    privacy_note: No spam. Unsubscribe anytime.
    submit_text: Example value
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Legacy mode uses form_action. Managed mode uses content.form and resolves base_url / site_key from site.Params.foundry.control when available.

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-lead-magnet
foundry-lead-magnet__form
foundry-lead-magnet__inner
foundry-lead-magnet__text
foundry-lead-magnet__title

logo-trust

Minimum required: logos, badges — everything else is optional. Hybrid trust block combining logos with supporting credibility chips.

sections:
- block: logo-trust
  id: logo-trust-example
  content:
    badges: Example value
    logos:
    - name: Partner Name
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-logo-trust
foundry-logo-trust__badges
foundry-logo-trust__grid
foundry-logo-trust__image
foundry-logo-trust__inner
foundry-logo-trust__item
foundry-logo-trust__name
foundry-logo-trust__subtitle
foundry-logo-trust__title

logos

Minimum required: logos — everything else is optional. Logo wall block for clients, partners, or agencies.

sections:
- block: logos
  id: logos-example
  content:
    logos:
    - name: Partner Name
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	`grid`, `strip`, `pill`
`variant`	grid \| strip \| pill — grid: 3-col card grid (default); strip: flat inline row with dividers; pill: compact pill chips
`marquee`	true \| false — enable scrolling marquee (overrides variant layout)
`marquee_speed`	scroll speed in px/s (default: 55)
`marquee_dir`	left \| right — scroll direction (default: left)
`marquee_pause`	hover \| none — pause behavior (default: hover)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-logos
foundry-logos__grid
foundry-logos__inner
foundry-logos__item
foundry-logos__title

map-coverage

Minimum required: image, stats — everything else is optional. Geographic coverage block combining map visuals and supporting text.

sections:
- block: map-coverage
  id: map-coverage-example
  content:
    image: "/images/example.jpg"
    image_alt: Descriptive alt text
    markers: Example value
    note: Example value
    stats:
    - label: Metric
      value: 95%
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-map-coverage
foundry-map-coverage__inner
foundry-map-coverage__map
foundry-map-coverage__text
foundry-map-coverage__title

masonry-gallery

Minimum required: one of images or images_data — everything else is optional. Responsive masonry-style image gallery with optional lightbox.

sections:
- block: masonry-gallery
  id: masonry-gallery-example
  content:
    images:
    - src: "/images/gallery-1.jpg"
      alt: Gallery image
      caption: Optional caption
    images_data: "site.section.images"
    text: Example supporting text.
    title: Example title
  design:
    columns: '3'
    gap: md
    lightbox: true
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`columns`	2 \| 3 \| 4 — desktop masonry columns
`gap`	sm \| md \| lg — spacing between items
`lightbox`	true \| false — open images in dialog lightbox
`css_class`	extra CSS classes on outer section

Notes

Use images for inline page-specific galleries.
Use images_data to point at a shared data slice such as site.section.images when multiple pages should reuse the same curated image set.
limit can trim a shared image slice for teaser use on home or landing pages.

BEM classes

foundry-masonry-gallery
foundry-masonry-gallery__columns
foundry-masonry-gallery__dialog
foundry-masonry-gallery__dialog-inner
foundry-masonry-gallery__empty
foundry-masonry-gallery__inner
foundry-masonry-gallery__item
foundry-masonry-gallery__open
foundry-masonry-gallery__subtitle
foundry-masonry-gallery__title

managed-form

Minimum required: form.form_key — everything else is optional. Managed form mount point for Foundry-connected intake, lead, and CTA flows.

sections:
- block: managed-form
  id: managed-form-example
  content:
    eyebrow: Example value
    title: Example title
    text: Supporting copy for the form.
    loading_text: Loading form...
    privacy_note: No spam. Unsubscribe anytime.
    form:
      mode: managed
      form_key: contact-intake
      cta_key: primary-cta
      base_url: https://control.example.com
      site_key: restricted proof consumer
  design:
    css_class: ''

The block renders a managed form shell and resolves the final configuration through layouts/partials/framework/form-config.html. When base_url or site_key are omitted inline, the shared Foundry control settings can supply them.

Design options

Field	Details
`variant`	`narrow` \| `wide` \| `panel` — narrow: max-w-3xl centered (default); wide: max-w-5xl for multi-field forms; panel: framed card with surface background
`css_class`	extra CSS classes on outer section

BEM classes

foundry-managed-form
foundry-managed-form__eyebrow
foundry-managed-form__inner
foundry-managed-form__privacy
foundry-managed-form__status
foundry-managed-form__text
foundry-managed-form__title

media-break

Minimum required: src, alt — everything else is optional. Full-bleed image or MP4 video break for editorial pages: use it between prose sections for Munich-style fixed image moments, or as a slower-than-scroll parallax visual beat with optional overlay copy.

sections:
- block: media-break
  id: consultation-room-break
  content:
    src: "/images/consultation-room.jpg"
    alt: restricted proof consumer consultation room
    eyebrow: Consultation
    title: The room slows down.
    text: A visual pause can sit between article sections without becoming a full pinned chapter.
    caption: Optional caption text.
  design:
    behavior: parallax
    height: 88svh
    min_height: 30rem
    overlay: medium
    content_align: left
    title_tag: h2
    position: center 42%
    parallax_speed: "0.12"
    parallax_dir: up
    css_class: ''

Use behavior: fixed for a desktop background-attachment: fixed image break that feels locked behind the page as the visitor scrolls through it. Use behavior: parallax when the image should drift upward more slowly than the scroll rate. Use behavior: still for a quiet full-bleed image or video break with no scroll-linked motion.

Design options

Field	Details
`variants`	`parallax`, `fixed`, `still`
`behavior`	parallax \| fixed \| still — parallax drifts the media slower than scroll, fixed uses desktop background-attachment, still renders a static full-bleed media break
`height`	CSS length for section height (default: 88svh)
`min_height`	CSS length for section minimum height (default: 28rem)
`overlay`	none \| light \| medium \| strong — media shade behind optional copy
`content_align`	left \| center \| right — optional overlay copy alignment
`title_tag`	h1 \| h2 — optional overlay title element for hero vs in-page use (default: h2)
`position`	CSS object-position/background-position value (default: center center)
`parallax_speed`	0.0-0.35 — viewport fraction used for slower-than-scroll drift (default: 0.14)
`parallax_dir`	up \| down — media drift direction as the visitor scrolls (default: up)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-media-break
foundry-media-break__action
foundry-media-break__asset
foundry-media-break__caption
foundry-media-break__content
foundry-media-break__copy
foundry-media-break__empty
foundry-media-break__eyebrow
foundry-media-break__fixed-bg
foundry-media-break__layer
foundry-media-break__media
foundry-media-break__shade
foundry-media-break__text
foundry-media-break__title

media-sequence

Minimum required: items — everything else is optional. Mixed image/video/text storytelling block for creative pages, showcases, and editorial case-study sequences.

sections:
- block: media-sequence
  id: media-sequence-example
  content:
    text: Example supporting text.
    title: Example title
    items:
    - type: image
      title: First frame
      text: Supporting description.
      src: "/images/example.jpg"
      alt: Descriptive alt text
      caption: Caption text
      credit: Photo credit
    - type: video
      title: Motion frame
      text: Supporting description.
      url: "/video/example.mp4"
      poster: "/images/example-poster.jpg"
      caption: Video caption
    - type: quote
      quote: This sequence should feel authored, not templated.
      author: Example author
  design:
    variant: editorial
    media_ratio: landscape
    media_surface: framed
    spacing: md
    css_class: ''

Design options

Field	Details
`variants`	`editorial`, `alternating`, `cinematic`
`variant`	editorial \| alternating \| cinematic — mixed-media storytelling layout
`media_ratio`	landscape \| square \| portrait \| wide \| auto — default media aspect ratio
`media_surface`	framed \| flush \| soft — default media frame treatment
`spacing`	sm \| md \| lg — vertical rhythm between sequence items
`css_class`	extra CSS classes on outer section

BEM classes

foundry-media-sequence
foundry-media-sequence__body
foundry-media-sequence__credits-item
foundry-media-sequence__eyebrow
foundry-media-sequence__gallery
foundry-media-sequence__image
foundry-media-sequence__inner
foundry-media-sequence__intro
foundry-media-sequence__item
foundry-media-sequence__items
foundry-media-sequence__media
foundry-media-sequence__media-shell
foundry-media-sequence__quote
foundry-media-sequence__text-item
foundry-media-sequence__title

pinned-media-story

Minimum required: items — everything else is optional. Full-viewport scroll story where each image or MP4 video pins to the back of the viewport while its chapter copy scrolls over it.

sections:
- block: pinned-media-story
  id: city-scroll-story
  content:
    eyebrow: City guide
    title: A day in motion
    text: Pair each chapter with the visual that should lock behind it.
    primary_action:
      text: Plan a visit
      url: /visit/
    items:
    - type: video
      title: Morning arrival
      text: The opening chapter scrolls while the video remains fixed behind it.
      src: "/video/arrival.mp4"
      poster: "/images/arrival-poster.jpg"
      caption: Short contextual caption.
    - type: image
      title: Market streets
      text: Images use the same pinned treatment as video.
      images:
      - src: "/images/market-01.jpg"
        alt: People walking through a city market
        kenburns_preset: in-left
        position: center center
      - src: "/images/market-02.jpg"
        alt: Vendor arranging goods at a city market
        kenburns_preset: out-right
        position: 55% center
      panels:
      - eyebrow: First stop
        title: Market streets
        text: The same pinned media can hold more than one scroll-over text beat.
      - eyebrow: Second stop
        title: Still the same visual
        text: Use panels when one image or rotator should stay locked behind several content moments.
      credit: Photo credit
  design:
    variant: dark
    min_height: 120vh
    overlay: medium
    content_align: left
    intro_title_tag: h2
    kenburns: true
    kenburns_interval: 7200
    media_parallax: true
    media_parallax_speed: "0.14"
    media_parallax_dir: up
    css_class: ''

Design options

Field	Details
`variants`	`dark`, `light`, `editorial`
`variant`	dark \| light \| editorial — pinned full-viewport media storytelling palette
`min_height`	CSS length for each chapter scroll span (default: 120vh)
`overlay`	none \| light \| medium \| strong — media shade behind copy
`content_align`	left \| center \| right — chapter text alignment
`intro_title_tag`	h1 \| h2 — intro title element for top-hero vs in-page section use (default: h2)
`kenburns`	true \| false — enable/disable Ken Burns rotation for image chapters; item-level kenburns can override
`kenburns_interval`	milliseconds between chapter image crossfades (default: 7200)
`kenburns_transition`	milliseconds for crossfade duration between chapter images (default: 1400)
`media_parallax`	true \| false — move the media layer slower than scroll inside each pinned chapter; item-level media_parallax can override
`media_parallax_speed`	0.0-0.35 — viewport fraction used for pinned media drift (default: 0.16)
`media_parallax_dir`	up \| down — drift direction as the visitor scrolls (default: up)
`css_class`	extra CSS classes on outer section

Item-level panels can be used when one pinned image, image rotator, or MP4 should carry several scroll-over text moments. If panels is omitted, the item renders one panel from its own eyebrow, title, text, caption, credit, and action fields.

For the Munich-style rhythm of text block, fixed/slower image, then next text box, prefer media-break. Use pinned-media-story when chapter copy should scroll over a media plane, or when one image/rotator should remain locked behind several text beats. Start with min_height: 115vh to 135vh for a single-panel chapter. Each additional panel adds another full-viewport text beat over the same pinned image; increase the item min_height only when the image should linger after the last panel. Use media_parallax_dir: up for the natural image-upward drift while scrolling; media_parallax_speed: "0.10" to "0.16" is editorial and subtle, while "0.20" to "0.28" is more obvious.

BEM classes

foundry-pinned-media-story
foundry-pinned-media-story__actions
foundry-pinned-media-story__asset
foundry-pinned-media-story__caption
foundry-pinned-media-story__chapter
foundry-pinned-media-story__chapter-eyebrow
foundry-pinned-media-story__chapter-text
foundry-pinned-media-story__chapter-title
foundry-pinned-media-story__chapters
foundry-pinned-media-story__content
foundry-pinned-media-story__credit
foundry-pinned-media-story__eyebrow
foundry-pinned-media-story__intro
foundry-pinned-media-story__media
foundry-pinned-media-story__panel
foundry-pinned-media-story__panel-stack
foundry-pinned-media-story__parallax-layer
foundry-pinned-media-story__rotator
foundry-pinned-media-story__shade
foundry-pinned-media-story__text
foundry-pinned-media-story__title

media-text

Minimum required: title, text, image - everything else is optional. Split layout block pairing media with descriptive copy and actions.

sections:
- block: media-text
  id: media-text-example
  content:
    eyebrow: Section label
    image: "/images/example.jpg"
    image_alt: Descriptive alt text
    items:
    - title: Item title
      text: Item description.
    kicker: Example value
    media_caption: Example value
    primary_action:
      text: Learn more
      url: "/contact/"
    secondary_action:
      text: Learn more
      url: "/contact/"
    text: Example supporting text.
    title: Example title
  design:
    density: normal
    frame: card
    layout: balanced
    media_fit: cover
    media_position: left
    media_ratio: landscape
    text_measure: normal
    vertical_align: center
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`media_position`	left \| right - media placement
`media_ratio`	landscape \| square \| portrait \| wide - media aspect ratio
`layout`	balanced \| media-wide \| content-wide \| stacked - media/content column balance
`vertical_align`	center \| start \| end - vertical alignment between media and copy
`text_measure`	normal \| narrow \| wide - copy width constraint
`density`	normal \| compact \| spacious - vertical spacing and grid gap
`frame`	card \| plain \| borderless - media frame treatment
`media_fit`	cover \| contain - image fit inside the media frame
`motion_parallax`	number string - optional parallax speed for the media column
`motion_parallax_dir`	1 \| -1 - optional media column parallax direction
`css_class`	extra CSS classes on outer section

Non-default layout example

sections:
- block: media-text
  id: media-text-editorial-example
  content:
    title: Editorial image with wider copy
    text: Use additive design fields when the same media/copy pattern needs a different balance or rhythm.
    image: "/images/example-editorial.jpg"
    image_alt: Editorial detail image
  design:
    layout: content-wide
    vertical_align: start
    text_measure: wide
    density: spacious
    frame: plain
    media_fit: contain

BEM classes

foundry-media-text
foundry-media-text__actions
foundry-media-text__caption
foundry-media-text__content
foundry-media-text__eyebrow
foundry-media-text__image
foundry-media-text__inner
foundry-media-text__item
foundry-media-text__item-icon
foundry-media-text__items
foundry-media-text__media
foundry-media-text__media-frame
foundry-media-text__text
foundry-media-text__title

Minimum required: none — everything else is optional. Inline email signup form for lead capture inside content flow.

sections:
- block: newsletter-inline
  id: newsletter-inline-example
  content:
    button_text: Submit
    form_action: "/api/submit"
    placeholder: you@example.com
    privacy_note: No spam. Unsubscribe anytime.
    text: Example supporting text.
    title: Example title
  design:
    variant: card
    css_class: ''

Legacy mode uses form_action. Managed mode uses content.form and the standard Foundry Control public form API.

Design options

Field	Details
`variants`	`card`, `banner`, `minimal`
`variant`	card \| banner \| minimal — form presentation
`css_class`	extra CSS classes on outer section

BEM classes

foundry-newsletter-inline
foundry-newsletter-inline__inner

onboarding-timeline

Minimum required: steps — everything else is optional. Structured onboarding sequence block with phase milestones.

sections:
- block: onboarding-timeline
  id: onboarding-timeline-example
  content:
    steps:
    - title: Step title
      text: Step detail.
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-onboarding-timeline
foundry-onboarding-timeline__content
foundry-onboarding-timeline__inner
foundry-onboarding-timeline__item
foundry-onboarding-timeline__list
foundry-onboarding-timeline__number
foundry-onboarding-timeline__title

page-list

Minimum required: section — everything else is optional. Generic content listing block for section pages with card/list/compact modes.

sections:
- block: page-list
  id: page-list-example
  content:
    limit: 6
    section: blog
    sort: date
    text: Example supporting text.
    title: Example title
  design:
    view: default
    columns: '3'
    show_date: true
    show_summary: true
    show_image: true
    css_class: ''

Design options

Field	Details
`variants`	`cards`, `list`, `compact`
`view`	cards \| list \| compact — listing layout mode
`columns`	2 \| 3 — grid columns for cards mode
`show_date`	true \| false — show publish date
`show_summary`	true \| false — show excerpt text
`show_image`	true \| false — show thumbnails
`css_class`	extra CSS classes on outer section

BEM classes

foundry-page-list
foundry-page-list__actions
foundry-page-list__body
foundry-page-list__card
foundry-page-list__compact
foundry-page-list__compact-item
foundry-page-list__empty
foundry-page-list__grid
foundry-page-list__image
foundry-page-list__image-link
foundry-page-list__inner
foundry-page-list__item-title
foundry-page-list__list
foundry-page-list__list-item
foundry-page-list__list-layout
foundry-page-list__meta
foundry-page-list__subtitle
foundry-page-list__summary
foundry-page-list__title

post-hero

Minimum required: title — everything else is optional. Article-oriented hero with metadata, author context, and optional featured image.

sections:
- block: post-hero
  id: post-hero-example
  content:
    author_image: "/images/example.jpg"
    author_name: Author Name
    author_role: Example value
    category: Example Group
    date: '2026-02-22'
    image: "/images/example.jpg"
    image_alt: Descriptive alt text
    read_time: 5 min read
    tags:
    - compliance
    - operations
    text: Example supporting text.
    title: Example title
  design:
    variant: centered
    css_class: ''

Design options

Field	Details
`variants`	`centered`, `split`, `stacked`
`variant`	centered \| split \| stacked — article hero layout
`css_class`	extra CSS classes on outer section

BEM classes

foundry-post-hero
foundry-post-hero__author
foundry-post-hero__content
foundry-post-hero__date
foundry-post-hero__image
foundry-post-hero__inner
foundry-post-hero__media
foundry-post-hero__meta
foundry-post-hero__read-time
foundry-post-hero__split
foundry-post-hero__standfirst
foundry-post-hero__tags
foundry-post-hero__title

post-list

Minimum required: section — everything else is optional. Enhanced blog list block with featured item support and richer card layouts.

sections:
- block: post-list
  id: post-list-example
  content:
    cta:
      text: Learn more
      url: "/contact/"
    featured_first: true
    limit: 6
    section: blog
    sort: date
    text: Example supporting text.
    title: Example title
  design:
    view: default
    columns: '3'
    show_date: true
    show_summary: true
    show_image: true
    show_category: true
    css_class: ''

Design options

Field	Details
`variants`	`cards`, `list`, `magazine`
`view`	cards \| list \| magazine — listing layout mode
`columns`	2 \| 3 — grid columns for cards mode
`show_date`	true \| false — show publish date
`show_summary`	true \| false — show excerpt text
`show_image`	true \| false — show thumbnails
`show_category`	true \| false — show category badge
`css_class`	extra CSS classes on outer section

BEM classes

foundry-post-list
foundry-post-list__card
foundry-post-list__cta
foundry-post-list__empty
foundry-post-list__featured
foundry-post-list__grid
foundry-post-list__inner
foundry-post-list__list
foundry-post-list__list-item
foundry-post-list__magazine
foundry-post-list__magazine-item
foundry-post-list__magazine-lead
foundry-post-list__magazine-stack
foundry-post-list__subtitle
foundry-post-list__title

content-feed

Minimum required: none — query fields are optional but recommended. Query-driven discovery feed that filters pages using normalized discovery metadata instead of section-only listing.

sections:
- block: content-feed
  id: content-feed-example
  content:
    eyebrow: Discover
    title: Latest Articles for Operators
    text: Curated from shared discovery metadata.
    empty_text: No matching content yet.
    cta:
      text: View all articles
      url: "/blog/"
    query:
      kinds: [article]
      sections: [blog]
      topics: []
      audience: []
      series: []
      categories: []
      tags: []
      languages: []
      featured_only: false
      exclude_current: true
      limit: 3
      sort: newest
  design:
    view: cards
    columns: '3'
    show_image: true
    show_summary: true
    show_date: true
    show_kind: true
    show_topics: false
    show_audience: false
    css_class: ''

Query semantics

OR within a field
AND across different fields
empty languages defaults to the current page language

Supported query fields

kinds
sections
topics
audience
series
categories
tags
languages
featured_only
exclude_current
limit
sort

Sort values

newest
oldest
title
featured
manual

manual sorts by search.order, then page weight, then newest date.

Design options

Field	Details
`view`	cards \| list \| compact — feed layout mode
`columns`	2 \| 3 \| 4 — cards grid columns
`show_image`	true \| false — show thumbnails
`show_summary`	true \| false — show excerpt text
`show_date`	true \| false — show publish date
`show_kind`	true \| false — show kind badge
`show_topics`	true \| false — show topic badges
`show_audience`	true \| false — show audience badge
`css_class`	extra CSS classes on outer section

BEM classes

foundry-content-feed
foundry-content-feed__compact
foundry-content-feed__compact-item
foundry-content-feed__cta
foundry-content-feed__card
foundry-content-feed__empty
foundry-content-feed__eyebrow
foundry-content-feed__grid
foundry-content-feed__inner
foundry-content-feed__list
foundry-content-feed__list-item
foundry-content-feed__text
foundry-content-feed__title

pricing-comparison

Minimum required: plans — everything else is optional. Pricing comparison matrix block across plans or competitors.

sections:
- block: pricing-comparison
  id: pricing-comparison-example
  content:
    plans: Example value
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-pricing-comparison
foundry-pricing-comparison__cell
foundry-pricing-comparison__inner
foundry-pricing-comparison__row
foundry-pricing-comparison__table
foundry-pricing-comparison__tier
foundry-pricing-comparison__title

pricing-tiers

Minimum required: tiers — everything else is optional. Tiered pricing card block with features and emphasis controls.

sections:
- block: pricing-tiers
  id: pricing-tiers-example
  content:
    tiers: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	`grid`, `featured`, `stacked`
`variant`	grid \| featured \| stacked — grid: 3 equal cards (default); featured: tier with `featured: true` gets brand-accent elevated treatment; stacked: full-width rows with feature list
`css_class`	extra CSS classes on outer section

Set featured: true on a tier to elevate it in the featured variant.

BEM classes

foundry-pricing-tiers
foundry-pricing-tiers__card
foundry-pricing-tiers__features
foundry-pricing-tiers__grid
foundry-pricing-tiers__inner
foundry-pricing-tiers__price
foundry-pricing-tiers__title

prose-panel

Minimum required: text — everything else is optional. Contained prose block for narrative or explainer content.

sections:
- block: prose-panel
  id: prose-panel-example
  content:
    text: Example supporting text.
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-prose-panel
foundry-prose-panel__content
foundry-prose-panel__inner

pullquote

Minimum required: quote — everything else is optional. Editorial pull-quote emphasis block for long-form content.

sections:
- block: pullquote
  id: pullquote-example
  content:
    author: Author Name
    quote: A representative quote for this block.
    role: Role or title
  design:
    variant: accent-bar
    align: center
    css_class: ''

Design options

Field	Details
`variants`	`accent-bar`, `filled`, `oversized`, `minimal`
`variant`	accent-bar \| filled \| oversized \| minimal — pullquote styling
`align`	center \| left — quote alignment
`css_class`	extra CSS classes on outer section

BEM classes

foundry-pullquote
foundry-pullquote__attribution
foundry-pullquote__box
foundry-pullquote__inner
foundry-pullquote__quote

quote

Minimum required: quote — everything else is optional. Standalone quotation block for prominent statements with attribution.

sections:
- block: quote
  id: quote-example
  content:
    author: Author Name
    image: "/images/example.jpg"
    quote: A representative quote for this block.
    role: Role or title
  design:
    variant: centered
    css_class: ''

Design options

Field	Details
`variants`	`centered`, `left`, `large`
`variant`	centered \| left \| large — quote presentation
`css_class`	extra CSS classes on outer section

BEM classes

foundry-quote
foundry-quote__author-text
foundry-quote__author-wrap
foundry-quote__figure
foundry-quote__inner
foundry-quote__mark
foundry-quote__meta
foundry-quote__text

Minimum required: section — everything else is optional. Related content recommendation block sourced from a section.

sections:
- block: related-posts
  id: related-posts-example
  content:
    exclude_current: true
    limit: 6
    section: blog
    title: Example title
  design:
    view: default
    css_class: ''

Design options

Field	Details
`variants`	`cards`, `compact`
`view`	cards \| compact — related links layout
`css_class`	extra CSS classes on outer section

BEM classes

foundry-related-posts
foundry-related-posts__card
foundry-related-posts__compact
foundry-related-posts__grid
foundry-related-posts__inner
foundry-related-posts__title

resource-downloads

Minimum required: resources — everything else is optional. Download resource listing block with item metadata.

sections:
- block: resource-downloads
  id: resource-downloads-example
  content:
    email_placeholder: Example value
    form_action: "/api/submit"
    form_title: Example value
    privacy_note: No spam. Unsubscribe anytime.
    resources: Example value
    submit_text: Example value
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Legacy mode uses form_action. Managed mode uses content.form and the standard Foundry Control public form API.

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-resource-downloads
foundry-resource-downloads__grid
foundry-resource-downloads__inner
foundry-resource-downloads__item
foundry-resource-downloads__link
foundry-resource-downloads__title

rich-text

Minimum required: text — everything else is optional. Long-form prose block with editorial layout variants.

sections:
- block: rich-text
  id: rich-text-example
  content:
    dropcap: true
    text: Example supporting text.
  design:
    variant: centered
    max_width: default
    css_class: ''

Design options

Field	Details
`variants`	`centered`, `wide`, `two-column`, `magazine`
`variant`	centered \| wide \| two-column \| magazine — article layout
`max_width`	prose \| md \| lg \| xl \| full — container width
`css_class`	extra CSS classes on outer section

BEM classes

foundry-rich-text
foundry-rich-text__body
foundry-rich-text__inner

search

Minimum required: none — everything else is optional. Static-site search interface powered by Pagefind with Foundry styling and graceful fallback.

sections:
- block: search
  id: search-example
  content:
    eyebrow: Search
    title: Search the site
    text: Find pages, docs, and resources.
    placeholder: Search...
    loading_text: Loading search index...
    empty_text: Start typing to search.
    zero_state_title: Start with a treatment, topic, or audience
    zero_state_text: Use search directly or begin with one of the curated paths below.
    no_results_text: No matching results found.
    no_results_title: No exact matches
    no_results_panel_text: Try a broader term, adjust the filters, or choose a guided next step.
    unavailable_text: Search index unavailable.
    clear_filters_text: Clear filters
    clear_all_text: Clear all
    sort_label: Sort
    sort_option_labels:
      relevance: Best match
      newest: Newest first
    overlay_title: Quick search
    overlay_text: Jump to the most relevant pages.
    overlay_placeholder: Search treatments, articles, and pages...
    overlay_empty_text: Start with a search, suggestion, or quick link.
    overlay_loading_text: Searching...
    overlay_no_results_text: No exact matches yet.
    overlay_view_all_text: View all results
    overlay_close_label: Close search
    overlay_shortcut_text: Press / or Cmd/Ctrl+K
    overlay_suggested_queries:
      - label: Botox
        query: botox
    overlay_quick_links:
      - label: Treatments
        url: /treatments/
        description: Explore treatment categories.
    overlay_no_results_actions:
      - label: Contact
        url: /contact/
        description: Ask for help.
    filter_labels:
      kind: Type
      topic: Topic
      audience: Audience
    filter_all_labels:
      kind: All types
      topic: All topics
      audience: All audiences
  design:
    variant: default
    show_images: true
    show_sub_results: false
    excerpt_length: 22
    debounce: 250
    filter_fields: [kind, topic, audience]
    primary_filter_field: kind
    sort_options: [relevance, newest]
    default_sort: relevance
    sync_query_to_url: true
    overlay_enabled: true
    overlay_results_limit: 5
    overlay_min_query_length: 2
    overlay_debounce: 160
    css_class: ''

Design options

Field	Details
`variants`	`default`, `minimal`
`variant`	default \| minimal — search panel style
`show_images`	true \| false — include thumbnails in results
`show_sub_results`	true \| false — include sub-result snippets
`excerpt_length`	number of words shown in result excerpt
`debounce`	debounce in milliseconds before querying
`filter_fields`	comma list or array of discovery filters to render
`primary_filter_field`	optional field rendered as tabs instead of a select
`sort_options`	optional sort values rendered as the full-page sort control
`default_sort`	optional default sort value; defaults to the first configured option
`sync_query_to_url`	true \| false — keep `q` and `filter.*` state in the URL
`overlay_enabled`	true \| false — enable the global quick-search overlay from this localized block
`overlay_results_limit`	number of overlay results shown before linking to the full page
`overlay_min_query_length`	minimum characters before the overlay starts querying
`overlay_debounce`	overlay debounce in milliseconds
`css_class`	extra CSS classes on outer section

Optional content fields

Field	Details
`clear_filters_text`	text for the filter reset control
`clear_all_text`	text for the summary-level reset that clears query and filters
`sort_label`	label shown above the full-page sort control
`sort_option_labels`	map of sort option labels keyed by sort value
`filter_labels`	map of field labels keyed by filter name
`filter_all_labels`	map of default option labels keyed by filter name
`zero_state_title`	heading shown in the full-page zero state
`zero_state_text`	supporting copy shown in the full-page zero state
`zero_state_suggested_queries_label`	heading above the full-page zero-state query chips
`zero_state_quick_links_label`	heading above the full-page zero-state quick links
`zero_state_suggested_queries`	list of `{ label, query }` chips shown before any search runs
`zero_state_quick_links`	list of `{ label, url, description }` links shown in the full-page zero state
`no_results_title`	heading shown when the full-page search returns no matches
`no_results_panel_text`	supporting copy shown in the full-page no-results state
`no_results_suggested_queries_label`	heading above the full-page no-results query chips
`no_results_actions_label`	heading above the full-page no-results recovery links
`no_results_suggested_queries`	list of `{ label, query }` chips shown when there are no matches
`no_results_actions`	list of `{ label, url, description }` recovery links shown when there are no matches
`overlay_title`	heading shown in the quick-search overlay
`overlay_text`	supporting copy in the quick-search overlay
`overlay_placeholder`	overlay input placeholder
`overlay_empty_text`	zero-state copy shown before a search runs
`overlay_loading_text`	overlay loading message
`overlay_no_results_text`	overlay empty-results message
`overlay_view_all_text`	CTA label that opens the full search page
`overlay_close_label`	accessible label for closing the overlay
`overlay_shortcut_text`	helper text for keyboard shortcuts
`overlay_suggested_queries_label`	heading above the overlay suggestion chips
`overlay_quick_links_label`	heading above the overlay quick links
`overlay_recovery_label`	heading above the overlay no-results actions
`overlay_suggested_queries`	list of `{ label, query }` suggestion chips
`overlay_quick_links`	list of `{ label, url, description }` links shown in zero state
`overlay_no_results_actions`	list of `{ label, url, description }` recovery actions

Discovery metadata

Search and future discovery blocks resolve page metadata through the shared partial "foundry/helpers/discovery-model.html" helper.

Preferred front matter:

search:
  exclude: false
  kind: article
  section: blog
  topics: [neurotoxin]
  audience: [men]
  series: []
  featured: false
  order: 0
  summary: ""
  image: ""
  image_alt: ""

Backward-compatible aliases still supported by the resolver:

search_exclude -> search.exclude
search_section -> search.section
audience -> search.audience
featured -> search.featured
featured_image / image / og_image -> search.image
page or param description/summary -> search.summary

Current Pagefind emission uses the normalized model for:

kind
topic
audience
series
section
category
author
tag
language

URL state

The search block hydrates from shared URL parameters on load:

q=<query>
repeated filter.kind=<slug>
repeated filter.topic=<slug>
repeated filter.audience=<slug>
repeated filter.series=<slug>
optional sort=<value>

If the page loads with filters but no q, Foundry runs a filter-only Pagefind query so filtered discovery links can land on a meaningful result set.

Filter controls use design.filter_fields and pull option labels from data/foundry/discovery.yaml when that registry is available.

If design.primary_filter_field matches one of those fields, Foundry renders it as a primary tab bar and keeps the remaining filters in the secondary control row.

If design.overlay_enabled is true, Foundry uses the localized search block content as the source for the global quick-search overlay triggered from the shared search button, /, or Cmd/Ctrl+K.

The overlay supports keyboard focus trapping, arrow-key result navigation, and a mobile-first sheet layout while preserving the normal /search/ link as the no-JS fallback.

BEM classes

foundry-search
foundry-search__app
foundry-search__eyebrow
foundry-search__inner
foundry-search__mount
foundry-search__noscript
foundry-search__panel
foundry-search__status
foundry-search__text
foundry-search__title

Optional component tokens

Themes can skin the shared search UI without selector overrides by setting optional --foundry-search-* tokens. The most useful ones are:

--foundry-search-panel-bg
--foundry-search-panel-shadow
--foundry-search-input-border
--foundry-search-input-bg
--foundry-search-clear-border
--foundry-search-clear-bg
--foundry-search-filter-label-color
--foundry-search-filter-border
--foundry-search-filter-bg
--foundry-search-filter-color
--foundry-search-filter-focus-border
--foundry-search-filter-focus-ring
--foundry-search-reset-color
--foundry-search-reset-hover-color
--foundry-search-tabbar-label-color
--foundry-search-tab-bg
--foundry-search-tab-border
--foundry-search-tab-color
--foundry-search-tab-active-bg
--foundry-search-tab-active-border
--foundry-search-tab-active-color
--foundry-search-summary-border
--foundry-search-summary-bg
--foundry-search-summary-chip-bg
--foundry-search-summary-chip-border
--foundry-search-summary-chip-color
--foundry-search-summary-clear-color
--foundry-search-summary-clear-hover-color
--foundry-search-overlay-backdrop
--foundry-search-overlay-surface
--foundry-search-overlay-border
--foundry-search-overlay-shadow
--foundry-search-overlay-chip-bg
--foundry-search-overlay-chip-border
--foundry-search-overlay-chip-color
--foundry-search-overlay-link-bg
--foundry-search-overlay-link-border
--foundry-search-overlay-link-hover-border
--foundry-search-overlay-link-shadow
--foundry-search-card-radius
--foundry-search-card-border
--foundry-search-card-bg
--foundry-search-card-shadow
--foundry-search-card-hover-shadow
--foundry-search-media-border
--foundry-search-pill-bg
--foundry-search-pill-color
--foundry-search-title-hover
--foundry-search-tag-bg
--foundry-search-tag-color

All of these fall back to the global --foundry-* tokens if they are not set by a theme.

section-header

Minimum required: title — everything else is optional. Reusable heading intro block used to start a section consistently.

sections:
- block: section-header
  id: section-header-example
  content:
    cta:
      text: Learn more
      url: "/contact/"
    eyebrow: Section label
    text: Example supporting text.
    title: Example title
  design:
    align: center
    size: lg
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`align`	center \| left — heading alignment
`size`	sm \| md \| lg \| xl — heading scale
`css_class`	extra CSS classes on outer section

BEM classes

foundry-section-header
foundry-section-header__cta
foundry-section-header__eyebrow
foundry-section-header__inner
foundry-section-header__text
foundry-section-header__title

slideshow

Minimum required: slides — everything else is optional. Auto-advancing slideshow/carousel with optional overlays and controls.

sections:
- block: slideshow
  id: slideshow-example
  content:
    slides:
    - src: "/images/slide-1.jpg"
      alt: Slide image
      title: Slide title
      text: Slide copy
    text: Example supporting text.
    title: Example title
  design:
    variant: fade
    aspect: '16:9'
    autoplay: true
    interval: 5000
    show_dots: true
    show_arrows: true
    show_overlay: true
    css_class: ''

Design options

Field	Details
`variants`	`fade`, `slide`, `cards`
`variant`	fade \| slide \| cards — transition style
`aspect`	16:9 \| 4:3 \| 21:9 \| auto — viewport ratio
`autoplay`	true \| false — auto-advance slides
`interval`	milliseconds between slide advances (default: 5000)
`show_dots`	true \| false — dot navigation visibility
`show_arrows`	true \| false — arrow navigation visibility
`show_overlay`	true \| false — caption overlay visibility
`css_class`	extra CSS classes on outer section

BEM classes

foundry-slideshow
foundry-slideshow__arrow
foundry-slideshow__arrow--next
foundry-slideshow__arrow--prev
foundry-slideshow__dot
foundry-slideshow__dots
foundry-slideshow__empty
foundry-slideshow__frames
foundry-slideshow__inner
foundry-slideshow__overlay
foundry-slideshow__slide
foundry-slideshow__stack
foundry-slideshow__subtitle
foundry-slideshow__title
foundry-slideshow__track
foundry-slideshow__viewport

Minimum required: platforms — everything else is optional. Share controls for social and copy-link actions.

sections:
- block: social-share
  id: social-share-example
  content:
    platforms:
    - twitter
    - linkedin
    - email
    title: Example title
  design:
    variant: buttons
    css_class: ''

Design options

Field	Details
`variants`	`buttons`, `icons`, `minimal`
`variant`	buttons \| icons \| minimal — share control style
`css_class`	extra CSS classes on outer section

BEM classes

foundry-social-share
foundry-social-share__button
foundry-social-share__button--copy
foundry-social-share__inner
foundry-social-share__list
foundry-social-share__status
foundry-social-share__title

stats-band

Minimum required: stats — everything else is optional. Horizontal KPI/statistics band with palette variants.

sections:
- block: stats-band
  id: stats-band-example
  content:
    stats:
    - label: Metric
      value: 95%
    subtitle: Example value
    title: Example title
  design:
    variant: dark
    css_class: ''

Design options

Field	Details
`variants`	`dark`, `light`, `brand`
`variant`	dark \| light \| brand — band palette
`css_class`	extra CSS classes on outer section

BEM classes

foundry-stats-band
foundry-stats-band--brand
foundry-stats-band--dark
foundry-stats-band--light
foundry-stats-band__grid
foundry-stats-band__inner
foundry-stats-band__item
foundry-stats-band__label
foundry-stats-band__subtitle
foundry-stats-band__title
foundry-stats-band__value

stats-grid

Minimum required: stats — everything else is optional. Grid-based statistics block for grouped numeric highlights.

sections:
- block: stats-grid
  id: stats-grid-example
  content:
    stats:
    - label: Metric
      value: 95%
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	`grid`, `band`, `highlighted`
`variant`	grid \| band \| highlighted — grid: 4-col centered cards (default); band: horizontal inline row, no card wrappers; highlighted: brand-accent colored cards
`css_class`	extra CSS classes on outer section

BEM classes

foundry-stats-grid
foundry-stats-grid__grid
foundry-stats-grid__inner
foundry-stats-grid__item
foundry-stats-grid__label
foundry-stats-grid__title
foundry-stats-grid__value

steps

Minimum required: steps — everything else is optional. Step-by-step process block with numbered or icon-based steps. Generated number badges and Step N footers automatically hide when a title already starts with the matching step number.

sections:
- block: steps
  id: steps-example
  content:
    steps:
    - title: Step title
      text: Step detail.
    subtitle: Example value
    title: Example title
  design:
    variant: cards
    columns: '3'
    show_icons: true
    show_marker: auto
    show_meta: auto
    css_class: ''

Design options

Field	Details
`variants`	`cards`, `plain`, `numbered`
`variant`	cards \| plain \| numbered — cards: card per step (default); plain: no card background; numbered: large editorial step number above text, no badge circle
`columns`	2 \| 3 \| 4 — grid columns
`show_icons`	true \| false — use step icon instead of numbers
`show_marker`	auto \| true \| false — control the generated badge; `auto` hides it when the title already includes the matching number
`show_meta`	auto \| true \| false — control the generated `Step N` footer; `auto` hides it when the title already includes the matching number
`css_class`	extra CSS classes on outer section

BEM classes

foundry-steps
foundry-steps__content
foundry-steps__grid
foundry-steps__inner
foundry-steps__item
foundry-steps__item-inner
foundry-steps__item-meta
foundry-steps__item-text
foundry-steps__item-title
foundry-steps__number
foundry-steps__subtitle
foundry-steps__title

table-of-contents

Minimum required: (none) — everything else is optional. Manual or auto-generated anchor navigation block for long pages.

sections:
- block: table-of-contents
  id: table-of-contents-example
  content:
    title: Example title
  design:
    variant: sidebar
    depth: 3
    numbered: true
    mobile: compact
    progress: true
    sticky: true
    css_class: ''

Sidebar mode now includes active-section tracking, completed-state styling hooks, a progress rail, and compact mobile behavior by default. The widget also respects the shared header offset so anchor jumps land below fixed headers.

Design options

Field	Details
`variants`	`sidebar`, `inline`, `compact`
`variant`	sidebar \| inline \| compact — TOC container style
`depth`	2 \| 3 — heading depth when auto-generating
`numbered`	true \| false — ordered list vs unordered list
`mobile`	compact \| expanded — compact sticky mobile toggle vs always-open list
`progress`	true \| false — show the scroll progress rail inside the widget
`sticky`	true \| false — keep the widget pinned on larger viewports
`css_class`	extra CSS classes on outer section

BEM classes

foundry-table-of-contents
foundry-table-of-contents__auto
foundry-table-of-contents__current
foundry-table-of-contents__head
foundry-table-of-contents__inner
foundry-table-of-contents__item
foundry-table-of-contents__link
foundry-table-of-contents__list
foundry-table-of-contents__panel
foundry-table-of-contents__progress
foundry-table-of-contents__title
foundry-table-of-contents__toggle
foundry-table-of-contents__widget

tabs

Minimum required: tabs — everything else is optional. Tabbed content block for switching between related panels.

sections:
- block: tabs
  id: tabs-example
  content:
    tabs:
    - label: Overview
      text: Tab content.
    title: Example title
  design:
    variant: underline
    css_class: ''

Design options

Field	Details
`variants`	`underline`, `pills`, `bordered`
`variant`	underline \| pills \| bordered — tab trigger style
`css_class`	extra CSS classes on outer section

BEM classes

foundry-tabs
foundry-tabs__controls
foundry-tabs__empty
foundry-tabs__inner
foundry-tabs__panel
foundry-tabs__panels
foundry-tabs__tab
foundry-tabs__tablist
foundry-tabs__title

team-grid

Minimum required: members — everything else is optional. Team member grid block with role and bio summaries.

sections:
- block: team-grid
  id: team-grid-example
  content:
    members: Example value
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	`grid`, `compact`, `list`
`variant`	grid \| compact \| list — grid: 3-col cards with bio (default); compact: 4-col, no bio, photo+name+role; list: horizontal rows, photo left + full bio
`css_class`	extra CSS classes on outer section

BEM classes

foundry-team-grid
foundry-team-grid__card
foundry-team-grid__grid
foundry-team-grid__inner
foundry-team-grid__name
foundry-team-grid__role
foundry-team-grid__title

testimonials

Minimum required: testimonials — everything else is optional. Static testimonial grid block for social proof.

sections:
- block: testimonials
  id: testimonials-example
  content:
    subtitle: Example value
    testimonials:
    - quote: Strong result quote.
      author: Client Name
      rating: 5
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	`grid`, `featured`, `stacked`
`variant`	grid \| featured \| stacked — grid: 3-col card grid (default); featured: first quote large + 2-col supporting; stacked: single centered column
`css_class`	extra CSS classes on outer section

BEM classes

foundry-testimonials
foundry-testimonials__author
foundry-testimonials__featured
foundry-testimonials__grid
foundry-testimonials__inner
foundry-testimonials__item
foundry-testimonials__quote
foundry-testimonials__stack
foundry-testimonials__title

testimonials-carousel

Minimum required: testimonials — everything else is optional. Scrollable testimonial carousel for longer quote sets.

sections:
- block: testimonials-carousel
  id: testimonials-carousel-example
  content:
    subtitle: Example value
    testimonials:
    - quote: Strong result quote.
      author: Client Name
      rating: 5
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-testimonials-carousel
foundry-testimonials-carousel__author
foundry-testimonials-carousel__icon
foundry-testimonials-carousel__icon-wrap
foundry-testimonials-carousel__inner
foundry-testimonials-carousel__item
foundry-testimonials-carousel__meta
foundry-testimonials-carousel__quote
foundry-testimonials-carousel__rating
foundry-testimonials-carousel__role
foundry-testimonials-carousel__subtitle
foundry-testimonials-carousel__title
foundry-testimonials-carousel__track

timeline

Minimum required: events — everything else is optional. Chronological timeline block for milestones and sequences.

sections:
- block: timeline
  id: timeline-example
  content:
    events: Example value
    subtitle: Example value
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	`vertical`, `cards`, `compact`
`variant`	vertical \| cards \| compact — vertical: left-border spine (default); cards: standalone card grid, no spine; compact: tighter spine for long lists
`css_class`	extra CSS classes on outer section

BEM classes

foundry-timeline
foundry-timeline__content
foundry-timeline__inner
foundry-timeline__item
foundry-timeline__list
foundry-timeline__marker
foundry-timeline__title

topic-chip-nav

Minimum required: items — everything else is optional. Topic chip navigation block for quick in-page or inter-page filtering.

sections:
- block: topic-chip-nav
  id: topic-chip-nav-example
  content:
    items:
    - title: Item title
      text: Item description.
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-topic-chip-nav
foundry-topic-chip-nav__chip
foundry-topic-chip-nav__inner
foundry-topic-chip-nav__list
foundry-topic-chip-nav__title

trust-badges

Minimum required: items — everything else is optional. Badge strip for compliance, trust, and credibility signals.

sections:
- block: trust-badges
  id: trust-badges-example
  content:
    items:
    - title: Item title
      text: Item description.
    title: Example title
  design:
    css_class: ''

Design options

Field	Details
`variant`	`chips` \| `logos` \| `list` — chips: flex-wrap badge chips (default); logos: image-first grayscale tiles (uses `items[].image`); list: vertical checkmark list for certifications
`css_class`	extra CSS classes on outer section

BEM classes

foundry-trust-badges
foundry-trust-badges__grid
foundry-trust-badges__inner
foundry-trust-badges__item
foundry-trust-badges__list
foundry-trust-badges__logo
foundry-trust-badges__title

video-embed

Minimum required: url — everything else is optional. Privacy-first video embed block supporting YouTube, Vimeo, and MP4.

sections:
- block: video-embed
  id: video-embed-example
  content:
    caption: Optional caption text.
    poster: "/images/example.jpg"
    text: Example supporting text.
    title: Example title
    transcript: Transcript excerpt goes here.
    url: https://example.com
  design:
    variant: standard
    aspect: '16:9'
    autoplay: true
    css_class: ''

Design options

Field	Details
`variants`	`standard`, `cinema`, `card`
`variant`	standard \| cinema \| card — video frame presentation
`aspect`	16:9 \| 4:3 \| 1:1 \| 9:16 — embed ratio
`autoplay`	true \| false — autoplay for self-hosted video
`css_class`	extra CSS classes on outer section

BEM classes

foundry-video-embed
foundry-video-embed__caption
foundry-video-embed__empty
foundry-video-embed__figure
foundry-video-embed__frame
foundry-video-embed__iframe
foundry-video-embed__inner
foundry-video-embed__play
foundry-video-embed__poster
foundry-video-embed__poster-placeholder
foundry-video-embed__shell
foundry-video-embed__subtitle
foundry-video-embed__title
foundry-video-embed__transcript

video-hero

Minimum required: title, text — everything else is optional. Hero block with video/media backdrop treatment.

sections:
- block: video-hero
  id: video-hero-example
  content:
    bullets: Example value
    eyebrow: Section label
    image: "/images/example.jpg"
    image_alt: Descriptive alt text
    primary_action:
      text: Learn more
      url: "/contact/"
    secondary_action:
      text: Learn more
      url: "/contact/"
    text: Example supporting text.
    title: Example title
    video_caption: Example value
    video_poster: Example value
    video_url: Example value
  design:
    css_class: ''

Design options

Field	Details
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-video-hero
foundry-video-hero__actions
foundry-video-hero__inner
foundry-video-hero__media
foundry-video-hero__overlay
foundry-video-hero__text
foundry-video-hero__title

full-bleed-split

Minimum required: title, text — everything else is optional. Cinematic editorial split layout with full-height media and structured narrative content.

sections:
- block: full-bleed-split
  id: full-bleed-example
  content:
    eyebrow: The property
    title: One house. Nothing held back.
    text: A narrative section pairing full-bleed imagery with editorial copy.
    items:
    - Indoor hot tub porch
    - Sauna and cold shower
    image: /images/property-detail.jpg
    image_alt: Property detail image
    primary_action:
      text: Explore spaces
      url: /property/
  design:
    image_position: right
    bg: light
    parallax: true
    parallax_speed: '0.2'
    parallax_dir: '-1'
    kenburns: true
    kenburns_interval: '8000'
    reveal: slide-left
    css_class: ''

Design options

Field	Details
`variants`	(none)
`image_position`	right \| left — image column position
`min_height`	80vh \| 100vh \| 70vh — section minimum height
`bg`	light \| dark \| stone \| cream — section palette
`parallax`	true \| false — enable/disable image parallax
`parallax_speed`	number string — parallax speed (default: 0.2)
`parallax_dir`	1 \| -1 — parallax direction
`kenburns`	true \| false — enable/disable image Ken Burns
`kenburns_interval`	milliseconds for multi-image crossfade
`reveal`	slide-right \| slide-left \| fade-up \| fade-in — text reveal style
`css_class`	extra CSS classes on outer section

BEM classes

foundry-full-bleed-split

motion-hero

Minimum required: title - everything else is optional. Full-screen motion-forward hero showcasing reveal, parallax, and Ken Burns engines in one section.

sections:
- block: motion-hero
  id: motion-hero-example
  content:
    eyebrow: Foundry motion toolkit
    title: Scroll-native motion, zero dependencies.
    text: Demonstrates layered parallax and optional Ken Burns image cycling.
    background_images:
    - /images/motion-hero-1.jpg
    - /images/motion-hero-2.jpg
    primary_action:
      text: See live demos
      url: /motion/
    secondary_action:
      text: View reference
      url: /docs/
  design:
    parallax: true
    parallax_back_speed: '0.25'
    parallax_front_speed: '0.45'
    parallax_front_dir: '-1'
    kenburns: true
    kenburns_interval: '6000'
    kenburns_transition: '1400'
    show_badges: true
    overlay_strength: current
    overlay_tone: current
    content_align: center
    min_height: screen
    scroll_nudge: true
    badge_style: engine

Use the additive visual controls when a site needs theme-safe presentation tuning without forking the block partial:

sections:
- block: motion-hero
  content:
    title: Cinematic without a local fork
    text: Left-aligned copy, neutral overlay, and proof badges using the same motion runtime.
    badges:
    - label: Proof badge
    - label: Brand-safe
  design:
    overlay_strength: medium
    overlay_tone: neutral
    content_align: left
    min_height: large
    scroll_nudge: false
    badge_style: proof

Design options

Field	Details
`variants`	(none)
`parallax`	true \| false - enable/disable parallax layers
`kenburns`	true \| false - enable/disable Ken Burns background cycling
`show_badges`	true \| false - show/hide badge row
`overlay_strength`	current \| none \| soft \| medium \| strong - overlay shade strength; `current` preserves legacy output
`overlay_tone`	current \| neutral \| warm \| cool \| brand - overlay color mood
`content_align`	center \| left - hero copy and action alignment
`min_height`	screen \| large \| medium - hero minimum height
`scroll_nudge`	true \| false - show/hide decorative scroll cue
`badge_style`	engine \| proof \| none - engine demo badges, content proof badges, or no badge row
`parallax_back_speed`	number string - background parallax speed (default: 0.25)
`parallax_front_speed`	number string - foreground parallax speed (default: 0.45)
`parallax_front_dir`	1 \| -1 - foreground parallax direction
`kenburns_interval`	milliseconds between background image crossfades (default: 6000)
`kenburns_transition`	milliseconds for crossfade duration between images (default: 1400)

BEM classes

foundry-motion-hero

property-amenities

Minimum required: title, plus one of signature_items or signature_items_data, one of categories or categories_data, and one of included_items or included_items_data. Editorial property-amenity showcase with signature cards, pill-nav panels on desktop, and stacked/accordion panels on mobile.

sections:
- block: property-amenities
  id: property-amenities-example
  content:
    eyebrow: Everything included
    title: The version guests can scan in 30 seconds.
    text: Surface the signature perks first, then group the room and utility details by category.
    signature_items:
    - badge: Wellness suite
      title: Recovery rituals built into the stay.
      text: Hot tub, sauna, and cold-plunge access without leaving the house.
      image: /images/property/hot-tub.jpg
      image_alt: Glass-enclosed wellness patio
      icon: sparkles
    categories:
    - label: Gather & Cook
      title: A real kitchen and places to use it.
      text: Group the rooms together instead of repeating a long amenity dump.
      image: /images/property/kitchen.jpg
      image_alt: Kitchen and dining area
      icon: fire
      items:
      - Full kitchen with range, oven, dishwasher, cookware, and utensils
      - Dining table sized for the full group
      - Living room or hearth space connected to the kitchen
    included_items:
    - High-speed WiFi
    - Fresh linens and bath towels
    - Parking on the property
  design:
    variant: editorial
    nav_style: pills
    css_class: ''

Design options

Field	Details
`variants`	`editorial`
`variant`	editorial — signature-card and grouped-panel presentation
`nav_style`	pills — desktop category trigger style
`css_class`	extra CSS classes on outer section

Notes

signature_items should normally contain 3-6 cards.
Use signature_items_data, categories_data, and included_items_data when the same amenity story needs to stay aligned across a retreat page, photo-tour page, and downstream proof fixture.
categories should normally contain 3-5 grouped panels.
categories[].items may be either simple strings or objects with title and text.
When a category lacks dedicated photography, omit image and provide icon; the block will render support art instead.

Shared-data example

sections:
- block: property-amenities
  content:
    title: Shared amenity story
    signature_items_data: "property.retreat.signature_items"
    categories_data: "property.retreat.categories"
    included_items_data: "property.retreat.included_items"

BEM classes

foundry-property-amenities
foundry-property-amenities__inner
foundry-property-amenities__signature-grid
foundry-property-amenities__signature-card
foundry-property-amenities__controls
foundry-property-amenities__tab
foundry-property-amenities__panel
foundry-property-amenities__mobile-stack
foundry-property-amenities__included

property-photo-tour

Minimum required: title, plus one of categories or categories_data. Category-driven property photo tour with room-type tabs on desktop and stacked sections on mobile.

sections:
- block: property-photo-tour
  id: property-photo-tour-example
  content:
    eyebrow: Photo tour
    title: Let guests browse the stay by space.
    text: Group photos by room type and keep each category curated instead of dumping every image onto the page.
    categories:
    - label: Arrival & Exterior
      title: Start with the outside impression.
      text: Orient the guest before they get into the room details.
      icon: home
      items:
      - Front facade and arrival sequence
      - Exterior angles that prove privacy and setting
      images:
      - url: /images/property/exterior-01.jpg
        alt: Front facade at golden hour
        caption: Arrival view.
      - url: /images/property/exterior-02.jpg
        alt: Exterior side angle
        caption: Exterior angle.
    - label: Living Spaces
      title: Shared rooms first.
      text: Show the rooms people use together before the support spaces.
      icon: fire
      items:
      - Living room wide shot
      - Kitchen usability angle
      - Dining view that shows scale
      images:
      - url: /images/property/living-01.jpg
        alt: Living room with fireplace
        caption: Main living area.
      - url: /images/property/kitchen-01.jpg
        alt: Kitchen and dining area
        caption: Kitchen and dining.
    categories_data: "site.property.photo_tour"
  design:
    variant: editorial
    nav_style: pills
    css_class: ''

Design options

Field	Details
`variants`	`editorial`
`variant`	editorial — grouped photo tour with featured image and supporting grid
`nav_style`	pills — desktop category trigger style
`css_class`	extra CSS classes on outer section

Notes

categories should normally contain 4-7 groups.
Use categories_data when the same photo-tour structure should power a full tour page and smaller previews elsewhere.
categories[].images should be curated, not exhaustive; 3-6 strong photos per group usually reads best.
Use room types or meaningful visual groupings, not arbitrary upload order.
Keep narrative selling copy on the property page and use this block for visual proof.
limit can trim the number of categories when you want a shorter preview from the same shared source.

BEM classes

foundry-property-photo-tour
foundry-property-photo-tour__inner
foundry-property-photo-tour__controls
foundry-property-photo-tour__tab
foundry-property-photo-tour__panel
foundry-property-photo-tour__featured
foundry-property-photo-tour__thumb-grid
foundry-property-photo-tour__mobile-stack
foundry-property-photo-tour__dialog

property-cards

Minimum required: properties — everything else is optional. Card grid for property/space highlights with optional featured card treatment.

sections:
- block: property-cards
  id: property-cards-example
  content:
    eyebrow: Signature spaces
    title: Rooms and amenities worth the stay.
    text: Showcase interiors, wellness features, and outdoor living.
    properties:
    - name: Indoor hot tub porch
      label: Wellness
      description: Enclosed glass porch with all-season hot tub views.
      image: /images/hot-tub.jpg
      beds: 2 bedrooms + additional sleeping
      size: 4 private acres
      price: Extended stay from $X / month
      url: /property/
      featured: true
    - name: Sauna suite
      label: Recovery
      description: Sauna, full shower, and cold bucket ritual.
      image: /images/sauna.jpg
      url: /property/
  design:
    columns: '3'
    variant: cards
    item_reveal: zoom-in
    css_class: ''

Design options

Field	Details
`variants`	`cards`, `editorial`
`variant`	cards \| editorial — listing presentation
`columns`	2 \| 3 — grid columns
`item_reveal`	fade-up \| zoom-in \| fade-in — per-card reveal animation
`css_class`	extra CSS classes on outer section

BEM classes

foundry-property-cards
foundry-property-cards__inner
foundry-property-cards__eyebrow
foundry-property-cards__title
foundry-property-cards__text
foundry-property-cards__grid

property-hero

Minimum required: title — everything else is optional. Cinematic property hero with optional video background, Ken Burns imagery, and estate stats strip.

sections:
- block: property-hero
  id: property-hero-example
  content:
    eyebrow: Back Mountain · Pennsylvania
    title: Away from the noise. Everything you need.
    subtitle: First Light
    text: A private house on four acres with indoor hot tub and sauna suite.
    images:
    - /images/hero-1.jpg
    - /images/hero-2.jpg
    - /images/hero-3.jpg
    primary_action:
      text: Explore First Light
      url: /property/
    secondary_action:
      text: Plan your stay
      url: /inquire/
    stat_1_value: 4 Acres
    stat_1_label: Private setting
    stat_2_value: 2 Weeks+
    stat_2_label: Minimum stay
    stat_3_value: 8-10
    stat_3_label: Guests
  design:
    overlay: deep
    parallax: true
    parallax_speed: '0.35'
    parallax_dir: '1'
    kenburns: true
    kenburns_interval: '5000'
    text_align: left
    min_height: 100vh
    show_scroll: true

Design options

Field	Details
`variants`	(none)
`overlay`	dark \| light \| deep \| warm — hero overlay treatment
`parallax`	true \| false — enable/disable background parallax
`parallax_speed`	number string — parallax speed (default: 0.35)
`parallax_dir`	1 \| -1 — parallax direction
`kenburns`	true \| false — enable/disable Ken Burns motion
`kenburns_interval`	milliseconds for multi-image crossfade (default: 6000)
`text_align`	left \| center — content alignment
`min_height`	100vh \| 80vh \| 70vh — section minimum height
`show_scroll`	true \| false — show/hide scroll indicator

BEM classes

foundry-property-hero
foundry-property-hero__scroll

Creating a new block

Copy layouts/partials/blocks/_template.html to layouts/partials/blocks/[block-name].html.
Replace placeholders and implement the block using standard context extraction and BEM classes.
Register the block in data/foundry/block-registry.yaml.
Document variants/design fields in data/foundry/block-options.yaml.
Add usage examples in /docs/BLOCKS.md and your demo content.
If motion is needed, use data-motion-* attributes and keep reduced-motion behavior safe.

Feature flags

Feature flags are resolved by foundry/helpers/feature-flag.html.

Flag	Default(s) in templates	Blocks using it
`animations`	`true`	`stats-band`
`experimentalHero`	`false`	`hero`
`uiCards`	`true`	`case-studies`, `certification-badges`, `cta`, `faq-cta`, `features`, `icon-grid`, `illustration-panel`, `pricing-comparison`, `pricing-tiers`, `resource-downloads`, `stats-grid`, `steps`, `testimonials`, `testimonials-carousel`, `trust-badges`