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 same block entry may add top-level fields for supported source values that must remain discoverable but are not routine editor controls. This is the canonical supplemental field contract for primitive-first, guided-advanced, derived, operational, invariant, and compatibility values; it is not a second editor projection. Each entry declares its source path, classification, semantic type, widget or inspection representation, rendering behavior, output surfaces, fallback when applicable, preview mapping, and alias relationship. Core validation requires complete supplemental entries. A field remains in the editor projection only when the editor-expansion contract says it is safe for ordinary structured editing.

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; the Structured Explanation wave adds features and timeline; the Openings & Route Choice wave adds post-hero, coming-soon-hero, media-break, founder-profile, and discovery-cards. See the Portable Authoring Contract for the complete active surface and DC03-S12 Openings And Route Choice Controls for preferred article metadata, launch form, visual pause, profile, route, and Hugo source guidance.

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. Use Audio Player when one recording should be played in the page with clear context, optional download, and a transcript. Use a plain resource link when playback adds no value; use Media Sequence or Video Embed when synchronized visuals are part of the evidence.

The normal path starts with an intent preset:

sections:
- block: audio-player
  id: episode-audio
  design:
    preset: episode-feature
  content:
    show: Field Notes
    title: How the work took shape
    url: /audio/field-notes-01.mp3
    transcript: The complete, corrected transcript goes here.

focused-listen is quiet supporting audio, episode-feature gives a primary recording artwork and context, and audio-resource makes listening and download equally visible. Native browser controls are the no-JavaScript floor; the fingerprinted Core controller progressively adds the custom timeline, volume, speed, and status behavior. Authors do not write ARIA, scripts, layout classes, or breakpoint-specific copies.

Design options

Intent presets: focused-listen, episode-feature, audio-resource.

BEM classes

• foundry-audio-player
• foundry-audio-player__assistive
• foundry-audio-player__content
• foundry-audio-player__controls
• foundry-audio-player__cover
• foundry-audio-player__cover-image
• foundry-audio-player__cover-letter
• foundry-audio-player__description
• foundry-audio-player__download
• foundry-audio-player__download-icon
• foundry-audio-player__empty
• foundry-audio-player__inner
• foundry-audio-player__icon
• foundry-audio-player__icon-svg
• foundry-audio-player__layout
• foundry-audio-player__meta
• foundry-audio-player__native
• 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__speed-label
• foundry-audio-player__speed-select
• foundry-audio-player__time
• foundry-audio-player__timeline
• foundry-audio-player__title
• foundry-audio-player__toggle
• foundry-audio-player__transcript
• foundry-audio-player__transcript-body
• foundry-audio-player__transcript-summary
• foundry-audio-player__volume
• foundry-audio-player__volume-icon
• foundry-audio-player__volume-range
• foundry-audio-player__volume-svg

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:
    title: "What changes after the decision work"
    subtitle: "Use paired states for a real transformation, not decorative contrast."
    before_label: "Starting point"
    after_label: "New direction"
    before:
      title: "Unclear path"
      text: "The visitor sees claims without decision context."
      items: ["Proof arrives late", "Next steps feel premature"]
    after:
      title: "Decision-ready path"
      text: "Context, proof, and action follow a deliberate sequence."
      items: ["Evidence is qualified", "The next step matches readiness"]
  design:
    variant: cards
    treatment: bordered

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. Use Callout for one concise piece of context, guidance, risk, or confirmation that belongs in the page’s reading flow. The selected type always renders a visible meaning label as well as a matching icon and color, so meaning never depends on color alone. Static warnings intentionally remain ordinary page content rather than live alert regions.

sections:
- block: callout
  id: consultation-context
  content:
    label: Before you book
    title: Bring the products you currently use
    text: We will review active ingredients together so your plan does not duplicate or conflict with your current routine.
    action:
      text: Prepare for the visit
      url: /consultation-guide/
  design:
    preset: useful-context

Intent presets: useful-context for ordinary supporting information, page-alert for a genuine page-wide warning, and editorial-aside for a quiet reading note. editorial-callout remains as a compatible subtle-note preset.

Content fields

Design options

Use Warning and Danger only for real risk. Use a normal heading, Rich Text, or CTA when the goal is merely to make marketing copy louder. Theme Families and Customer Brand Systems may change the public Callout variables, while Core retains the semantic anatomy, responsive behavior, and visible meaning.

BEM classes

• foundry-callout
• foundry-callout__action
• foundry-callout__action-icon
• foundry-callout__action-link
• foundry-callout__box
• foundry-callout__content
• foundry-callout__icon
• foundry-callout__icon-symbol
• foundry-callout__inner
• foundry-callout__meaning
• 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:
    title: "Representative outcomes"
    subtitle: "Explain the constraint, approach, and supported evidence."
    cases:
      - client_type: "Local service"
        title: "A clearer consultation path"
        problem: "The original page mixed claims and conversion pressure."
        solution: "The new sequence qualified proof before asking for action."
        results: ["Normal Hugo source", "No copied renderer"]
  design:
    variant: editorial

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__panel
• foundry-coming-soon-hero__form-panel
• foundry-coming-soon-hero__form
• foundry-coming-soon-hero__inner
• foundry-coming-soon-hero__text
• foundry-coming-soon-hero__title

coming-soon-trust

Preferred Section source: type: trust-marks with style: launch.

Coming Soon Trust is the launch-reassurance control. It tells a visitor what is ready, what the organization actually promises, and which named relationships support the launch. It must not manufacture credibility from decorative badges. Use Logos for a neutral organization collection, Logo Trust for a verified relationship surface, Trust Badges for mixed ongoing assurances, and the Certifications Style for issued credentials.

At least one accurate fact, assurance, or permissioned logo relationship should be present. eyebrow, title, and introduction establish context. Every fact or assurance may keep a qualification and public source next to the claim. Every logo keeps a visible name and may state its exact relationship; the mark never establishes partnership or endorsement by itself.

sections:
- type: trust-marks
  style: launch
  id: launch-readiness
  design:
    preset: launch-readiness
  content:
    eyebrow: Public launch record
    title: What is ready before the doors open
    introduction: Dates, scope, and information handling are stated plainly.
    facts:
    - value: Sep 2026
      label: Public preview opens
      details: A planned date, qualified until the schedule is final.
      source_url: /launch-details/
    assurances:
    - label: Waitlist email is used only for launch updates
      details: Verify this against the real form, provider, and privacy policy.
      source_url: /privacy/
    logos:
    - name: Example Studio
      relationship: Launch collaborator
      image: /media/example-studio.svg
      image_alt: ''
      url: /launch-details/

Design options

The three presets are different content structures, not color swaps: launch-readiness balances a public readiness ledger with qualified assurances; compact-status-rail keeps a small fact set concise; and privacy-first-note turns one information boundary into an editorial statement. Legacy block: coming-soon-trust, stats, badges, subtitle, and variant: grid source remains compatible, but new sites should use the typed vocabulary above.

BEM classes

• foundry-coming-soon-trust
• foundry-coming-soon-trust__inner
• foundry-coming-soon-trust__header
• foundry-coming-soon-trust__eyebrow
• foundry-coming-soon-trust__title
• foundry-coming-soon-trust__introduction
• foundry-coming-soon-trust__evidence
• foundry-coming-soon-trust__facts
• foundry-coming-soon-trust__fact
• foundry-coming-soon-trust__fact-label
• foundry-coming-soon-trust__fact-value
• foundry-coming-soon-trust__fact-details
• foundry-coming-soon-trust__fact-source
• foundry-coming-soon-trust__assurances
• foundry-coming-soon-trust__assurance
• foundry-coming-soon-trust__assurance-label
• foundry-coming-soon-trust__assurance-details
• foundry-coming-soon-trust__assurance-source
• foundry-coming-soon-trust__logos
• foundry-coming-soon-trust__logo
• foundry-coming-soon-trust__logo-mark
• foundry-coming-soon-trust__logo-image
• foundry-coming-soon-trust__logo-name
• foundry-coming-soon-trust__logo-relationship
• foundry-coming-soon-trust__logo-link

comparison-table

Minimum required: rows — everything else is optional. General comparison control for measuring two approaches against the same visitor-centered decision points. Use Pricing Comparison when the columns are priced plans with shared criteria.

sections:
- block: comparison-table
  id: comparison-table-example
  content:
    title: "Compare the decision"
    caption: "Comparison of two approaches"
    headers:
      - label: "Decision point"
      - label: "Evidence-led"
      - label: "Shortcut"
    rows:
      - feature: "Proof"
        ours: "State source, scope, and limitation near the claim."
        typical: "Move context into fine print."
  design:
    variant: editorial

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, source-ordered list. Use it when visitors genuinely have more than one bounded next step; use cta when one action should dominate.

sections:
- block: cta-button-list
  id: cta-button-list-example
  design:
    preset: inline-actions
  content:
    title: "Choose how to begin"
    subtitle: "Keep each destination distinct and explain the decision boundary in portable Markdown."
    buttons:
      - text: "Review the outline"
        url: "/outline/"
        variant: primary
      - text: "Ask a question"
        url: "/contact/"
        variant: secondary

Design options

The named presets are inline-actions, ordered-handoff, and compact-register. Each action requires a label and a real destination. Use primary only when one action should lead attention; otherwise leave actions secondary or choose a quiet ghost alternative. Foundry keeps the list semantic and source-ordered without JavaScript, and stacks actions on narrow screens. Tracking fields remain optional metadata passed through the shared button component.

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. Media-supported conversion Style for next steps that benefit from visual context. Prefer a plain CTA when the image does not help the visitor decide. The normal authoring path is the typed cta.media Section Style; the renderer name remains supported for compatibility.

sections:
- type: cta
  style: media
  id: guided-handoffs
  content:
    eyebrow: Next steps
    title: Choose the right working session
    items:
    - title: Map the story
      text: Start with the visitor question, evidence, and next action.
      image: /images/story-map.jpg
      image_alt: Story map and content notes on a worktable
      features:
      - Name the visitor job
      - Preserve portable source
      action:
        text: Plan the page
        url: /contact/
        variant: primary
        cta_key: story-planning
  design:
    preset: guided-handoffs

Recommended presets are guided-handoffs for a longer alternating sequence, editorial-invitations for an open ruled composition, and compact-next-steps for a small set of peer choices. Keep items in reading order; desktop media placement may change, but mobile source and focus order do not.

Design options

BEM classes

• foundry-cta-image-paragraph
• foundry-cta-image-paragraph__action
• foundry-cta-image-paragraph__collection
• foundry-cta-image-paragraph__content
• foundry-cta-image-paragraph__feature
• foundry-cta-image-paragraph__header
• foundry-cta-image-paragraph__inner
• foundry-cta-image-paragraph__item
• 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, interactive models, tools, and third-party widgets. Core owns deferred-source activation and loader completion; a consumer does not need site-local JavaScript for those modes. Set require_activation when the provider must not be contacted until the visitor chooses to load it. The fallback link remains available when JavaScript is disabled.

sections:
- block: embed
  id: embed-example
  content:
    fallback_text: Open source link
    fallback_url: https://example.com/fallback
    activation_title: View the interactive model
    activation_text: Loading this model contacts the external provider.
    activation_label: Load interactive model
    text: Example supporting text.
    title: Example title
    url: https://example.com
  design:
    variant: card
    aspect: '16:9'
    loading: lazy
    show_loader: true
    require_activation: true
    css_class: ''

Design options

BEM classes

• foundry-embed
• foundry-embed__empty
• foundry-embed__activate
• foundry-embed__fallback
• foundry-embed__figure
• foundry-embed__frame
• foundry-embed__frame-wrap
• foundry-embed__inner
• foundry-embed__loader
• foundry-embed__loader-panel
• 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. Use FAQ Follow-up for the final one to three questions that may prevent a visitor from taking one accurate next step. Use FAQ Accordion for the complete question library, and use a generic CTA when no answer-driven transition is needed. The split and note presentations use native disclosures; guided keeps every selected answer visible in numbered source order. No JavaScript is required.

Recommended presets: questions-to-next-step, guided-decision-close, and quiet-contact-note.

Write questions in the visitor’s language. Keep each answer concise and qualified, and keep timing, privacy, eligibility, availability, policy, and process notes accurate. Legacy item title and text fields remain compatible, but new source should use question and answer.

sections:
- type: cta
  style: faq-follow-up
  id: final-project-questions
  content:
    eyebrow: Before we begin
    title: The questions that shape a useful first conversation
    subtitle: These are the final practical details, not a replacement for the complete FAQ.
    items:
    - question: Do I need a finished brief?
      answer: No. Bring the decision, audience, and constraints you already know; the first conversation identifies what still needs evidence.
    - question: What happens after the conversation?
      answer: You receive the documented next step that fits the actual scope. No project begins without a separate reviewed agreement.
    cta_title: Start with the real decision
    cta_text: Share the context that would make a first review useful.
    cta_action:
      text: Request a project review
      url: /contact/
      cta_key: project-review
      cta_kind: contact
    cta_secondary_action:
      text: Read the complete FAQ
      url: /faq/
    cta_note: Initial messages are reviewed privately; response timing should match the site's current published policy.
  design:
    preset: questions-to-next-step

Design options

BEM classes

• foundry-faq-cta
• foundry-faq-cta__answer
• foundry-faq-cta__actions
• foundry-faq-cta__body
• foundry-faq-cta__eyebrow
• foundry-faq-cta__guided-item
• foundry-faq-cta__handoff
• foundry-faq-cta__handoff-mark
• foundry-faq-cta__handoff-text
• foundry-faq-cta__handoff-title
• foundry-faq-cta__header
• foundry-faq-cta__indicator
• foundry-faq-cta__inner
• foundry-faq-cta__intro
• foundry-faq-cta__item
• foundry-faq-cta__note
• foundry-faq-cta__number
• foundry-faq-cta__question
• foundry-faq-cta__questions
• foundry-faq-cta__questions--guided
• foundry-faq-cta__summary
• 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.

Use Features for parallel benefits, capabilities, or differentiators. Use Timeline when chronology matters and Process when visitors must understand a sequence of actions or expectations. The routine editor uses canonical name and description fields and preserves compatibility aliases and advanced keys.

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--columns-{2,3,4}
• 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. Introduce one founder, principal, artist, practitioner, or other important person with enough public context to support trust. Use team-grid for several people and author-bio for compact article attribution.

The shortest good source is an approved public name, accurate role, concise Markdown biography, and approved portrait. Add factual highlights only when they help the visitor understand experience, responsibility, or approach; do not invent credentials, awards, affiliations, or outcome claims.

sections:
- block: founder-profile
  id: founder-story
  design:
    preset: founder-story
  content:
    title: "The person behind the work"
    name: "Jordan Vale"
    role: "Founder and creative director"
    biography: |
      Jordan built the studio around a simple belief: clear decisions and
      careful craft should reinforce each other.
    highlights:
      - text: "Leads every discovery engagement"
        context: "From first brief through final review"
      - text: "Fifteen years in independent practice"
    image: "/images/jordan-vale.jpg"
    image_alt: "Jordan Vale working beside material samples in the studio"
    primary_action:
      text: "Read the studio approach"
      url: "/approach/"

subtitle and paragraphs remain supported for older sites, but new source should use one biography Markdown field. Responsive-image source sets, intrinsic dimensions, custom sizes, and direct email/phone links remain advanced source fields; the normal human and AI path does not require them.

Intent presets

• founder-story — balanced portrait and narrative for an About page.
• artist-profile — expressive image-right manifesto with open typography.
• practitioner-profile — compact, factual authority with clear highlights.

Design options

Theme Families and Customer Brand Systems may art-direct public --foundry-founder-profile-* variables for measure, spacing, portrait shape, media position, typography, accent, rules, and factual-highlight surfaces. Core continues to own heading order, portrait semantics, biography measure, contact focus, and responsive reading order.

BEM classes

• foundry-founder-profile
• foundry-founder-profile__actions
• foundry-founder-profile__contact
• foundry-founder-profile__contacts
• foundry-founder-profile__content
• foundry-founder-profile__eyebrow
• foundry-founder-profile__highlight
• foundry-founder-profile__highlights
• foundry-founder-profile__identity
• foundry-founder-profile__image
• foundry-founder-profile__inner
• foundry-founder-profile__intro
• foundry-founder-profile__layout
• foundry-founder-profile__media
• foundry-founder-profile__name
• foundry-founder-profile__picture
• foundry-founder-profile__role
• foundry-founder-profile__text
• foundry-founder-profile__title

gallery

Minimum required: images — everything else is optional. Ordered, accessible image collection with optional captions, credits, related routes, filter categories, crop focus, and progressively enhanced lightbox navigation. Use Masonry for irregular editorial rhythm, Slideshow for sequential presentation, Property Tour for place-aware groups, or Media Sequence for a mixed-media narrative.

sections:
- block: gallery
  id: gallery-example
  design:
    preset: editorial-pairs
  content:
    title: Selected places
    text: A short introduction that tells visitors what to notice.
    images:
    - id: lake-arrival
      src: "/images/gallery-1.jpg"
      alt: Lake house beyond a private cedar edge
      caption: Arrival establishes the relationship between house and water.
      credit: Photograph by Example Studio
      link: /places/lake-house/
      category: exteriors
      position: center

Start with editorial-pairs, visual-catalog, or natural-archive. The legacy portfolio-grid preset remains compatible. Each image is a normal link to the full asset without JavaScript; the fingerprinted Core controller enhances that link into the dialog only when the required anatomy is available.

Design options

BEM classes

• foundry-gallery
• foundry-gallery__close
• foundry-gallery__dialog
• foundry-gallery__dialog-actions
• foundry-gallery__dialog-caption
• foundry-gallery__dialog-credit
• foundry-gallery__dialog-footer
• foundry-gallery__dialog-image
• foundry-gallery__dialog-inner
• foundry-gallery__dialog-link
• foundry-gallery__dialog-nav
• foundry-gallery__dialog-position
• foundry-gallery__dialog-stage
• foundry-gallery__empty
• foundry-gallery__grid
• foundry-gallery__header
• foundry-gallery__image
• foundry-gallery__inner
• foundry-gallery__item
• foundry-gallery__media
• 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--{centered,left}
• foundry-hero--media
• foundry-hero__actions
• foundry-hero__inner
• foundry-hero__text
• foundry-hero__title

icon-grid

Minimum required: items — everything else is optional. Use Icon Grid to explain a small set of capabilities, principles, or service paths that benefit from quick visual anchors. Use Features for denser benefit copy and Discovery Cards when every item is primarily a destination.

Recommended presets: editorial-capabilities for an open two-column list, service-cards for scannable destinations, and expressive-symbols for a centered visual statement. icon-highlight-row remains compatible.

sections:
- block: icon-grid
  id: icon-grid-example
  content:
    items:
    - icon: sparkles
      title: Thoughtful direction
      text: A short explanation of the useful outcome.
      url: /approach/
      link_label: See our approach
    text: Choose the few ideas a visitor should understand first.
    title: What makes the work different
  design:
    preset: service-cards

Design options

BEM classes

• foundry-icon-grid
• foundry-icon-grid__content
• foundry-icon-grid__grid
• foundry-icon-grid__header
• foundry-icon-grid__icon
• foundry-icon-grid__icon-svg
• foundry-icon-grid__inner
• foundry-icon-grid__item
• foundry-icon-grid__item-text
• foundry-icon-grid__item-title
• foundry-icon-grid__link
• 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-image editorial Style with bounded emphasis, crop, focal position, caption, and optional lightbox enhancement. Use Gallery or Slideshow when the visitor needs to browse several images. The normal authoring path is typed media-story.image-feature; the renderer name remains supported for compatibility.

sections:
- type: media-story
  style: image-feature
  id: evidence-figure
  content:
    src: /images/process-map.svg
    alt: Process map showing discovery, evidence review, and decision handoff
    caption: The complete process remains visible without JavaScript.
    credit: Internal process study
  design:
    preset: editorial-figure

Recommended presets are editorial-figure for uncropped evidence, cinematic-wide for immersive emphasis, full-bleed-statement for an edge-to-edge beat, and supporting-figure for a bounded side-aligned image. The optional lightbox is progressive enhancement; the base image and caption remain ordinary visible HTML.

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__image
• foundry-image-feature__media
• foundry-image-feature__opener
• foundry-image-feature__zoom

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 permissioned logos with supporting credibility chips. Use only marks the site owns or has explicit permission to publish; the Core compatibility fixture uses clearly fictional demonstration artwork.

sections:
- block: logo-trust
  id: logo-trust-example
  content:
    eyebrow: Permissioned partners
    title: Organizations we are approved to name
    subtitle: Every mark is verified before publication.
    logos:
    - name: Partner Name
      image: /media/partner-name.svg
    badges:
    - Permission verified
    - Meaningful alternative names
  design:
    preset: permissioned-partners

Design options

Use logo-trust when a small verified set of organizations or affiliations helps visitors interpret trust. Use logos for a larger neutral logo wall and certification-badges when credentials, issuing bodies, or destinations are the primary meaning. Real sites must verify the relationship, publication rights, organization name, and alternative text before adding a mark.

BEM classes

• foundry-logo-trust
• foundry-logo-trust--grid
• foundry-logo-trust--strip
• foundry-logo-trust--band
• foundry-logo-trust__badges
• foundry-logo-trust__badge
• foundry-logo-trust__empty
• foundry-logo-trust__eyebrow
• foundry-logo-trust__grid
• foundry-logo-trust__header
• 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. An accurately named collection of organizations, publications, tools, sponsors, collaborators, or brands. This Block does not turn proximity into trust proof. Use logo-trust for verified organization relationships and certification-badges for formally issued credentials.

sections:
- block: logos
  id: logos-example
  design:
    preset: brand-wall
  content:
    title: Selected collaborations
    introduction: Every relationship is named plainly and every mark is approved for display.
    logos:
    - name: Northline Workshop
      relationship: Campaign collaborator
      description: A limited collaboration for the 2026 launch campaign.
      image: /media/northline-workshop.svg
      image_alt: ""
      url: /work/northline/

Keep name visible even when an image exists. Use relationship when visitors could otherwise infer a customer, sponsor, partner, endorsement, or publisher status that the source does not actually establish. Leave image_alt empty when the adjacent visible name communicates the same information; describe only unique visual meaning. Verify names, destinations, and display rights before publishing a real mark.

Start with brand-wall, relationship-index, or compact-mentions. moving-ticker is an advanced progressive enhancement: the complete static list remains readable when JavaScript is unavailable, animation is disabled, or reduced motion is requested. trust-marquee and authority-grid remain compatible legacy preset names; they do not change this Block into verified trust evidence.

Design options

BEM classes

• foundry-logos
• foundry-logos__header
• foundry-logos__inner
• foundry-logos__introduction
• foundry-logos__collection
• foundry-logos__motion-options
• foundry-logos__viewport
• foundry-logos__items
• foundry-logos__item
• foundry-logos__item-link
• foundry-logos__mark
• foundry-logos__image
• foundry-logos__relationship
• foundry-logos__name
• foundry-logos__description
• 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%
      detail: "Current reporting year; 318 registered participants."
    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: ''