Child Theming with WP Rig

WP Rig can turn any theme it builds into a child theme build system: keep the framework’s build pipeline, PHP architecture, and asset handling, but declare yourself a child of a parent theme. Conversion is paradigm-aware — the resulting child carries exactly the components its theme type needs.

Creating a child theme

npm run setup-child   # rig-init + childify in one command

Run it in a fresh WP Rig checkout. The interactive init configures the theme (name, slug, paradigm, dev URL), then childify converts the checkout into a child of your chosen parent theme.

What childify changes

  • Style header: the child declares its Template: (the parent theme’s directory name).
  • Component keep-list derived from the paradigm: classic children keep the classic core; universal and block-based children additionally keep Editor, Blocks, Block_Patterns, Block_Styles, and Icons.
  • inc/components-manifest.json: the kept components are written through the framework-native manifest mechanism — the same list Theme::get_default_components() reads first. The old regex-based Theme.php stripper is gone.
  • Config hygiene: config.local.json never ships with the child — your machine-specific settings stay home.
  • Version separation: the framework version (tracked in config/framework.json) is stripped from the child; it carries only its own theme version from config. See Theme Configuration.

What you override in a child

  • Templates: copy a template from the parent and edit it — WordPress resolves child templates first.
  • CSS/JS source: the child’s assets/ builds through the same Lightning CSS/esbuild pipeline; enqueue what the parent doesn’t.
  • Components: the child can add its own components under inc/ — auto-discovery treats them identically.
  • Icons: an icon in the child’s assets/icons/ overrides a parent icon of the same filename (see Icons & the Icon API).
  • Design tokens: the child ships its own config/tokens.json; regenerate with rig:tokens (see Design Tokens v2).

Registry components and children

Components added from the Open Component Registry live in the child like any other component — registered in components-manifest.json, paradigm-gated, and removable with rig:remove. A child is the natural place for client-specific registry components you don’t want in the parent.

Compatibility testing

Child theme compatibility is covered by automated tests (asset and translation handling, version management), so parent updates that would break children get caught in CI rather than in production.

Theme Paradigms (how the keep-list derives), Theme Configuration (version separation), and The Open Component Registry.