Migration and upgrades

Use this guide to migrate older Foundry sites that built their own layout/CSS before theme-shield became full-featured.

What Moved to Theme-Provided

Older sites often implemented these locally. Theme-shield now provides them by default:

• Base layout shell (_default/baseof.html)
• Header navigation (desktop + mobile + submenu behavior)
• Footer layout and menu rendering
• Typography hierarchy and body copy defaults
• Form input states and focus styling
• Button interaction states
• Card interaction states (hover/focus-within)
• Utility-to-token mappings
• Skip link accessibility styling

Migration goal: delete duplicated local implementations and keep only site-specific deltas.

Step 1: Choose a Compatible Bundle

Before changing site dependencies, choose the target release bundle in likestyle-foundry-distribution.

Use that bundle as the source of truth for:

• the compatible core version
• the compatible theme version
• the matching starter/docs references
• the required verification commands

Step 2: Pin Module Versions

In site go.mod, pin explicit versions for both modules and upgrade intentionally:

require (
  github.com/jerrybroughton/likestyle-foundry-core v0.1.9
  github.com/jerrybroughton/likestyle-foundry-theme-shield v0.1.9
)

Step 3: Remove Local Base Layout Overrides

If your site has layouts/_default/baseof.html only to load CSS or render header/footer:

• delete it, or
• keep a minimal override only if structure truly differs.

Theme base layout already includes:

• theme CSS loading
• hook partials (head-start, head-end, body-start, body-end)
• skip link
• header/footer

Step 4: Switch to Theme Header/Footer

Remove local copies of:

• layouts/partials/header/site-header.html
• layouts/partials/footer/site-footer.html

Then configure via params and menus:

• site.Params.logo
• site.Params.header.cta
• site.Params.footer.tagline
• site.Params.footer.social
• site.Menus.main and optional site.Menus.footer

Only reintroduce local header/footer partials if your information architecture requires custom markup.

Step 5: Remove Redundant CSS

Audit your site CSS by category.

Safe to remove when duplicated

• global typography defaults (h1-h6, p, list styles)
• generic button styles
• generic form field styles
• shared card hover/focus styles
• header nav surfaces/toggles/dropdown defaults
• footer multi-column layout defaults
• utility remaps already handled by theme

Keep as site-specific

• brand-only effects (custom gradients, hero visuals)
• unique campaign/page treatments
• business-specific interaction behavior
• content blocks not covered by core/theme yet

Practical cleanup loop

1. Temporarily disable one local CSS file.
2. Build and inspect critical pages (home, top service pages, contact, blog/list).
3. Restore only rules that are truly site-specific.
4. Repeat until local CSS is mostly brand-specific.

Step 6: Validate Feature Flags

Use params.foundry.features to control rollout:

• newNav
• uiCards
• animations
• experimentalHero (if used)

This lets older sites adopt behavior in stages.

Step 7: Regression Checklist

• Header works on mobile and desktop
• Submenus open/close correctly
• Footer links and social links render correctly
• CTA buttons have proper contrast in light/dark
• Forms have visible focus states
• Block spacing and section rhythm are consistent
• Reduced motion behavior is respected

Version Bump Checklist

When upgrading core/theme versions on a site:

1. Choose the target distribution bundle.
2. Update go.mod module versions.
3. Run hugo mod tidy.
4. Run the bundle verification steps where applicable.
5. Rebuild and test locally (hugo server --disableFastRender).
6. Verify all pages using custom blocks.
7. Run accessibility sanity checks (focus, contrast, keyboard nav).
8. Review visual diffs for top conversion pages.
9. Commit with explicit upgrade message.
10. Tag/release only after QA pass.

Optional: Migration Tracking Table

For larger sites, track progress by file:

• CSS file
• removed lines
• retained lines
• reason retained
• pages verified

This keeps migration repeatable and auditable.