Child theme

Minimum contract

A production child theme based on Core FSE must:

1. declare the parent theme;
2. have its own theme.json;
3. define the required brand CSS variables;
4. import core CSS into its own bundles;
5. load the shared bundle on the frontend and in the editor iframe;
6. load the frontend-only bundle on the frontend;
7. define the site fonts and actual global styles;
8. verify frontend/editor parity.

Declaring the parent theme

style.css:

/**
 * Theme Name: Example FSE
 * Template: core-fse
 */

Without Template: core-fse, WordPress will not apply parent/child inheritance.

Required brand variables

The child theme must deliberately define:

:root {
  --color-base: ...;
  --color-contrast: ...;
  --color-accent: ...;
  --color-on-accent: ...;
  --color-on-image: ...;
  --color-links: ...;
  --color-links-hover: ...;
}

Checklist:

• base and contrast form the primary page surface;
• on-accent is legible on accent;
• on-image is suitable for content and focus states over images;
• link and hover states are distinguishable;
• values have been checked for accessible contrast.

Optional overrides

:root {
  --_spacing--edge-x: var(--size-fluid400-72px);
  --_spacing--base-gap: var(--size-fluid150-24px);

  --_font-size-huge: var(--size-fluid200-92px);
  --_font-size-huge-fluid: var(--size-fluid300-92px);

  --line-height-normal: 1.5;
  --letter-spacing-tight: -0.01em;
  --radius-medium: 10px;
}

A primitive is used here to configure a system alias, not as a component API.

Child-theme theme.json

A child theme usually adds:

• the complete final color palette;
• gradients and duotone where needed;
• font families and fontFace;
• shadow presets;
• root global styles;
• element styles;
• block styles.

Fonts belong to the child theme:

{
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "name": "basic",
          "slug": "basic",
          "fontFamily": "ExampleFont, sans-serif",
          "fontFace": []
        }
      ]
    }
  }
}

Afterward, this is available:

var(--wp--preset--font-family--basic)

Do not assume the parent palette is automatically retained with every extension. Check the final merged theme.json and Gutenberg UI.

CSS entry points

Shared frontend/editor entry point:

@use '../../../../core-fse/assets/css/vars/primitives.css' as *;
@use '../../../../core-fse/assets/css/vars/semantic.css' as *;
@use '../../../../core-fse/assets/css/vars/theme-core.css' as *;
@use '../vars.css' as *;
@use '../../../../core-fse/assets/css/front-and-admin.css' as *;
@use '_extra.scss' as *;

Frontend entry point:

@use '../../../../core-fse/assets/css/front.css' as *;
@use '_extra.scss' as *;

The variables file path and name may differ, but child overrides must come after Core contract defaults and before styles that use them.

Asset enqueue

The shared bundle must load through enqueue_block_assets to reach:

• the frontend;
• the editor iframe.

The frontend-only bundle loads through wp_enqueue_scripts.

Do not rely on a separate runtime enqueue of core CSS: the child bundle already contains the imported base layer.

Benedictine: case study

Benedictine is located at wp-content/themes/benedictine.

Variables

assets/css/vars.css:

• overrides the required colors;
• adds base-2, base-3, and accent variants;
• changes edge-x, base-gap, and huge font sizes;
• refines letter spacing, radius, and line height.

Shared bundle

assets/css/front-and-admin/front-and-admin.scss uses this order:

core primitives
→ core semantic
→ Core contract
→ Benedictine vars
→ core front-and-admin
→ Benedictine extras

Frontend bundle

assets/css/front/front-styles.scss imports core-fse/assets/css/front.css, then Benedictine frontend-only styles.

theme.json

Benedictine:

• lists base colors again and adds brand variants;
• adds gradients;
• registers variable fonts and unicode ranges;
• defines page, typography, element, and block styles;
• uses inherited spacing and font-size presets.

This is an implementation example, not a file to copy blindly. A new site must choose its own colors, fonts, and global styles.

Build

Current Benedictine command:

cd wp-content/themes/benedictine
npm run build

Vite creates .min.css. Do not edit these files manually.

New child-theme checklist

• [ ] Template: core-fse is specified.
• [ ] Required color variables are defined.
• [ ] The final palette includes the required core roles.
• [ ] Fonts are declared in the child theme.json.
• [ ] Root styles define page colors, spacing, and typography.
• [ ] Core variable files are imported in the correct order.
• [ ] The front-and-admin bundle is loaded in the editor iframe.
• [ ] The frontend bundle contains core-fse/assets/css/front.css.
• [ ] Build output is rebuilt.
• [ ] The frontend, post editor, and Site Editor are checked.
• [ ] Focus and contrast are checked.