Block reference

Block Index

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-feed | content-sidebar-nav | cta | cta-button-list | cta-image-paragraph | discovery-cards | divider | embed | faq-accordion | faq-cta | features | founder-profile | full-bleed-split | gallery | guided-discovery | hero | icon-grid | illustration-panel | image-feature | lead-magnet | logo-trust | logos | managed-form | managed-form-panel | map-coverage | masonry-gallery | media-break | media-sequence | media-text | motion-hero | newsletter-inline | onboarding-timeline | page-list | pinned-media-story | post-hero | post-list | pricing-comparison | pricing-tiers | property-amenities | property-cards | property-hero | property-photo-tour | prose-panel | pullquote | quote | related-posts | relationship-map | resource-downloads | rich-text | routing-panels | search | section-header | slideshow | social-preview-grid | 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

How blocks work

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

1. layouts/partials/framework/render-sections.html iterates sections.
2. It resolves each block name through Core’s data/foundry/block-registry.yaml, merged with an optional consumer-owned data/foundry/site-block-registry.yaml.
3. The mapped partial in layouts/partials/blocks/ is rendered with { page, section } context.
4. 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: ""

Portable editor contract

data/foundry/block-schemas.json may add an editor object with typed content_fields and design_fields. Foundry v0.1.29 defines this contract for the hero, media-text, gallery, cta, and managed-form golden blocks. Those templates emit matching field-level preview anchors when params.foundry.preview_metadata.enabled is true.

The current human-control projections also cover steps for ordered Process content, search for functional utility behavior, and the Simple Content wave: section-header, rich-text, quote, and callout. The Proof Content wave adds stats-band, testimonials, and trust-badges; the Answers & Disclosure wave adds accordion and faq-accordion. See the Portable Authoring Contract for the complete active surface and DC03-S10 Answers And Disclosure Controls for the preferred disclosure and Hugo source experience.

Every typed field in the derived report includes preview.scope: section and a deterministic preview.selector. Select the intended section wrapper first, then query the field selector inside it; querying a suffix selector across the whole page is ambiguous when blocks repeat. See Portable Authoring Contract.

When preview metadata is enabled and the rendered page is embedded, Core also loads its portable field-selection sender. Pointer, Enter, and Space selection emit foundry.preview-selection.v1 to the immediate parent. The sender never persists workflow state; the editor remains responsible for exact source and origin validation plus contract-backed field validation.

Use the derived contract instead of reverse-engineering templates:

foundry authoring-contract --site /path/to/site --json

The report schema is schemas/foundry/authoring-contract.schema.json. The command is read-only. It includes both family catalogs, every block’s section-family chooser memberships, all block variants and normalized design controls, the shared section-flow controls, and portable menu options. A managed editor may consume the report but must keep repo-visible content and configuration as the portable source of truth.

Its editor_expansion matrix covers every public Section Type and prevents a consumer from equating technical block options with finished human Controls. Only complete entries have a verified normal projection; other Sections stay source-editable while their bounded expansion, reusable primitive, or guided advanced experience is completed. See DC03-S7 Editor Expansion Matrix.

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.

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”.

Social & Presence contract

Social & Presence blocks render normalized foundry.social_item.v1 items. Blocks do not call provider APIs and do not require connected accounts.

Supported source modes:

• curated: editor-selected media, caption, date, permalink, and platform.
• embed: public URL or embeddable URL with a fallback link/card.
• static-import: importer output that has already been materialized as normal site data.
• api: connected-account output that has already been materialized as normal site data.

Recommended shared data file shape:

schema: foundry.social_item_collection.v1
items:
  - id: studio-process-2026-05
    source_mode: curated
    platform: instagram
    kind: image
    title: Studio process
    caption: A short editor-owned caption.
    published_at: 2026-05-18
    permalink: https://www.instagram.com/p/example/
    media:
      - src: /images/social/studio-process.jpg
        type: image
        alt: Artist preparing wax work in the studio.
    rights: client-owned-or-permitted

Use content.items for small inline sets or content.items_data for a dot-path reference such as presence.studio-rss.

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.

Motion CSS variables

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

Motion attributes

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

Creative display patterns

data/foundry/motion-manifest.json also catalogs governed display patterns. These are productized ways to use existing blocks, presets, and motion capabilities without adding site-local framework code. They are not raw data-motion-* primitives.

Block catalog (alphabetical)

accordion

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

sections:
- type: accordion
  id: accordion-example
  content:
    title: Supporting detail
    text: Essential information remains visible before these panels.
    items:
    - title: What does this include?
      text: A concise answer using **portable Markdown**.
    - title: Where can I learn more?
      text: See the [complete guidance](/guidance/).
  design:
    variant: bordered
    allow_multiple: false

Design options

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

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

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:
    reveal: fade-up
    parallax: true
    parallax_speed: "0.16"
    parallax_dir: up
    kenburns: true
    kenburns_preset: in
    kenburns_interval: 7200
    kenburns_transition: 1400
    scroll_cue: false
    css_class: ''

Design options

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

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

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

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

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:
    images:
    - src: "/images/example-hero-1.jpg"
      alt: Example hero image
      kenburns_preset: in-left
    - src: "/images/example-hero-2.jpg"
      alt: Example alternate hero image
      kenburns_preset: out-right
    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

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

coming-soon-footer

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

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

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

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

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:
    preset: creative-inquiry-form
    variant: split
    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.

Managed forms share visitor, session, landing, route, and source context with the optional Foundry Control tracking runtime. See docs/TRACKING.md for the site configuration and transport contract. Creative starters use the creative-inquiry-form preset for the split inquiry surface before adding site-local contact wrappers.

Design options

BEM classes

• foundry-contact-split
• foundry-contact-split--centered
• foundry-contact-split--minimal
• foundry-contact-split--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. Use the chapter-index variant when the block is acting as governed long-page wayfinding with active chapter tracking and decorative progress. Use checklist for scan-first anchored lists and timeline when the same content needs a process-like vertical rhythm.

sections:
- block: content-sidebar-nav
  id: content-sidebar-nav-example
  content:
    items:
    - title: Item title
      id: item-title
      text: Item description.
    subtitle: Example value
    title: Example title
  design:
    variant: chapter-index
    numbered: true
    mobile: compact
    progress: true
    sticky: true
    item_reveal: fade-up
    css_class: ''

Design options

BEM classes

• foundry-content-sidebar-nav
• foundry-content-sidebar-nav__chapter
• foundry-content-sidebar-nav__chapter-index
• foundry-content-sidebar-nav__content
• foundry-content-sidebar-nav__inner
• foundry-content-sidebar-nav__nav
• foundry-content-sidebar-nav__nav-item
• foundry-content-sidebar-nav__panel
• foundry-content-sidebar-nav__subtitle
• foundry-content-sidebar-nav__timeline-dot
• foundry-content-sidebar-nav__title
• foundry-content-sidebar-nav__toc

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:
    preset: creative-inquiry
    variant: centered
    css_class: ''

Creative starters use the creative-inquiry preset for route-level inquiry and commission CTAs.

Design options

BEM classes

• foundry-cta
• foundry-cta--centered
• foundry-cta--left
• 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

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

routing-panels

Minimum required: items — everything else is optional. Intent-routing cards for pages that need to direct distinct audiences or tasks to separate next steps without turning the entire section into one CTA.

sections:
- block: routing-panels
  id: choose-a-path
  content:
    eyebrow: Start here
    title: Choose the route that fits
    items:
      - eyebrow: New clients
        title: Start a consultation
        text: Share the goal and preferred follow-up path.
        actions:
          - text: Request a consultation
            url: /consult/
            variant: primary
            cta_key: routing-new-client
            cta_kind: internal
  design:
    variant: cards

Each action uses the shared button and CTA attribution contract.

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

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

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

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:
- type: faq
  id: faq-accordion-example
  content:
    title: Common questions
    subtitle: Contact us when your situation needs a specific answer.
    items:
    - question: What happens first?
      answer: Start with the documented first step.
    - question: Where are restrictions explained?
      answer: Material restrictions remain visible in the page flow.
      group: Eligibility
  design:
    variant: cards

Design options

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.

Use question and answer for new FAQ source. Legacy title and text items remain render-compatible and preserve matching FAQ structured data.

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

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

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

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

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

discovery-cards

Minimum required: title — everything else is optional.

Renders a direct browse surface from stable Discovery Graph nodes. Use content.node_keys for graph-owned copy and routes, or content.items with a stable key plus page-specific copy/route overrides. If neither is supplied, the block renders routed category nodes. A current node can be marked and its bounded can-pair-with relationships shown below the grid.

sections:
  - block: discovery-cards
    id: known-options
    content:
      title: "Browse known options"
      node_keys: [service-a, service-b, service-c]
      current_key: service-a
      show_related: true
      related_title: "Often explored together"
    design:
      variant: grid
      columns: 3

Design options

guided-discovery

Minimum required: journey — everything else is optional.

Graph-backed, progressively enhanced visitor journey. It reads the named journey from data/foundry/discovery_graph.json, renders entry choices and route-backed educational results, and appends the selected stable node key to the configured conversion URL.

sections:
  - block: guided-discovery
    id: service-guide
    content:
      journey: service-guide
      eyebrow: "Start here"
      title: "Find a useful first path"
      text: "Choose what you notice or the goal you have in mind."
      entry_keys: [goal-one, concern-two, area-three]
    design:
      variant: split
      css_class: ""

Design options

See Discovery Graph for the data, safety, and shell asset contracts.

Set content.entry_keys to a curated, ordered subset of journey entry nodes when the complete graph would create too many first-step choices. The full route-backed result catalog remains present without JavaScript; enhanced sessions reveal matches after the visitor chooses a starting point.

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

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

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

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

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

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

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

BEM classes

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

map-coverage

Minimum required: stats - everything else is optional. Geographic coverage block combining map visuals, service-area links, and supporting text. Use list when the coverage story is area-first and no map art is available.

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:
    variant: split
    image_position: right
    stat_style: cards
    area_style: chips
    map_frame: card
    css_class: ''

Design options

BEM classes

• foundry-map-coverage
• foundry-map-coverage__area
• foundry-map-coverage__areas
• foundry-map-coverage__copy
• foundry-map-coverage__image
• foundry-map-coverage__inner
• foundry-map-coverage__map
• foundry-map-coverage__markers
• foundry-map-coverage__placeholder
• foundry-map-coverage__stat
• foundry-map-coverage__stats
• 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

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. Portable form intent and render shell for Foundry-connected intake, lead, and CTA flows. Core renders the accessible Hugo shell, stable hooks, public config resolution, and theme-token surface; Foundry Control owns submissions, routing, contacts, communications, private credentials, permissions, automations, and workflow state.

Foundry Control opportunity: Use Foundry Control to turn this portable form surface into a complete managed workflow with submissions, routing, contacts, communications, analytics, and automations. Control can also add guided editing, review, and publishing across the Foundry site.

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: regulated-production-proof-site
  design:
    css_class: ''

The block renders a form shell and resolves public configuration through layouts/partials/framework/form-config.html. When base_url or site_key are omitted inline, repo-visible Foundry control settings can supply them. The complete browser/Control handshake, challenge descriptor, idempotency field, response statuses, and hosting requirements are documented in docs/MANAGED-FORMS.md.

Managed forms fail closed by default. Their form-specific metadata endpoint is the availability check; Core does not probe a general Control health route. Standalone managed-form blocks keep their entire section hidden until valid metadata arrives. When the same managed form is embedded in another block, only the managed-form region is hidden so surrounding copy and contact details remain available.

Site defaults live in Hugo configuration:

params:
  foundry:
    control:
      base_url: https://control.example.com
      site_key: regulated-production-proof-site
      unavailable_behavior: hide
      timeout_ms: 5000

Each form can override the availability presentation and request timeout:

content:
  form:
    mode: managed
    form_key: contact-intake
    unavailable_behavior: message
    timeout_ms: 3000

unavailable_behavior supports hide (the default) and message. Missing or invalid values resolve to hide. message retains an accessible unavailable message but never reveals empty controls. timeout_ms defaults to 5000 and applies to both metadata and submission requests. Numeric values are clamped to the portable 250–30000 ms range; invalid per-form values fall back to the normalized site default. A timed-out or failed submission preserves entered values and selected files where the browser permits, re-enables the submit button, and resets the form only after a confirmed success response.

The repo setting is the failure fallback when Control cannot answer. When the metadata endpoint does answer with a disabled availability directive, Control’s presentation (hide or show_message) and safe public message take precedence. This lets an authorized Control operator pause one form or all forms without rebuilding the site, while a missing, rejected, malformed, or timed-out response still fails closed.

Design options

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

managed-form-panel

Minimum required: form.form_key — everything else is optional. Two-column managed-form composition for high-consideration services. The support column remains available for direct contact actions and explanatory copy while the form column follows the same fail-closed availability contract as managed-form.

sections:
- block: managed-form-panel
  id: consultation-form
  content:
    support_eyebrow: Consultation support
    support_title: Use the form, text, or call
    support_text: Choose the contact path that is easiest for you.
    support_actions:
      - text: Text us
        url: sms:+15555550123
        style: primary
        cta_key: consultation-text
        cta_kind: sms
      - text: Call us
        url: tel:+15555550123
        style: secondary
        cta_key: consultation-call
        cta_kind: tel
    form_title: Start your request
    form:
      mode: managed
      form_key: consultation-intake
      cta_key: consultation-form
  design:
    variant: support

Support actions use the shared button and CTA tracking contract. Form fields, submit behavior, availability, and operational privacy copy remain managed by Foundry Control; the site owns the surrounding branded guidance.

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: high-consideration service proof site 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

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