Theme implementation contract

Foundry theming is governed by the cross-platform [styling policy](https://github.com/jerrybroughton/likestyle-foundry-core/blob/v0.1.24/docs/</Users/gb/Library/Mobile Documents/comappleCloudDocs/Documents/CodexProjects/likestyle-foundry-distribution/docs/styling-policy.md>). The short version is: tokens are the contract; Tailwind is not.

Five-layer CSS cascade

Foundry resolves styles in this order:

1. assets/css/foundry-base.css — neutral --foundry-* fallback variables, stable shell partial styling, accessibility helpers, and shared button primitives.
2. assets/css/foundry-creative.css — page-preset token defaults for the Creative v1 lane.
3. Optional compiled utility/theme layer — may include Tailwind-generated CSS where a site or theme already uses it.
4. Optional theme module CSS (for example theme-shield assets/css/theme.css) — overrides variables and adds presentation rules.
5. 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 and Foundry page-preset token layers 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. It also includes fallback styling for stable core UI surfaces that appear in generated fixtures and consumer shells:

• site-header navigation, including mobile menu defaults
• search-trigger
• sr-only
• foundry-button primary, secondary, and ghost variants

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 regulated production proof site) 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.

Creative preset tokens

Creative v1 pages expose page_preset and motion_profile as page-level classes and data attributes:

• foundry-page--preset-creative-portfolio
• foundry-page--motion-cinematic
• foundry-page--motion-editorial
• foundry-page--motion-quiet

assets/css/foundry-creative.css uses those classes to define theme-owned authored-feel defaults for typography rhythm, spacing tempo, media treatment, image treatment, panel treatment, CTA tone, and motion tone. It covers the Creative route-floor surfaces directly: hero, section header, media sequence, gallery, founder profile, page list, timeline, contact split, rich text, CTA, and chapter navigation. Themes can override the same variables from their theme CSS without forking block partials.

Key Creative tokens include:

• --foundry-creative-heading-family
• --foundry-creative-body-family
• --foundry-creative-section-space-y
• --foundry-creative-reel-gap
• --foundry-creative-media-radius
• --foundry-creative-media-shadow
• --foundry-creative-panel-radius
• --foundry-creative-panel-bg
• --foundry-creative-panel-border
• --foundry-creative-panel-shadow
• --foundry-creative-image-filter
• --foundry-creative-gap
• --foundry-motion-distance
• --foundry-motion-duration
• --foundry-motion-parallax-max
• --foundry-motion-kb-scale

Motion tone

Themes own motion tone through tokens and presentation defaults, while Core owns the motion runtime and block contracts. For the planned profile model, parallax limits, and reduced-motion requirements, see Foundry Motion Kit Plan.

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.