v0.2.2 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.16
Policy: release-bound

Component pins for v0.2.2

Component	Role	Version
core	runtime	`v0.1.16`
theme-shield	theme	`v0.1.15`
restricted-component-1	brand-theme	`v0.1.5`
dark-mode	runtime-addon	`v0.1.0`
i18n	runtime-addon	`v0.1.0`
starter	reference	`v0.1.3`
docs	reference	`v0.1.4`
distribution	tooling	`v0.3.1`
restricted-component-2	consumer-reference	`v0.1.5`
restricted-component-3	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 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 site.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
`variants`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-before-after
foundry-before-after__inner
foundry-before-after__label
foundry-before-after__panels
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
`variants`	`info`, `tip`, `warning`, `danger`, `note`, `success`
`type`	info \| tip \| warning \| danger \| note \| success — semantic intent style
`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`	None (single style)
`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
`variants`	None (single style)
`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`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-faq-accordion
foundry-faq-accordion__answer
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
    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`
`variant`	plain \| cards — item treatment
`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`	None (single style)
`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: images — 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
    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

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

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:
    media_position: left
    media_ratio: landscape
    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
`css_class`	extra CSS classes on outer section

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

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`	None (single style)
`css_class`	extra CSS classes on outer section

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.
    no_results_text: No matching results found.
    unavailable_text: Search index unavailable.
  design:
    variant: default
    show_images: true
    show_sub_results: false
    excerpt_length: 22
    debounce: 250
    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
`css_class`	extra CSS classes on outer section

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-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`	None (single style)
`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`
`variant`	cards \| plain — step card styling
`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`	None (single style)
`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`	None (single style)
`css_class`	extra CSS classes on outer section

BEM classes

foundry-testimonials
foundry-testimonials__author
foundry-testimonials__grid
foundry-testimonials__inner
foundry-testimonials__item
foundry-testimonials__quote
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`	None (single style)
`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
`variants`	None (single style)
`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__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'
    show_badges: true

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 engine badges
`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)

BEM classes

foundry-motion-hero

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`

Block Index

How blocks work

Block standards (BEM, CSS vars, context extraction)

CSS variable system

Motion CSS variables

Motion attributes

Block catalog (alphabetical)

accordion

audio-player

author-bio

before-after

callout

case-studies

certification-badges

columns

coming-soon-cta

coming-soon-footer

coming-soon-hero

coming-soon-trust

comparison-table

contact-split

content-sidebar-nav

cta

cta-button-list

cta-image-paragraph

divider

embed

faq-accordion

faq-cta

features

founder-profile

gallery

hero

icon-grid

illustration-panel

image-feature

lead-magnet

logo-trust

logos

map-coverage

masonry-gallery

media-text

newsletter-inline

onboarding-timeline

page-list

post-hero

post-list

pricing-comparison

pricing-tiers

prose-panel

pullquote

quote

related-posts

resource-downloads

rich-text

search

section-header

slideshow

social-share

stats-band

stats-grid

steps

table-of-contents

tabs

team-grid

testimonials

testimonials-carousel

timeline

topic-chip-nav

trust-badges

video-embed

video-hero

full-bleed-split

motion-hero

property-cards

property-hero

Creating a new block

Feature flags

Related documentation