Theming

This guide explains how Foundry theme-shield styling works and how to override it safely.

What Theme-Shield Provides Out of the Box

likestyle-foundry-theme-shield includes:

• Base layout (_default/baseof.html)
• Reusable header/footer partials
• Theme stylesheet (assets/css/theme.css) with:
  • typography system
  • form controls
  • button states
  • card interactions and motion-safe transitions
  • dark mode token swaps
  • utility-class remappings for common Tailwind-style classes

The recommended default is: use theme defaults first, then layer small site-specific overrides.

CSS Custom Properties Reference (--foundry-*)

These variables are defined in :root and swapped in dark mode.

Brand + semantic colors

• --foundry-brand-primary
• --foundry-brand-primary-strong
• --foundry-brand-accent
• --foundry-link
• --foundry-link-hover
• --foundry-success
• --foundry-success-soft
• --foundry-danger
• --foundry-danger-soft
• --foundry-warning

Surfaces + text

• --foundry-bg
• --foundry-surface
• --foundry-surface-soft
• --foundry-text
• --foundry-text-muted
• --foundry-border
• --foundry-border-strong
• --foundry-focus

Shadows + radius

• --foundry-shadow-sm
• --foundry-shadow-md
• --foundry-shadow-lg
• --foundry-radius-sm
• --foundry-radius
• --foundry-radius-lg

Typography

• --foundry-font-family-body
• --foundry-font-family-heading
• --foundry-font-family-ui
• --foundry-font-family-mono
• --foundry-line-height-body
• --foundry-line-height-heading
• --foundry-letter-spacing-heading

Motion and interaction

• --foundry-ease-standard
• --foundry-duration-fast
• --foundry-duration-base
• --foundry-duration-slow
• --foundry-card-hover-lift
• --foundry-card-hover-border
• --foundry-card-hover-shadow

Optional component tokens

When a shared block needs more control than the global surface/text/link tokens provide, Foundry may expose block-scoped component tokens.

Current example:

• Search supports optional --foundry-search-* tokens for panel, input, result card, media border, pill/tag, and title hover styling.
• Table of contents supports optional --foundry-toc-* tokens for panel background, compact toggle surface, progress rail, and active/completed link states.

Prefer component tokens over overriding internal block selectors when a shared block exposes them.

Sticky navigation and anchor offset

Foundry now exposes a shared --foundry-scroll-offset value, derived from the live header height plus a small gap. The table of contents widget and heading targets use that value so anchor links land below fixed headers without per-site hardcoded offsets.

If a theme changes header height substantially, adjust the theme design first and let the shared offset continue to flow from that measured header, instead of overriding page templates with pixel values.

Override Colors and Fonts

Create a small site override file, for example assets/css/site.css:

:root {
  --foundry-brand-primary: #0d4d8b;
  --foundry-brand-primary-strong: #073562;
  --foundry-brand-accent: #ef6a2f;
  --foundry-font-family-body: "Inter", "Segoe UI", Arial, sans-serif;
  --foundry-font-family-heading: "Merriweather", Georgia, serif;
}

.dark,
[data-theme="dark"] {
  --foundry-bg: #081426;
  --foundry-surface: #0f1f3d;
  --foundry-text: #e8f0ff;
}

Load it with a local layouts/partials/css.html partial (site-level override).

Site-Specific CSS (Recommended Pattern)

1. Keep theme defaults intact.
2. Add only brand/layout-specific rules in site.css.
3. Avoid overriding block internals unless required.
4. Prefer changing block structure/data or component tokens before writing custom CSS.

Good use cases for site CSS:

• brand-only gradients
• one-off campaign hero effects
• highly specific page treatments

Late Override CSS

Foundry themes may now load an optional late override file after theme.css:

• assets/css/foundry-overrides.css

Use it sparingly. This file exists for:

• theme bug fixes that must load after theme CSS
• temporary migration patches
• downstream component overrides that cannot be solved with tokens alone

Do not use foundry-overrides.css as your main site stylesheet. Keep normal site styling in your regular site CSS layer and reserve the late override file for changes that truly need last-wins precedence.

Dark Mode Support

Theme-shield supports dark mode through token remapping under:

• .dark
• [data-theme="dark"]

When you override tokens, include both light and dark values so contrast remains accessible.

Motion and Reduced Motion

Theme transitions use tokenized durations/easing and respect reduced motion patterns. If adding animation, wrap it in:

@media (prefers-reduced-motion: reduce) {
  /* disable or simplify */
}

Tailwind Integration and Class Scanning

Foundry blocks use utility-heavy class contracts from core (data/foundry/classes.yaml). In Hugo/Tailwind workflows:

• enable build stats (build.writeStats: true) so class usage can be scanned reliably
• keep block/template class names literal (avoid runtime string composition when possible)
• preserve any safelist entries required by dynamic variants

Theme-shield also includes utility-to-token mappings so common utility patterns inherit your --foundry-* color, border, and typography system.

Configuration Touchpoints

Common theme-related parameters:

• site.Title
• site.Params.logo
• site.Params.header.cta
• site.Params.footer.tagline
• site.Params.footer.social
• site.Params.foundry.features
• site.Params.body_class / site.Params.foundry.body_class

Use params for structure/content behavior, and CSS variables for visual system control.