Foundry architecture

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

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.

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

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

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.