Compatibility

The goal of Foundry compatibility policy is straightforward:

• keep shipped sites stable
• keep framework development moving
• make upgrades intentional instead of accidental

Core rule

Existing sites do not follow moving branches.

They pin released module tags and adopt newer releases only when the site owner is ready. Foundry can continue adding features, variants, and fixes, but a site should not change behavior until its pinned versions change.

Repo ownership

Use the narrowest correct layer for every change.

• likestyle-foundry-core
  • shared block markup contracts
  • shared runtime behavior
  • shared structural CSS and fallback tokens
  • additive block APIs and feature flags
• likestyle-foundry-theme-shield
  • neutral visual defaults for shared contracts
  • baseline theme tokens and component styling
• likestyle-foundry-theme-restricted proof consumer
  • restricted proof consumer brand treatment only
  • no shared behavior should originate here
• site repos such as restricted proof consumer
  • page composition
  • content wiring
  • site-only layout wrappers when shared contracts are insufficient
• likestyle-foundry-starter
  • proof that a shared capability is reusable
  • upgrade reference for new sites
• likestyle-foundry-distribution
  • release bundles, compatibility manifests, and verification tooling
• likestyle-foundry-docs
  • policy, contracts, migration guidance, and upgrade documentation

If another site could reasonably use a behavior or contract, it does not belong in a site repo.

Change classes

Every Foundry change should be classified before implementation.

1. Safe additive

Examples:

• new block
• new optional field
• new token
• new variant
• new feature flag
• new theme styling for a new contract

Requirements:

• no existing contract removed or repurposed
• starter or demo coverage if user-facing
• docs updated

2. Soft upgrade

Examples:

• improved behavior behind a new variant
• improved behavior behind an opt-in flag
• new shared runtime that existing consumers can ignore

Requirements:

• existing sites keep current behavior unless they opt in
• migration guidance explains how to adopt
• verify at least one downstream site still builds cleanly

3. Migration-required

Examples:

• default behavior changes for an existing contract
• old field remains supported, but preferred path changes

Requirements:

• deprecation notice in docs
• explicit migration steps
• release bundle notes
• verification against starter and at least one real site

4. Breaking

Examples:

• removing a public field
• removing a stable class or token
• changing markup or runtime expectations for existing consumers

Requirements:

• planned release only
• migration guide first
• distribution manifest with clear upgrade notes
• no silent shipment as normal feature work

Most Foundry work should stay in the first two classes.

Allowed and forbidden default behavior changes

Allowed in minor/feature work:

• adding new optional tokens
• adding new optional fields
• adding new variants
• adding new runtime data attributes or classes
• introducing a new shared capability with site adoption left optional

Not allowed without migration planning:

• changing the meaning of an existing field
• changing default rendering semantics for a widely used block
• removing tokens or classes that sites may already target
• moving behavior from a theme into a site repo or vice versa without contract documentation

Deprecation policy

Foundry should migrate by addition first, replacement second, removal last.

Required sequence:

1. Add the new path.
2. Keep the old path working.
3. Mark the old path deprecated in docs.
4. Publish migration guidance.
5. Remove only in a planned breaking release.

Required verification matrix

For any shared Foundry change, the minimum verification matrix is:

1. Build the changed shared repo if it has its own build or validation command.
2. Build likestyle-foundry-starter.
3. Build at least one real downstream site that consumes the changed contract.
4. Update the starter or demo when the shared feature is user-facing.
5. Update docs before tagging the release bundle complete.

For visual navigation or scroll behavior, keep a starter or demo example page permanently so future changes can be checked against the same scenario.

Release bundles

Foundry compatibility is not just a repo tag problem. It is a stack problem.

Use likestyle-foundry-distribution manifests to define compatible bundles of:

• core
• theme-shield
• brand themes where applicable
• starter reference version
• docs version
• optional control-plane compatibility contracts

Sites should upgrade to a known compatible bundle, not guess which tags across repos happen to work together.

Upgrade path for sites

Recommended site workflow:

1. Pin released module tags in go.mod.
2. Track the current bundle manifest that the site is using.
3. Upgrade to a newer bundle only when ready.
4. Run the site’s local QA and visual review.
5. Deploy only after verification completes.

This keeps production stable while Foundry continues to evolve.