Foundry architecture

LikeStyle Foundry is split into composable modules so block logic, visual design, and site content evolve independently.

Platform stance

Foundry is the open framework layer.

That means:

• sites may use Foundry without LikeStyle Control
• sites may use Foundry without LikeStyle hosting
• shared framework contracts should remain useful to external tools too
• Control-specific workflow behavior should layer on top of the framework rather than becoming a hidden requirement

Repositories

• likestyle-foundry-core: Block renderer, block partials, shared class tokens, schemas.
• likestyle-foundry-theme-shield: Default visual system (theme CSS, header/footer, base layout).
• likestyle-foundry-starter: Runnable starter site pinned to known module versions.
• likestyle-foundry-distribution: Release bundles, compatibility manifests, verification tooling.
• likestyle-foundry-docs: Documentation, contracts, and migration guidance.

Adoption modes

Foundry should support three valid adoption modes:

1. Standalone Foundry

• Hugo site uses Foundry starter/core/theme only
• any editor workflow
• any compatible static-site hosting

2. Foundry with external integrations

• site uses Foundry plus third-party integrations or custom tooling
• shared manifests and hooks remain available to those tools

3. Foundry with LikeStyle Control

• site opts into LikeStyle Control workflows
• gets structured editing, preview, review, publish orchestration, and other managed features

These are adoption options, not framework tiers.

Compatibility Layer

Foundry compatibility is managed as a stack, not as a collection of unrelated repo tags.

likestyle-foundry-distribution owns:

• stable and preview bundle manifests
• the expected compatible repo tag set
• verification commands that must pass before a shared release is considered complete
• release maps that capture program-level version decisions and deferrals
• site consumption guidance for pinned or vendored installs

This lets the framework continue evolving while production sites stay pinned to known-good bundles.

Rendering Pipeline

1. A page declares sections in front matter.
2. render-sections.html reads each section and resolves block via data/foundry/block-registry.yaml.
3. The matching block partial receives:
   • .page (current page context)
   • .section (block payload: content, design, id, optional data)
4. If data is specified, Foundry merges referenced site.Data payload before render.

This gives a strict content contract with predictable rendering behavior.

Canonical Block Artifacts

Foundry now keeps block implementation standards in two core artifacts:

• layouts/partials/blocks/_template.html
  • Canonical implementation template for all new blocks
  • Defines standard context extraction, section wrapper shape, and BEM patterns
• data/foundry/block-options.yaml
  • Canonical registry of supported design fields and variants per block
  • Intended as documentation plus a future validation input

Together these reduce implementation drift and keep block contracts consistent across core, themes, starter, and demo sites.

These artifacts should be treated as open integration contracts, not as private LikeStyle Control internals.

Theme-Provided Components

likestyle-foundry-theme-shield now provides reusable layout primitives by default:

• layouts/_default/baseof.html
• layouts/partials/header/site-header.html
• layouts/partials/footer/site-footer.html
• layouts/partials/head/theme-css.html
• Hooks for extension:
  • layouts/partials/head-start.html
  • layouts/partials/head-end.html
• layouts/partials/body-start.html
• layouts/partials/body-end.html

Shared theme/layout code may also expose pluggable hooks for:

• preview metadata
• version surfaces
• attribution or badge surfaces

These hooks should remain optional and policy-driven, not universal hard-coded requirements.

Header behavior

• Reads site.Menus.main
• Supports nested menu children
• Mobile menu toggle + submenu toggles
• Optional CTA from site.Params.header.cta
• Optional logo from site.Params.logo (fallback to title text)

Footer behavior

• Reads site.Menus.footer, fallback to site.Menus.main
• Supports grouped link columns (children)
• Optional social links from site.Params.footer.social
• Optional tagline from site.Params.footer.tagline
• Includes current year copyright

CSS Architecture

The CSS model is layered:

1. Theme tokens (--foundry-*) define brand colors, surfaces, typography, radii, shadows, and motion.
2. Theme component rules style common blocks, header/footer, forms, cards, buttons, and utility mappings.
3. Site overrides should be minimal and brand-specific only.

Goal: consume the theme defaults first, then add only site-specific deltas.

Tailwind + Utility Integration

Foundry blocks use class contracts from data/foundry/classes.yaml (button/card/chip/panel tokens). The theme maps common utility patterns to tokenized design values so you can keep content clean and avoid massive per-site CSS files.

Customizing Header and Footer

Recommended override strategy:

1. Start with theme defaults.
2. Change menus and params first.
3. Override partials locally only when structure must change.

Common config knobs:

• site.Title
• site.Params.logo
• site.Params.header.cta
• site.Params.footer.tagline
• site.Params.footer.social
• site.Menus.main, site.Menus.footer

Feature Flags Reference

Feature flags are read from site.Params.foundry.features (case-insensitive keys):

• newNav: Enables modern nav behavior (submenu toggles, mobile interactions).
• experimentalHero: Enables hero behavior gated for rollout.
• uiCards: Enables card/panel-heavy styling across compatible blocks.
• animations: Enables motion hooks/class behavior.

Theme base layout also emits body classes from enabled flags:

• foundry-feature-<flag> for each enabled flag
• foundry-motion-enabled or foundry-motion-disabled

This supports gradual rollout and per-site compatibility.

Shared Runtime Utilities

Foundry runtime behavior should stay centralized when multiple sites need the same interaction pattern. Current examples:

• Motion engines in foundry-motion.js
• Shared header measurement that publishes --foundry-scroll-offset
• Table of contents state management for active items, completed items, mobile compact mode, and progress rails

Themes should style these behaviors through tokens and class contracts, while sites only own placement and layout wrappers when necessary.

Versioning and Stability

Pin module versions in each site (go.mod) to prevent accidental design/runtime changes. Use controlled bundle upgrades and validate against docs, starter, and preview environments before production rollout.

See also:

• Foundry Charter
• Owner Visibility And Inventory
• Foundry Acceptance Rules