WP Block Themes

When to use

• editing

  theme.json

  (presets, settings, styles, per-block styles)
• adding or changing templates (

  templates/*.html

  ) and template parts (

  parts/*.html

  )
• adding patterns (

  patterns/*.php

  ) and controlling what appears in the inserter
• adding style variations (

  styles/*.json

  )
• debugging “styles not applying” / “editor doesn’t reflect theme.json”

Inputs required

• Repo root and which theme is targeted (theme directory if multiple exist).
• Target WordPress version range (theme.json version and features vary by core version).
• Where the issue manifests: Site Editor, post editor, frontend, or all.

Procedure

0) Triage and locate block theme roots

1. Run triage:

   • node skills/wp-project-triage/scripts/detect_wp_project.mjs

2. Detect theme roots + key folders:

   • node skills/wp-block-themes/scripts/detect_block_themes.mjs

1) Create a new block theme (if needed)

• Prefer starting from a known-good scaffold (or exporting from a WP environment) rather than guessing file layout.
• Be explicit about the minimum supported WordPress version because

  theme.json

  schema versions differ.

• references/creating-new-block-theme.md

detect_block_themes

2) Confirm theme type and override expectations

• Block theme indicators:

  • theme.json

    present

  • templates/

    and/or

    parts/

    present
• Remember the style hierarchy:
  • core defaults → theme.json → child theme → user customizations
  • user customizations can make theme.json edits appear “ignored”

• references/debugging.md

  (style hierarchy + fastest checks)

3) Make

theme.json

changes safely

• settings (what the UI allows): presets, typography scale, colors, layout, spacing
• styles (how it looks by default): CSS-like rules for elements/blocks

• references/theme-json.md

4) Templates and template parts

• Templates live under

  templates/

  and are HTML.
• Template parts live under

  parts/

  and must not be nested in subdirectories.

• references/templates-and-parts.md

5) Patterns

patterns/

• references/patterns.md

6) Style variations

styles/

• references/style-variations.md

Verification

• Site Editor reflects changes where expected (Styles UI, templates, patterns).
• Frontend renders with expected styles.
• If styles aren’t changing, confirm whether user customizations override theme defaults.
• Run the repo’s build/lint scripts if assets are involved (fonts, custom JS/CSS build).

Failure modes / debugging

• references/debugging.md

• wrong theme root (editing an inactive theme)
• user customizations override your defaults
• invalid

  theme.json

  shape/typos prevent application
• templates/parts in wrong folders (or nested parts)

Escalation

• Theme Handbook and Block Editor Handbook for

  theme.json

  , templates, patterns, and style variations.