Theme implementation contract

Foundry theming follows the token-first styling policy used across Foundry. 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

Shared typography roles

Foundry Core exposes neutral typography role tokens in foundry-base.css so themes can tune hierarchy without forking block selectors:

• --foundry-font-family-heading
• --foundry-font-family-body
• --foundry-font-family-ui
• --foundry-type-display-size
• --foundry-type-headline-size
• --foundry-type-section-size
• --foundry-type-item-size
• --foundry-type-body-size
• --foundry-type-meta-size
• --foundry-type-display-line-height
• --foundry-type-body-line-height
• --foundry-type-measure
• --foundry-type-meta-tracking

Use these roles before writing local title, body, meta, or reading-measure selectors. High-expression page presets can still keep profile-specific tokens, but those tokens should alias the shared roles where the meaning matches.

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.

For the current token-depth findings and the next contract-first slice, see Milestone 2 Theme Token Depth Audit. The machine-readable token group contract lives in data/foundry/theme-token-manifest.json and classifies token groups by purpose, owner, source CSS, required/optional status, current tokens, planned tokens, known gaps, and proof surface before broad CSS expansion. Inspect the contract with:

foundry inspect theme-tokens
foundry inspect theme-tokens --json

The same manifest includes draft theme profile guidance for quiet editorial, cinematic campaign, utility-heavy service, immersive product/story, and gallery/property/destination starts. Profiles connect token groups to page jobs, proof surfaces, acceptance gates, and anti-drift notes before reference themes are implemented. See Milestone 2 General Theme Profile Guidance.

Before building reference themes or broad profile CSS, use the Milestone 2 Reference Theme Proof Brief. The same proof matrix is exposed through data/foundry/theme-token-manifest.json and foundry inspect theme-tokens --json, covering representative pages, viewport checks, reduced-motion checks, dark-mode expectations, and no-framework gates for each profile.

The first rendered profile proof is Milestone 2 Cinematic Campaign Reference Theme Proof. It uses fixtures/compatibility/cinematic-campaign-theme-proof/ and a fixture-local assets/css/foundry-reference-proof.css layer to prove campaign art direction with plain CSS before broad shared theme CSS expansion.

The second rendered profile proof is Milestone 2 Utility Service Reference Theme Proof. It uses fixtures/compatibility/utility-service-theme-proof/ to prove service routing, search, static forms, resources, and CTA tone with the same plain CSS proof-layer pattern.

The third rendered profile proof is Milestone 2 Quiet Editorial Reference Theme Proof. It uses fixtures/compatibility/quiet-editorial-theme-proof/ to prove article and journal reading rhythm, metadata, table of contents, related resources, restrained CTAs, and dark-mode reading comfort with the same plain CSS proof-layer pattern.

The fourth rendered profile proof is Milestone 2 Immersive Product Story Reference Theme Proof. It uses fixtures/compatibility/immersive-product-story-theme-proof/ to prove product/story first viewport treatment, media sequence pacing, signature detail, comparison, narrative proof, FAQ, contextual CTA, reduced-motion behavior, and no-framework story readability with the same plain CSS proof-layer pattern.

The fifth rendered profile proof is Milestone 2 Gallery Property Reference Theme Proof. It uses fixtures/compatibility/gallery-property-destination-theme-proof/ to prove property/destination first viewport treatment, gallery browsing, amenity proof, inquiry handoff, curated dark media mode, reduced-motion behavior, and no-framework media readability with the same plain CSS proof-layer pattern.

The cross-proof QA handoff is Milestone 2 Reference Theme Visual QA Matrix. It compares the five completed proof fixtures across desktop, mobile, tablet/content-scan, no-framework, reduced-motion, and dark-mode expectations before shared reference theme CSS expands.

The shared token candidate handoff is Milestone 2 Shared Reference Theme Token Candidate Contract. It records planned media, panel, CTA, and dark-media candidates with owners, proof surfaces, promotion gates, and the hook audit required before implementation.

The hook coverage checkpoint is Milestone 2 Reference Theme Hook Coverage Audit. It maps those shared token candidates to existing block hooks, additive hook gaps, owner files, readiness buckets, and the smallest next shared CSS pilot scope before implementation begins.

The first shared CSS pilot scope is Milestone 2 Shared Reference Theme CSS Pilot Scope. It limits the implementation handoff to --foundry-cta-panel-bg and --foundry-cta-panel-border on existing CTA hooks, with fixture and browser gates before any wider media, panel, card, form, or dark-mode token work.

The first shared CSS pilot implementation is Milestone 2 CTA Panel Token CSS Pilot Implementation. It implements the CTA panel background and border tokens in assets/css/foundry-base.css, maps them to the framed CTA panel hook, and keeps CTA shadow/emphasis plus media, panel, card, form, and dark-mode tokens out of scope.

The CTA panel pilot browser review is Milestone 2 CTA Panel Token Browser QA And Promotion Review. It records the fixture QA results, confirms the CTA panel tokens did not leak into buttons, forms, media, cards, generic panels, or dark-mode surfaces, and promotes only --foundry-cta-panel-shadow for the next scoped implementation slice.

The CTA panel shadow implementation is Milestone 2 CTA Panel Shadow Token Implementation. It implements --foundry-cta-panel-shadow against the framed CTA panel hook and keeps --foundry-cta-emphasis planned for a separate scope review before any emphasis behavior touches buttons, campaign copy, or site-specific conversion styling.

The CTA emphasis scope review is Milestone 2 CTA Emphasis Scope Review. It parks broad --foundry-cta-emphasis as too wide for direct implementation and decomposes the safe part into CTA title and body copy color tokens.

The CTA copy color implementation is Milestone 2 CTA Copy Color Token Implementation. It implements --foundry-cta-title-color and --foundry-cta-text-color on existing CTA copy hooks while keeping actions on the shared button component.

The media treatment pilot scope is Milestone 2 Media Treatment Token Pilot Scope. It chooses --foundry-media-radius, --foundry-media-frame-bg, and --foundry-media-caption-color as the first shared media tokens because they map to repeated frame and caption hooks without changing content semantics, CTA behavior, generic panels, cards, forms, dark mode, or JavaScript.

The media treatment CSS pilot implementation is Milestone 2 Media Treatment Token CSS Pilot Implementation. It implements the three scoped media tokens with local fallback variables so article, story, utility, campaign, and gallery media keep their default treatment unless a theme deliberately overrides the shared media contract.

The media treatment browser QA and promotion review is Milestone 2 Media Treatment Token Browser QA And Promotion Review. It confirms the media pilot across the reference proofs and promotes only --foundry-media-border for the next implementation slice. Shadow, filter, object-position, overlay, and aspect tokens remain planned until their own review gates.

The media border token implementation is Milestone 2 Media Border Token Implementation. It implements --foundry-media-border on existing bordered media hooks only, preserving border widths, border presence, layout behavior, generic cards, panels, CTAs, forms, search, dark mode, and JavaScript behavior.

The media shadow scope review is Milestone 2 Media Shadow Scope Review. It approves --foundry-media-shadow only as a future implementation candidate for media hooks that already have shadow presence. It keeps unshadowed media, cards, panels, dialogs, CTAs, forms, search, dark-mode chrome, animation, and JavaScript out of the shared media shadow contract.

The media shadow token implementation is Milestone 2 Media Shadow Token Implementation. It implements --foundry-media-shadow on existing elevated media hooks only, preserving unshadowed media, story/profile-local depth rules, cards, panels, dialogs, CTAs, forms, search, dark-mode chrome, animation, layout, and JavaScript behavior.

The media filter scope review is Milestone 2 Media Filter Scope Review. It keeps --foundry-media-filter planned instead of promoting a broad shared implementation, because image filters can damage product, property, medical, editorial, result, and proof-media inspectability. Profile-specific tokens such as --foundry-creative-image-filter remain valid where the theme explicitly owns image tone.

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.