Theming

Foundry v1 does not treat “the theme” as one indivisible template. It separates reusable art direction from customer-owned identity.

The Two Design Layers

A Theme Family owns the broad visual grammar:

• hierarchy and reading rhythm
• surface and shape behavior
• media framing and composition
• responsive transformation
• shell restraint and motion tone

A Customer Brand System owns identity values and rules:

• type stacks and color roles
• spacing and shape preferences
• logo and approved media treatment
• voice and accessibility requirements
• declared customer exceptions

Changing a Theme Family should not rewrite customer facts or identity. Changing a Brand System should not require a layout fork.

The Initial Theme Families

These families are an open Foundry library, not the limit of possible customer design. Their current status and evidence state come from Foundry Core manifests; a compelling screenshot does not promote a draft contract by itself.

Reference Brand Systems Are Not Customer Brands

Core includes fictional reference Brand Systems to make directions visible and test the inheritance contract. They demonstrate outcomes such as clear service, literary studio, natural destination, clinical luxury, experimental studio, playful consumer, and refined hospitality.

Use them for comparison. Replace their names, values, copy, facts, and media before publication.

How A New Site Chooses Design

foundry new-site --list
foundry inspect design-systems --json

Choose in this order:

1. select the Site Type and Site Blueprint for the visitor job
2. compare at least two compatible creative directions
3. choose the Theme Family for art direction
4. replace the reference identity with the Customer Brand System
5. use Section Styles and Controls for bounded page-level decisions
6. create a declared Extension only when the supported design system is genuinely insufficient

The generated foundry-site.yaml, site params, and CSS keep these choices in normal repository files.

See The Differences Before Choosing

The Documentation site’s Explore Foundry guide is the visual learning surface. It pairs real desktop/mobile evidence with explanations for Theme Families, Brand Systems, Site Types, Page Starters, Section Families, Blocks, Styles, and Controls.

Each image states what it proves. A screenshot for an owning Block may show a Control in context, but it is not mislabeled as exact proof of every possible value. Missing coverage remains visible as a documentation gap.

Core’s Visual Example manifest, copyable Hugo source, and exact evidence state remain the authority behind the guide.

Safe Inheritance Order

1. Core fallback tokens and behavior
2. Theme Family art-direction grammar
3. Customer Brand System identity values
4. narrow, declared site-owned Extensions

Prefer a higher-level choice before a lower-level override. A site should not copy a shared partial merely to change brand color, reading rhythm, or a governed Section Style.

CSS Custom Properties

Customer identity commonly uses these portable --foundry-* tokens.

Brand and semantic color

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

Surfaces and text

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

Shape, shadow, and type

• --foundry-shadow-sm
• --foundry-shadow-md
• --foundry-shadow-lg
• --foundry-radius-sm
• --foundry-radius
• --foundry-radius-lg
• --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

• --foundry-ease-standard
• --foundry-duration-fast
• --foundry-duration-base
• --foundry-duration-slow

Customer Brand Override Example

Use the generated assets/css/foundry-overrides.css, or another clearly owned site stylesheet, for Customer Brand System values:

.foundry-page--brand-system-northline {
  --foundry-brand-primary: #174c3c;
  --foundry-brand-accent: #d67a3d;
  --foundry-bg: #f7f4ed;
  --foundry-text: #17221e;
  --foundry-focus: #0b63ce;
  --foundry-font-family-heading: Georgia, "Times New Roman", serif;
  --foundry-font-family-body: Inter, "Segoe UI", sans-serif;
  --foundry-radius: 0.5rem;
}

Keep contrast, focus visibility, reduced motion, and media accuracy as explicit requirements. Do not encode customer facts in CSS.

Component Tokens And Controls

Some Blocks expose component-scoped tokens or bounded design Controls. Prefer those over internal selector overrides. Use:

foundry inspect blocks --json
foundry authoring-contract --site /path/to/site --json

The authoring contract distinguishes complete owner-facing Controls from advanced technical fields. “Complete” means the Control has guidance, safe values, reset behavior, source mapping, and preview semantics—not merely that a field exists in a schema.

Shell Modules And Optional Tooling

Theme Shield remains a compatible shell module for existing and generated sites. It supplies base layout, header/footer behavior, and baseline CSS, but it is not the public art-direction choice and is not the only possible Foundry presentation layer.

Node/Tailwind may still be chosen by a particular customer project as optional site tooling. Foundry v1 does not require it for normal creation, preview, validation, or production builds.

Dark Mode And Reduced Motion

When a site supports dark mode, define accessible identity values for both states. Motion must preserve meaning and remain usable under prefers-reduced-motion: reduce.

When To Create An Extension

Create a named, inspectable, removable, upgrade-aware Extension only when the Theme Family, Customer Brand System, Section Style, tokens, presets, and existing Controls cannot express the real customer need. Repeated useful Extensions are candidates for upstream Foundry work; one-off selector drift is not a design system.