Blocks and families

LikeStyle Foundry renders page sections from front matter using a shared block registry.

Terminology

Foundry uses a layered composition model:

• block
  • the technical framework primitive
• section
  • a placed page instance of a block or composition
• composition
  • a reusable named structure, currently backed by the bricks compatibility model
• blueprint
  • the public/editor term for a governed page creation path backed by a page type contract

In public/editor language, users build pages from sections and may reuse compositions. In technical framework language, blocks remain the stable render primitives.

For long-term family, variant, and preset governance, see FOUNDRY-BLOCK-ARCHITECTURE.md. For the first concrete family-level example, see FOUNDRY-HERO-FAMILY-SPEC.md. For cross-layer ownership, see FOUNDRY-FEATURE-PLACEMENT-MATRIX.md.

Section Contract

Each page uses a sections array in front matter. Every section supports:

• block: Required block key (must exist in data/foundry/block-registry.yaml).
• id: Optional anchor ID.
• content: Required data payload for the block.
• design: Optional display/layout hints.
• data: Optional data binding to pull reusable content from site.Data.

Example section shell:

sections:
  - block: hero
    id: top
    content:
      title: "Headline"
      text: "Support text"
    design:
      variant: centered

In most pages, sections are the primary assembly format. When reusable named structures are needed, compositions may be used through the current bricks compatibility layer.

Canonical Block Standard

Foundry blocks now follow a canonical template and naming convention.

• Canonical template source: /layouts/partials/blocks/_template.html in likestyle-foundry-core
• BEM naming convention:
  • Block root: foundry-[block-name]
  • Element: foundry-[block-name]__[element]
  • Modifier: foundry-[block-name]--[modifier]

Example BEM structure:

<section class="foundry-hero ...">
  <div class="foundry-hero__inner ...">
    <h1 class="foundry-hero__title ...">...</h1>
    <p class="foundry-hero__text ...">...</p>
    <div class="foundry-hero__actions ...">...</div>
  </div>
</section>

For block design options and accepted variants, use the registry:

• /data/foundry/block-options.yaml (in likestyle-foundry-core)
• Live demo illustration: /blocks/#showcase-canonical-standard (in likestyle-foundry-demo)

This file is the source of truth for design fields per block and is intended for future schema/tooling validation.

Blocks should remain the smallest stable shared framework unit. Reusable multi-part structures belong in the composition layer, not in increasingly overloaded individual blocks.

Data-Driven Sections (Reusable Content)

Foundry supports merging data files into sections.

• String path: data: "foundry.blocks.home-hero"
• Object path: data: { source: "foundry", path: "blocks.home-hero" }

When both section values and data values exist, explicit section values win.

This is complementary to compositions:

• data bindings are for reusable content payloads
• compositions are for reusable named structures

Registry Overview

Current registered blocks:

• hero, trust-badges, features, media-text
• page-list, quote, tabs, gallery, accordion, social-share
• icon-grid, steps, stats-band, video-hero, before-after
• content-sidebar-nav, timeline, map-coverage, contact-split, cta
• testimonials, testimonials-carousel, logos, onboarding-timeline, stats-grid
• faq-accordion, faq-cta, prose-panel, illustration-panel, case-studies
• certification-badges, resource-downloads, lead-magnet, topic-chip-nav, team-grid
• founder-profile, cta-image-paragraph, comparison-table, cta-button-list
• pricing-tiers, pricing-comparison, logo-trust
• coming-soon-hero, coming-soon-cta, coming-soon-trust, coming-soon-footer

New Blocks

page-list

Description: Lists content from a Hugo section (blog, articles, etc.) in cards, list, or compact view.

content contract

• title (string, optional)
• text (string, optional, markdown)
• section (string, required) — Hugo section path like blog
• limit (number, optional, default 6)
• sort (string, optional) — date, title, weight

design options

• view (string, optional, default cards) — cards, list, compact
• columns (string, optional, default 3) — 2, 3 (used for cards grid)
• show_date (bool, optional, default true)
• show_summary (bool, optional, default true)
• show_image (bool, optional, default true)
• css_class (string, optional)

example front matter

- block: page-list
  id: latest-articles
  content:
    title: "Latest Articles"
    text: "Recent updates from the team."
    section: "blog"
    limit: 6
    sort: "date"
  design:
    view: "cards"
    columns: "3"
    show_date: true
    show_summary: true
    show_image: true

quote

Description: Standalone quote/pull-quote with optional author metadata and avatar.

content contract

• quote (string, required, markdown)
• author (string, optional)
• role (string, optional)
• image (string, optional)

design options

• variant (string, optional, default centered) — centered, left, large
• css_class (string, optional)

example front matter

- block: quote
  id: founder-quote
  content:
    quote: "We optimize reliability first, then scale."
    author: "Alex Rivera"
    role: "Founder, Northline Systems"
    image: "/images/team/alex.jpg"
  design:
    variant: "large"

tabs

Description: Accessible tabbed content block for grouped content and side-by-side comparisons.

content contract

• title (string, optional)
• tabs (array, required)
• tabs[].label (string, recommended)
• tabs[].icon (string, optional)
• tabs[].text (string, markdown)

design options

• variant (string, optional, default underline) — underline, pills, bordered
• css_class (string, optional)

example front matter

- block: tabs
  id: delivery-model-tabs
  content:
    title: "Delivery Options"
    tabs:
      - label: "Starter"
        icon: "rocket-launch"
        text: "Lean setup with core governance controls."
      - label: "Growth"
        icon: "chart-bar"
        text: "Expanded automation and reporting layers."
      - label: "Enterprise"
        icon: "building-office"
        text: "Dedicated workflows, policy controls, and SLA support."
  design:
    variant: "pills"

gallery

Description: Responsive image gallery with optional captions and dialog-based lightbox.

content contract

• title (string, optional)
• text (string, optional, markdown)
• images (array, required)
• images[].src (string, required)
• images[].alt (string, required)
• images[].caption (string, optional, markdown)

design options

• columns (string, optional, default 3) — 2, 3, 4
• gap (string, optional, default md) — sm, md, lg
• aspect (string, optional, default square) — square, landscape, auto
• css_class (string, optional)

example front matter

- block: gallery
  id: work-gallery
  content:
    title: "Recent Delivery Work"
    text: "Representative snapshots from client programs."
    images:
      - src: "/images/gallery/session-01.jpg"
        alt: "Workshop whiteboard"
        caption: "Architecture sprint workshop"
      - src: "/images/gallery/session-02.jpg"
        alt: "Dashboard screenshot"
        caption: "Governance dashboard rollout"
      - src: "/images/gallery/session-03.jpg"
        alt: "Team working session"
  design:
    columns: "3"
    gap: "md"
    aspect: "landscape"

accordion

Description: General-purpose accordion for grouped content beyond FAQs.

content contract

• title (string, optional)
• text (string, optional, markdown)
• items (array, required)
• items[].title (string, required)
• items[].text (string, required, markdown)
• items[].icon (string, optional)

design options

• allow_multiple (bool, optional, default false)
• variant (string, optional, default bordered) — bordered, minimal, cards
• css_class (string, optional)

example front matter

- block: accordion
  id: process-accordion
  content:
    title: "Implementation Details"
    text: "Open each section to view delivery details."
    items:
      - title: "Discovery"
        icon: "magnifying-glass"
        text: "We map current process risk and ownership gaps."
      - title: "Implementation"
        icon: "wrench-screwdriver"
        text: "We apply controls and workflow automation incrementally."
      - title: "Operate"
        icon: "rocket-launch"
        text: "We monitor performance and refine the operating model."
  design:
    allow_multiple: false
    variant: "cards"

social-share

Description: Page-level social sharing links with optional clipboard copy behavior.

content contract

• title (string, optional)
• platforms (array, required)
• Supported platform values: twitter, linkedin, facebook, email, copy-link

design options

• variant (string, optional, default buttons) — buttons, icons, minimal
• css_class (string, optional)

example front matter

- block: social-share
  id: share-this-page
  content:
    title: "Share This Guide"
    platforms:
      - twitter
      - linkedin
      - email
      - copy-link
  design:
    variant: "buttons"

Existing Core Block Contracts (Quick Reference)

This section keeps a compact contract list for the rest of the registry.

hero

content

• title (string)
• text (string)
• primary_action (object: text, url, optional icon)
• secondary_action (object: text, url, optional icon)

design

• variant: centered | left
• css_class: optional

features

content

• title (string)
• text (string)
• items (array: name, description, optional icon)

design

• columns: 2 | 3 | 4
• variant: cards | plain
• css_class: optional

media-text

content

• title (string)
• text (string)
• eyebrow (string, optional)
• image (string)
• image_alt (string)
• items (array of strings, optional)
• primary_action (object)
• secondary_action (object)

design

• media_position: left | right
• media_ratio: landscape | square | portrait | wide
• css_class: optional

icon-grid

content

• title (string)
• text (string)
• items (array: title, text, optional icon)

design

• columns: 2 | 3 | 4
• variant: plain | cards
• css_class: optional

steps

content

• title (string)
• subtitle (string)
• steps (array: title, text, optional icon)

design

• columns: 2 | 3 | 4
• variant: cards | plain
• css_class: optional

stats-band

content

• title (string)
• subtitle (string)
• stats (array: value, label)

design

• variant: dark | light | brand
• css_class: optional

video-hero

content

• title (string)
• text (string)
• eyebrow (string, optional)
• bullets (array, optional)
• video_url (string, optional)
• video_poster (string, optional)
• image (string, fallback)
• image_alt (string)
• primary_action (object)
• secondary_action (object)

before-after

content

• title (string)
• subtitle (string)
• before (object: title, text, items[])
• after (object: title, text, items[])

content-sidebar-nav

content

• title (string)
• subtitle (string)
• items (array: id, title, text, optional bullets)

timeline

content

• title (string)
• subtitle (string)
• events (array: title, text, optional date, badge)

map-coverage

content

• title (string)
• subtitle (string)
• image (string)
• image_alt (string)
• stats (array)
• markers (array, optional)
• note (string, optional)

contact-split

content

• title (string)
• subtitle (string)
• phone (string, optional)
• email (string, optional)
• address (string, optional)
• hours (string, optional)
• form_title (string)
• form_text (string, optional)
• form_action (string)
• form_method (string, optional)
• fields (array)
• submit_text (string)
• privacy_note (string, optional)

cta

content

• title (string)
• text (string)
• primary_action (object)
• secondary_action (object)

design

• variant: centered | left
• css_class: optional

testimonials

content

• title (string)
• subtitle (string)
• testimonials (array: quote, author)

testimonials-carousel

content

• title (string)
• subtitle (string)
• testimonials (array: quote, author, optional role, rating)

logos

content

• title (string)
• subtitle (string)
• logos (array: name, image, optional description)

onboarding-timeline

content

• title (string)
• subtitle (string)
• steps (array: name, description, optional icon)

stats-grid

content

• title (string)
• subtitle (string)
• stats (array: value, label, optional icon)

faq-accordion

content

• title (string)
• subtitle (string)
• items (array: question, answer)

faq-cta

content

• title (string)
• subtitle (string)
• items (array: question, answer)
• cta_title (string)
• cta_text (string)
• cta_action (object)
• cta_secondary_action (object)

prose-panel

content

• title (string)
• text (markdown)

illustration-panel

content

• image (string)
• image_alt (string)
• caption (string)
• panel_width: standard | wide | compact

case-studies

content

• title (string)
• cases (array: client_type, title, problem, solution, results[])

certification-badges

content

• title (string)
• subtitle (string)
• badges (array: name, optional description, optional icon)

resource-downloads

content

• title (string)
• subtitle (string)
• form_title (string)
• form_action (string)
• submit_text (string)
• privacy_note (string)
• resources (array: title, description, thumbnail, thumbnail_alt, file)

lead-magnet

content

• title (string)
• subtitle (string)
• offer_title (string)
• offer_text (string)
• download_url (string, optional)
• form_title (string)
• form_text (string, optional)
• form_action (string)
• form_method (string, optional)
• fields (array)
• submit_text (string)
• privacy_note (string)

topic-chip-nav

content

• title (string)
• items (array: text, url, optional icon)

team-grid

content

• title (string)
• subtitle (string)
• members (array: name, role, bio, image, image_alt, optional links)

founder-profile

content

• title (string)
• name (string)
• role (string)
• subtitle (string)
• image (string)
• image_alt (string)
• image_webp_srcset, image_srcset, image_sizes, image_width, image_height
• paragraphs (array)
• highlights (array)
• contact_email_href, contact_email_label
• contact_phone_href, contact_phone_label

cta-image-paragraph

content

• title (string)
• paragraph (string)
• image (string)
• image_alt (string)
• action (object: text, url, optional icon)

comparison-table

content

• title (string)
• columns (array)
• rows (array)

cta-button-list

content

• title (string)
• subtitle (string)
• buttons (array: text, url, optional icon)

pricing-tiers

content

• title (string)
• tiers (array: name, price, optional alt_price, includes, best_for)

pricing-comparison

content

• title (string)
• subtitle (string)
• plans (array: name, price, description, features, optional highlight, highlight_label, action)

logo-trust

content

• title (string)
• subtitle (string)
• logos (array: name, image)
• badges (array of strings)

coming-soon-* blocks

• coming-soon-hero
• coming-soon-cta
• coming-soon-trust
• coming-soon-footer

See the site implementation examples for full payload shape (content/coming-soon.md in consuming sites).