WP Theme JSON Editor

A Visual Studio Code extension that provides a form-driven visual editor for WordPress theme.json files. Edit colors, typography, spacing, and more without touching raw JSON.

Features

• Schema-driven UI — Fields are generated from the official WordPress JSON Schema, so the editor stays current with every WP release.
• Global search — Search all properties across all sections from the sidebar. Results show breadcrumb paths for quick navigation.
• Breadcrumb navigation — Clickable breadcrumb trail at the top of each panel showing the current location in the schema tree.
• Section navigation — Sidebar with sub-section drill-down for Settings, Styles, Custom Templates, Template Parts, and Patterns.
• CSS variable autocomplete — Text inputs and CSS editors suggest --wp--preset--* and --wp--custom--* variables derived from the current theme.json data. Triggers on var(-- or --wp.
• CSS variable name preview — Preset items (palette, gradients, font sizes, shadows, etc.) display their generated CSS variable name below each entry.
• Keyboard shortcuts — Cmd+S / Ctrl+S saves while the editor panel is focused. Cmd+Shift+T / Ctrl+Shift+T opens the editor on a theme.json or styles/*.json file.
• Color picker — Native color input for palette entries, duotone colors, and any color-related property.
• CSS editor — CodeMirror 6 with syntax highlighting for CSS and JSON fields, plus CSS variable autocomplete. CSS is minified on save and prettified on load. Inline lint errors for JSON syntax issues.
• Array management — Add, edit, remove, and drag-to-reorder items in palettes, font families, spacing scales, and more. Context-aware labels ("Palette 1", "Font Family 1").
• Spacing units — Toggleable chip selector for CSS units supported by the WordPress block editor (px, em, rem, %, vw, vh, and viewport variants).
• Block-level overrides — Accordion-based block editor with search. Core blocks render the full per-block schema; custom blocks get a JSON editor.
• Style variations — Free-form variation editor for styles.variations with the full styles schema per variation.
• Variation scaffolding — The New Block Style Variation command creates a styles/<slug>.json partial from a title and a comma-separated block list, reusing the theme's own $schema and version. An empty block list scaffolds a global variation.
• Variations overview — Open a theme's theme.json and the Variations section lists every styles/*.json file in that theme, with the blocks each one registers on. Click any entry to open it.
• Variation metadata — Style variation files (styles/*.json, or any document declaring title/slug/description/blockTypes) open on a Variation section for those root keys. blockTypes is a block picker — pick the core blocks the variation registers on, or type a custom block name.
• Custom variables — Nested accordion editor for settings.custom with inline rename, live CSS custom property preview (--wp--custom--...) for leaf values, and add/remove for groups and values.
• Elements editor — Collapsible accordion for styles.elements (button, link, headings, caption, cite) with "configured" indicator.
• Validation — Required fields marked with *, inline error messages, and full JSON Schema validation via ajv (500ms debounce).
• Experimental property toggle — Show or hide experimental and undocumented properties found via the core-scan snapshot.
• Conflict detection — If the file changes on disk while you have unsaved edits, a banner lets you reload or keep your changes.
• Empty state handling — Sections not yet in your theme.json show an "Add section" button.
• Description formatting — Schema descriptions render with bullet lists, inline code, and proper line breaks.
• VSCode theme integration — The UI uses VSCode CSS variables, so it respects your color theme (light, dark, high contrast).
• Accessibility — ARIA tree roles on navigation, aria-expanded on accordions, aria-pressed on unit toggles, role="alert" on validation errors and lint messages.

Getting Started

From the Marketplace

Install "WP Theme JSON Editor" from the VS Code Marketplace, then:

1. Open a project containing a theme.json file, or a style variation under the theme's styles/ folder (e.g. styles/dark.json).
2. Right-click the file in the Explorer → Open in WP Theme JSON Editor.
3. Or press Cmd+Shift+T (Mac) / Ctrl+Shift+T (Windows/Linux) while the file is active.

Trying it locally

The examples/ folder holds sample themes covering every editor surface — a minimal theme.json, a full one, and a styles/ directory with block style variations, a global variation, a nested variation, slug/file-name drift, and a deliberately malformed file. Press F5 to launch the Extension Development Host with that folder as its workspace. See examples/README.md for what each file exercises.

From Source

git clone https://github.com/s3rgiosan/vscode-wp-theme-json-editor.git
cd vscode-wp-theme-json-editor

# Install dependencies
npm install

# Build
npm run build

# Launch in Extension Development Host
# Press F5 in VSCode

Commands

Settings

Editing theme JSON in other locations

By default the editor opens theme.json and style variations under styles/. To open theme JSON kept elsewhere, add patterns to wpThemeJsonEditor.includePatterns:

"wpThemeJsonEditor.includePatterns": [
  "**/theme.json",
  "**/styles/**/*.json",
  "**/src/theme-json/**/*.json"
]

Partial files don't need to be a complete theme.json — any JSON object is accepted, and validation only flags fields that are present.

Note: Until you set includePatterns, the Explorer right-click menu appears only for theme.json and files under styles/. Once you've defined your own patterns, the menu appears on every .json file; choosing one that doesn't match your patterns shows a warning instead of opening. The Command Palette (WP Theme JSON: Open…) and the Cmd+Shift+T / Ctrl+Shift+T shortcut always honor your patterns.

Development

# Install dependencies
npm install

# Watch both extension and webview simultaneously
npm run dev

# Type-check
npm run lint                # Host type-check (tsc --noEmit)
cd webview && npm run lint  # Webview type-check

# Run tests
npm test                    # Host tests (SchemaResolver, SchemaMerger)
cd webview && npm test      # Webview tests (utilities, validation, CSS, autocomplete)

# Build for packaging
npm run build               # Compiles host (tsc) then webview (vite build)

# Package as .vsix
npm run package             # or: npx vsce package

# Regenerate core-scan snapshot (maintainers only)
npx tsx scripts/scan-core.ts

CI/CD

• CI — Runs on every push and pull request. Type-checks both projects, runs all tests, and builds.
• Release — Triggered by pushing a version tag. Runs CI checks, packages the extension, publishes to the VS Code Marketplace and Open VSX Registry, creates a GitHub Release with the .vsix and the shared UI package tarball attached, and notifies the WP plugin so it opens a PR updating to the new UI package.
• Definitions refresh — Runs weekly (Monday 06:00 UTC) and on manual dispatch. Scans the trunk of both WordPress core and the Gutenberg plugin via the GitHub API for supported and experimental theme.json properties, records the latest WordPress release as the snapshot version, and opens a PR if the snapshot changes.

Releasing

# 1. Update version in package.json (root and webview)
# 2. Commit
git commit -am "chore: bump version to X.Y.Z"
# 3. Tag
git tag X.Y.Z
# 4. Push
git push && git push --tags
# The release workflow handles packaging and publishing.

Changelog

See CHANGELOG.md for a list of changes in each release.

License

GPL-3.0 -- see LICENSE for details.