Site shell contract

Phase: 08-shell-contract-governance Status: Stable (v1)

The Foundry shell contract defines how downstream themes and sites configure site chrome — header, navigation, footer, utility surfaces, and page-level exceptions — without copying shell partials locally.

Why a Shell Contract?

Without a contract, every site ends up with:

• Local copies of layouts/partials/header/, layouts/partials/footer/, and layouts/_default/baseof.html
• Bespoke template conditions scattered across dozens of partials
• No machine-readable ownership model → AI editors can’t safely touch shell code
• Governance by tribal knowledge rather than validated structure

The shell contract moves this behaviour into typed, schema-backed Core ownership that downstream repos configure rather than copy.

Artifacts

Shell Surfaces (shell-manifest)

The shell manifest covers these surfaces:

The shared header consumes the normalized model directly. Without a manifest, it preserves the established site-title, home-link, and main menu behavior. Themes still own density, typography, color, and responsive presentation.

The contact bar is deliberately not injected by a universal base layout. A site that wants it calls the portable composition once near body-end:

{{ partial "foundry/shell/contact-bar.html" (dict "page" .) }}

Typed Link Kinds

All link entries in the manifest use a typed kind field:

Page-Level Chrome Exceptions (page-shell)

Pages declare shell behaviour through front matter fields that are normalized by helpers/page-shell-params.html:

---
title: Landing Page
header_mode: transparent      # overlays first content block
footer_mode: minimal          # legal links only
hide_site_chrome: false       # true = full chrome suppression
route_owner: services         # canonical section key
utility_surface: cta-only     # show only primary CTA in header
show_breadcrumbs: true        # render visible breadcrumbs when shell supports it
noindex: false
suppress_announcement: false
suppress_contact_bar: false
shell_compat_mode: false       # set true only during phased migration
---

Field Reference

Using the Helper Partial

In your base layout or shell partial, resolve page-shell params once at the top:

{{/* layouts/_default/baseof.html */}}
{{ $shell := partial "foundry/helpers/page-shell-params.html" . }}

{{ if not $shell.hide_site_chrome }}
  {{ partial "header/site-header.html" (dict "page" . "shell" $shell) }}
{{ end }}

{{ block "main" . }}{{ end }}

{{ if not $shell.hide_site_chrome }}
  {{ partial "footer/site-footer.html" (dict "page" . "shell" $shell) }}
  {{ partial "foundry/shell/contact-bar.html" (dict "page" .) }}
{{ end }}

The helper handles:

• Reading typed contract fields from .Params
• Applying defaults for missing fields
• Legacy compat: falls back to older param names during migration

Visible Breadcrumbs

Foundry already emits breadcrumb structured data through SEO schema. For visible page breadcrumbs, call the shared partial from the shell where the site wants breadcrumbs to appear:

{{ partial "foundry/navigation/breadcrumbs.html" (dict "page" . "shell" $shell) }}

The partial renders only when show_breadcrumbs: true and when the current page has more than one crumb. It uses Hugo ancestors, respects breadcrumb_home_label, and marks the current page with aria-current="page".

Navigation Interaction Contract

Foundry Core owns the portable interaction behavior for menus. Themes and sites continue to own menu content, density, visual styling, and information architecture.

The Core header loads assets/js/foundry-navigation.js through foundry/framework/foundry-navigation.html. The controller provides:

• synchronized Menu / Close labels and aria-expanded state
• mobile scroll locking, contained focus, scroll reset, and outside dismissal
• submenu-first Escape handling with focus restoration
• viewport-change cleanup so desktop and mobile state cannot leak across modes
• click activation for touch/coarse pointers and optional hover activation for fine pointers
• pointer-safe submenu state and automatic closure when a navigation link or another header surface is selected
• an is-scrolled header state for theme-owned transparent/sticky treatments

The default Core header switches at 48rem. A custom header must declare the same mobile maximum used by its CSS:

<header
  data-foundry-header
  data-foundry-nav-breakpoint="899px"
  data-foundry-nav-hover="true"
  data-foundry-nav-scroll-lock="true"
  data-foundry-nav-contain-focus="true">
  <button data-foundry-nav-toggle>...</button>
  <nav data-foundry-nav>...</nav>
</header>

Submenu buttons use data-foundry-submenu-toggle; their owning list item uses foundry-nav-item--has-submenu; and the panel uses data-foundry-submenu. Core applies is-menu-open, is-mobile-navigation, is-submenu-open, and foundry-nav-open as runtime state hooks.

Custom shells that shadow the Core header must load the shared controller after their navigation markup:

{{ partial "foundry/framework/foundry-navigation.html" . }}

Sites should not copy the controller into a local inline script. Brand-specific mega-menu columns, mobile content priorities, icons, and CTA copy remain in the theme or site layer.

Shared Layer Tokens

Core exposes a stacking contract so a downstream sticky header cannot cover a search overlay or modal:

Themes may raise the scale, but must preserve that ordering. Override the tokens instead of patching individual Core selectors with unrelated z-index values.

Ownership Model

Sites configure shell behaviour through the contract. They do not copy shell partials unless:

1. The needed behaviour cannot be expressed through the contract
2. The shadow is documented in .planning/shadow-copy-review.md with a reason and migration phase
3. The shadow passes the override validator with an explicit allowlist entry

Validation

foundry validate shell --root /path/to/likestyle-foundry-core --json
foundry validate shell-overrides --site /path/to/downstream-repo --json
foundry validate shell-overrides --site /path/to/downstream-repo \
  --allowlist /path/to/downstream-repo/.planning/shell-shadow-allowlist.json \
  --json

Core’s Go validators are the only supported shell-contract maintenance path. See CLI Reference and Tooling Policy.

Shell Shadow Migration Path

If a downstream repo has temporary shell shadows (common during initial adoption):

1. Document each shadow in .planning/shadow-copy-review.md under “Shell Shadows” with a reason and target phase.
2. Create .planning/shell-shadow-allowlist.json listing the shadow paths.
3. Run foundry validate shell-overrides --allowlist <file> in CI to catch any new unreviewed shadows.
4. Retire the shadow in the designated phase by adopting the Core contract field or theme variant.
5. Remove the allowlist entry and confirm the validator exits 0.

Compatibility Mode

During migration, set shell_compat_mode: true in page front matter to enable legacy param resolution alongside the new contract. This allows incremental per-page migration without a big-bang rewrite. Remove shell_compat_mode once all pages in a section are migrated.

What This Phase Does Not Do

• Move high-consideration service proof site route labels, CTA copy, or contact info into Core defaults
• Implement final header/footer rendering for any specific theme
• Expand into runtime personalization or non-shell product work
• Promote any shell primitive to “shield” status before a second consumer proves genericity

These are targets for Phase 09 (Theme Capability & Shared Shell Rendering) and Phase 10 (high-consideration service proof site Pilot & Exception Retirement).