Theme implementation contract

Foundry theming is governed by the cross-platform styling policy. The short version is: tokens are the contract; Tailwind is not.

Four-layer CSS cascade

Foundry resolves styles in this order:

1. assets/css/foundry-base.css — neutral --foundry-* fallback variables.
2. Optional compiled utility/theme layer — may include Tailwind-generated CSS where a site or theme already uses it.
3. Optional theme module CSS (for example theme-shield assets/css/theme.css) — overrides variables and adds presentation rules.
4. Optional site override layer (assets/css/foundry-overrides.css) — loaded after theme CSS for downstream fixes that truly must win.

This ordering is implemented in layouts/_partials/css.html, which loads foundry-base.css before higher-level styling layers. Theme base templates should then load theme CSS and finally partial "foundry/head/site-overrides-css.html" ..

Using the framework without a theme

foundry-base.css provides neutral defaults for every required token, so blocks render correctly even with no theme module imported.

Using theme-shield

theme-shield adds a complete visual identity layer: typography system, color palette, dark mode, card interactions, and section treatments.

It notably sets --foundry-bg: #f2f5fb, Playfair Display heading fonts, and alternating section backgrounds/dividers.

Sites with a full custom brand system (for example restricted proof consumer) should typically import Foundry core without theme-shield.

Add it with module imports:

module:
  imports:
    - path: github.com/jerrybroughton/likestyle-foundry-core
    - path: github.com/jerrybroughton/likestyle-foundry-theme-shield

Creating a custom theme

Create a Hugo module with assets/css/theme.css and override only the --foundry-* tokens you need. Keep structure/components in core; keep visual language in the theme.

Do not make Tailwind the only path to a usable theme. A pinned downstream site should still render correctly from shipped CSS and token overrides.

Recommended structure:

my-foundry-theme/
  assets/
    css/
      theme.css
  layouts/
    partials/
      head/
        theme-css.html

Downstream site structure:

my-foundry-site/
  assets/
    css/
      foundry-overrides.css

Use foundry-overrides.css only for:

• theme-level bug fixes that must load after theme CSS
• site-specific component overrides that cannot be expressed by tokens alone
• temporary compatibility patches during migration

Do not treat foundry-overrides.css as the main site stylesheet.

Dark mode pattern:

:root {
  --foundry-bg: #ffffff;
  --foundry-surface: #ffffff;
  --foundry-surface-soft: #f6f8fc;
  --foundry-text: #0f172a;
  --foundry-text-muted: #475569;
  --foundry-border: #dbe4f4;
  --foundry-brand-primary: #1f3b82;
  --foundry-brand-accent: #c7352f;
}

.dark,
[data-theme="dark"] {
  --foundry-bg: #0a122e;
  --foundry-surface: #0f1d49;
  --foundry-surface-soft: #162a5d;
  --foundry-text: #edf2ff;
  --foundry-text-muted: #c1cff2;
  --foundry-border: #2d4276;
}

Optional component tokens

When a shared block needs more control than the global surface/link tokens provide, Foundry can expose block-scoped component tokens instead of forcing downstream selector overrides.

The search block supports optional --foundry-search-* tokens for panel, input, result card, media border, pill/tag, and title hover styling.

The table of contents widget supports optional --foundry-toc-* tokens for panel background, toggle surface, progress rail, and active/completed link states.

Themes should prefer those tokens over overriding internal .foundry-search__* or .foundry-table-of-contents__* selectors in site CSS.

Variable reference

Full comparison of core defaults and theme-shield overrides.

Theme-shield also defines additional optional tokens for links, typography, focus styles, and extended shadows.