[Tracking] Edit Theme Settings: phased implementation

[bph]

Tracking issue for adding an Edit Theme Settings modal to Create Block Theme.

Why this is important

Building a block theme in the editor should feel seamless — design in the browser, save back to clean theme files. CBT delivers most of that, but the settings layer (palette, fonts, sizes, shadows, units, custom templates) still requires editing theme.json by hand. Edit Theme Settings closes that gap inside the same modal pattern as Edit Theme Metadata.

CBT is not a niche developer tool:

• It's the recommended tool in the theme developer learning pathway on Learn WordPress.
• Theme design teams use it to build themes in the editor.
• Agencies use it to sync client customizations back to version control.
• It's the centerpiece of the Editor + GitHub + Playground workflow being demonstrated at WordCamps and Meetups.
• Independent theme builders like Anders Norén have added it to their workflow.

Protoype

@henriqueiamarino has built a prototype of the modal with five tabs (Color, Dimensions, Typography, Shadows, Templates) on the edit-theme-settings branch. The tabs render and reflect data from the active theme's theme.json, but the Update button is not wired up yet — the prototype is a UI demonstration of the proposed feature shape, not a working save flow.

Try it in Playground: open the prototype (Twenty Twenty-Four + the prototype plugin pre-installed; "Edit Theme Settings" sits under the CBT sidebar with the cog icon).

Background

The existing "Edit Theme Metadata" modal lets users persist style.css / README / screenshot changes from the editor. "Edit Theme Settings" extends that pattern to theme.json — letting theme authors curate the theme's color palette, font families, spacing presets, custom templates, and so on without leaving the Site Editor.

The remaining work is server-side persistence (REST endpoint + service), state lifting in the modal, save UX (loading / notices / refresh), and splitting the feature across reviewable PRs.

Approach

Foundation first, then features:

1. PR 0 — REST endpoint (server-side only). New POST /create-block-theme/v1/theme-settings route + CBT_Theme_Settings_Save service in includes/create-theme/theme-settings-save.php, mirroring the recently-extracted CBT_Theme_Save shape. Validates a partial-theme.json payload, deep-merges into the theme's theme.json, writes via the existing CBT_Theme_JSON_Resolver::write_theme_file_contents(). Includes server-side reification of removedShadowDefaults (the only operational key in the payload). PHPUnit coverage. Reviewable independently; unblocks the JS work.
2. PR 1 — Foundation + Color tab wired (UI side). Modal-level state lifting, postUpdateThemeSettings resolver, save UX, Color tab fully wired end-to-end. Other tabs continue rendering with local state, no save.
3. PRs 2–5 — One tab per PR. Dimensions, Typography, Shadows, Templates each lift their state and wire to the endpoint.

Doing the endpoint as a separate PR means each PR has a clean focus (PHP / framework / per-tab), the contract is concrete and testable before any UI consumes it, and the JS side can iterate on Color without waiting on PHP review.

Sub-issues

• REST endpoint + CBT_Theme_Settings_Save service #837 — REST endpoint + `CBT_Theme_Settings_Save` service (PR 0)
• Foundation + Color tab fully wired #838 — Foundation + Color tab fully wired (PR 1)
• Dimensions tab persistence #839 — Dimensions tab persistence
• Typography tab persistence #840 — Typography tab persistence
• Shadows tab persistence #841 — Shadows tab persistence
• Templates tab persistence #842 — Templates tab persistence

PRs 2–5 (Dimensions / Typography / Shadows / Templates) can be picked up in any order once #838 lands.

Decisions taken (open to discussion)

• Save flow does not wipe user customizations. `CBT_Theme_Save` does (its purpose is promoting user changes into theme files); this flow does not (it edits the theme's offering). Documented assumption: existing user styles may continue to override what's seen in the editor.
• Shadow default-removal reified server-side. The modal sends `removedShadowDefaults: [slug, ...]`; the endpoint expands it into `settings.shadow.defaultPresets: false` + kept defaults re-registered as customs. Centralizes WP-core-defaults knowledge in PHP.
• State lifted to modal level, prop-drilled. Skip context/entity-store options for v1.

Out of scope (potential follow-ups)

• WP-CLI command for theme settings (parallels [Tracking] WP-CLI support: phased implementation #828)
• Documentation in readme.txt (lands with PR 1 when feature becomes user-visible)
• Surgical "wipe only the slices the payload touched" if blanket-don't-wipe causes UX confusion
• Concurrent-edit handling (modal open while theme.json edited externally)

References

• Prototype branch: https://github.com/henriqueiamarino/create-block-theme/tree/edit-theme-settings
• Existing pattern mirrored: `rest_update_theme` + `postUpdateThemeMetadata` resolver
• Service-class pattern mirrored: `CBT_Theme_Save` (extracted in Refactor: Extract CBT_Theme_Save service from rest_save_theme #833)

Open to discussion on scope, sequencing, and the open decisions above before any PRs are opened.

[bph]

An early video to see the tabbed modal to edit Theme Settings. All feedback is welcome! Kudos to @henriqueiamarino

Screen.Recording.2026-05-06.at.14.40.54.mov