The WP Rig team is thrilled to announce WP Rig v3.5.0 — the largest release since v3.0. This is the release where the framework’s three-paradigm foundation becomes real: design tokens reach version 2, the Site Editor gets a full bake-and-sync round-trip, classic themes get a true-classic guarantee, and WP 7.1’s theme.json v3 and Icon API are supported natively. Here is everything that landed.

Design token system v2 (SPEC-017)

config/tokens.json is now layered — primitives → semantic light/dark → component — with a JSON Schema for editor autocomplete. Dark mode is generated from semantic.*.dark, fixing the long-standing gap where token colors never flipped in dark schemes. Config-driven theme.designTokens.colorBinding (independent vs wp-preset) is paradigm-aware: classic themes never emit --wp--preset-- references. New commands: rig:tokens:setup (v1→v2 upgrade with backups), rig:tokens:import / rig:tokens:export for W3C DTCG / Figma round-trips. Tailwind remains fully optional — nothing is added unless theme.designTokens.emit.tailwind is enabled. A WCAG contrast gate (currently at warn) audits your palette as you work.

npm run rig:tokens:setup

npm run rig:tokens:setup

Site Editor bake & sync (rig:bake)

Site Editor work — custom templates, template parts, patterns, Global Styles, Font Library fonts — lives in the database, not in git. v3.5.0 ships rig:bake, a Node port of bacoords/wp-theme-control, that moves that work into your theme’s files so it can be diffed, reviewed, and committed. Every write is recorded in a manifest with sha256 checksums; cleanup deletes only records whose files still match. Runtime URLs in baked patterns are patternized to patterns/hidden-*.php. Paradigm-gated to universal and block-based themes — classic gets a graceful refusal.

git status                       # must be clean — a bake is reviewed as a diff
npm run rig:bake:plan            # read-only inventory + collisions
npm run rig:bake                 # writes files; does NOT clean the DB
npm run lint:patterns && npm run lint:blocks
git add -p && git commit         # review the diff
npm run rig:bake:clean -- .wp-theme-control/runs/<run>/manifest.tsv

git status                       # must be clean — a bake is reviewed as a diff
npm run rig:bake:plan            # read-only inventory + collisions
npm run rig:bake                 # writes files; does NOT clean the DB
npm run lint:patterns && npm run lint:blocks
git add -p && git commit         # review the diff
npm run rig:bake:clean -- .wp-theme-control/runs/<run>/manifest.tsv

The true-classic guarantee

Choosing classic during rig-init now enforces itself. A stale config.local.json override no longer silently wins the merge chain — init strips theme.themeType and theme.enableBlocks on every run so your interactive choice is authoritative. Selecting classic also moves leftover templates/ and parts/ FSE artifacts into a timestamped .rig-backup/ folder (never deleted) — a stray templates/index.html made WordPress core detect a block theme and surface the Site Editor regardless of config. theme.json is intentionally kept: it is hybrid-legitimate and never triggers the Site Editor.

Navigation that looks right out of the box

The starter template no longer ships a bare <!-- wp:navigation /--> — the markup that caused WordPress to lazily create an unstyled fallback nav post. The starter now ships inline wp:home-link + wp:page-list inner blocks with a styled baseline in _blocks-based.css, so the default state renders like real navigation immediately. A new opt-in npm run seed:navigation seeds an editable wprig-primary-nav post for Site Editor workflows.

npm run seed:navigation

npm run seed:navigation

WordPress 7.1 alignment

• theme.json v3: added settings.viewport (mobile 480px / tablet 782px), explicit settings.blockVisibility, and token-derived layout sizes. Pseudo-state styling (hover/focus/active) is enabled.
• Viewport-driven breakpoints: all 7 @custom-media aliases derive from settings.viewport — one breakpoint scale for every paradigm, and the editor preview and frontend finally agree.
• Block Visibility alignment: the responsive nav shares the same scale as core’s wp-block-hidden-* classes — hamburger hides at 481px, nav collapses at 782px. Guidance documented to avoid double-toggling.
• Native Icon API: every SVG in assets/icons/ registers with wp_register_icon() in every paradigm — classic included. Incompatible icons are skipped with a log note instead of registering blank.

The paradigm foundation

The single-source-of-truth paradigm system ships complete: config/paradigms.json, JS/PHP helpers, generic component gating via Paradigm_Component_Trait and PARADIGM constants, and fail-fast validation with jest + PHPUnit coverage. Block features are strictly gated out of the classic core. Changing your theme type is a one-line config edit — every gate follows automatically.

Block-based CSS surface & pattern registry

A new assets/css/src/_blocks-based.css (gated to universal/block-based) ships a starter baseline for FSE core blocks: Navigation desktop + mobile-toggle alignment, theme part spacing, and Query Loop defaults — it never loads in classic themes. The new inc/Block_Patterns component provides config-seeded, filterable pattern categories and registers installed components’ bundled patterns. Companion tooling: rig:pattern scaffolding with i18n-aware headers and a lint:patterns validator now part of ai:check.

Framework vs theme version separation

WP Rig’s own version now lives in config/framework.json and is stripped by childify — a built theme never carries it. The theme version lives in config and is stamped into style.css and readme.txt at bundle time, fixing a leak where the framework version could reach production themes.

npm run rig version:framework 3.5.0   # bump framework version
npm run rig version 1.0.0             # bump theme version
npm run rig version                   # print both

npm run rig version:framework 3.5.0   # bump framework version
npm run rig version 1.0.0             # bump theme version
npm run rig version                   # print both

User-styles overlay (SPEC-016)

Baked Global Styles and font activations land in git-tracked config/user-styles.json — not theme.json. The token pipeline merges the overlay last (deep-merge objects, arrays replace wholesale, custom font definitions win on duplicate slugs); SSOT keys never merge. rig:tokens regeneration is deterministic after a bake, and the PHP runtime is overlay-blind with a PHPUnit parity guard.

Upgrading

Update your WP Rig checkout and re-run init:

npm run rig-init

npm run rig-init

Coming from token-system v1? Run rig:tokens:setup — it upgrades config/tokens.json to the layered v2 format with a collapse-aware legacy-name codemod and backups. Full release notes are in the changelog.

Thanks

This release was driven by @robruiz with the WP Rig maintainer team. Found a bug? Open an issue on GitHub — and if WP Rig saves you time, consider sponsoring the project.

The WP Rig team is thrilled to announce the official release of WP Rig v3.4.2!

WP Rig has always been the premier developer-first starter theme and build system for WordPress. With v3.4.2, we’re taking performance, layout sophistication, and theme compliance to the next level. This release introduces game-changing server-side rendering speeds, cutting-edge CSS layouts, and powerful local auditing tools designed to get your theme into the official WordPress.org Directory on day one.

Here is a look at what makes WP Rig v3.4.2 our most exciting release yet.

1. Blazing-Fast Server Speeds with Block Manifests (Issue #936)

Bespoke block-based WordPress themes often suffer from a hidden bottleneck: runtime filesystem scanning. On every page load, WordPress has to scan directories, locate individual block.json files, and parse them with CPU-intensive JSON decoding.

WP Rig v3.4.2 completely eliminates this runtime overhead by integrating with modern WordPress 6.7 and 6.8 Block Metadata Collections.

• Pre-Compiled Manifests: During npm run build, WP Rig compiles all your block configurations into a single, high-performance PHP file (assets/blocks/blocks-manifest.php).
• In-Memory Performance: Because the manifest is a native PHP array, it caches directly in your server’s OPcache. WordPress reads your entire block library directly from memory almost instantly—completely bypassing the filesystem.
• Resilient Fallback Pipeline: A smart 3-tier loader utilizes modern WordPress 6.8+ batch loading, falls back to WordPress 6.7 in-memory collections, and gracefully drops back to traditional scanning on older WordPress versions or local dev setups.

2. Viewport-Aware, Zero-Flicker Submenus (Issue #845)

We have resolved the long-standing issue of dropdown navigation menus overflowing the edge of the viewport using an ultra-modern hybrid positioning system:

• CSS Anchor Positioning: For modern browsers, WP Rig uses native CSS Anchor Positioning to dynamically align submenus relative to their parents. This delivers absolute zero layout flicker and zero JavaScript execution.
• Optimized TypeScript Fallback: For older browsers, a highly optimized Intersection Observer script seamlessly detects potential overflows and flips submenu alignment without taxing browser paint cycles.

3. Demystifying the Theme Directory: Local Submission Auditing

Passing the official WordPress.org Theme Directory review is notoriously challenging. To take the guesswork out of compliance, WP Rig v3.4.2 introduces an automated local submission readiness platform!

We have codified strict theme review guidelines directly into an executable suite of commands:

• npm run audit:theme-review: Instantly checks your active theme for metadata accuracy, banned files, illegal plugin-territory code (like inline block registration), translation errors, and security issues.
• npm run bundle:wporg: Compiles a clean, production-ready .zip archive—stripping all source files (src/, .ai/, etc.)—and automatically audits the final zip to ensure it is 100% submission-ready.
• wp rig review-setup: Integrates with WP-CLI to install the official Theme Check and Theme Sniffer plugins locally, configure developer runtime logs, and import the official Theme Unit Test data for comprehensive visual QA.

4. Developer Quality of Life & Polish

We’ve also packed this release with features to make your daily coding workflow faster and more enjoyable:

• Locked Mobile Menus: Hold Alt (or Option on macOS) while toggling the mobile menu in block-based dev to lock it open. It will stay pinned to the screen even when browser Developer Tools steal focus.
• Single Source of Truth Breakpoints (Issue #925): Define --mobile-breakpoint as a CSS Custom Property. It is dynamically parsed and shared by both CSS and TypeScript, completely removing magic numbers.
• Variable Font Support: Refactored font handling natively supports variable fonts and optimizes Google Fonts query generation to ensure faster rendering.
• Modern Workspace Alignment: Unified Prettier, ESLint, and EditorConfig rules; block schema validation; PHP-only block scaffolding for WordPress 7.0; and the addition of ergebnis/agent-detector to help AI agents adapt to your local container environments.

Try WP Rig v3.4.2 Today!

Experience the ultimate blend of modern developer tooling, server-side speed, and bulletproof compliance. Getting started takes less than a minute:

# Clone the repository
git clone https://github.com/wprig/wprig.git my-theme
cd my-theme
# Install dependencies and start the modern dev server
bun run rig-init:bun
bun start

# Clone the repository
git clone https://github.com/wprig/wprig.git my-theme
cd my-theme

# Install dependencies and start the modern dev server
bun run rig-init:bun
bun start

Try WP Rig v3.4.2 today, and watch your build times, server-side rendering speeds, and theme audit errors vanish! 🚀

Love WP Rig? Support the project by starring us on GitHub and sharing this release with your dev networks!

⚡ Executive Summary: The Evolution of WP Rig

Following our major shift to a modern stack powered by Bun, TypeScript, and Lightning CSS (completely removing Gulp for 10x faster build cycles) , and the introduction of our v3.3 Agentic foundation , WP Rig v3.4 officially moves us from a static starter theme to a composable development platform.

WP Rig v3.4 is one of our most foundational releases yet. If you build custom WordPress themes professionally, this release is engineered to make your day-to-day workflow faster, safer, and remarkably easy to maintain.

This version zeros in on three pillars that matter to modern engineering teams:

• Performance as a Built-In System: Out-of-the-box optimization, not an afterthought.
• The “A La Carte” Component Lifecycle: Reusable, shareable features powered by the new Open Component Registry (OCR).
• Automation-Hardened Tooling: Enterprise-grade security and reliability for CI/CD and AI-assisted workflows.

The Strategic Objectives Behind v3.4

1. Performance as Core Architecture

WP Rig has always been a developer’s secret weapon for speed. With v3.4, performance moves directly into the core runtime via manifest-driven loading, smarter caching behavior, and cutting-edge font delivery techniques.

2. The Open Component Registry (OCR) Foundation

The headline feature of v3.4 is the Open Component Registry. Instead of regenerating common theme features or wrestling with monolithic starter themes, developers can now download or contribute “bolt-on” features a la carte.

Crucially, this supercharges AI-assisted development. Because OCR components contain predictable structural data, AI agents can effortlessly discover, pull in, and compose complex themes using proven building blocks.

3. Secure Tooling for Teams and AI Agents

As engineering workflows increasingly rely on automation, our CLI tools require stronger defaults. Building on the AI groundwork laid out in v3.3 (including MCP-oriented docs and agent setup scripting), v3.4 hardens command execution, sanitizes external data, and provides non-interactive flags designed specifically for AI-driven pipelines.

Detailed Breakdown: What’s New in v3.4

🚀 Performance & Asset Delivery Improvements

• Cookie-Based Critical Asset Strategy: Delivers the absolute best of both worlds. The first page view inlines critical CSS above the fold, while subsequent views automatically serve cached external files.
• Transient-Based Caching: Added deep caching for configuration retrieval and asset loading logic within inc/Theme.php.
• FOUT Elimination: Reduced font flashing by defaulting localized fonts to font-display: block alongside automated preloading.
• Manifest-Driven Navigation: Extended the Asset_Provider system to handle custom loading strategies, automatically delaying non-critical interaction JavaScript.

🧩 Open Component Registry (OCR) Built for Humans & Agents

• Automated Discovery: Refactored core theme files to instantly scan, discover, and register independent components sitting in the inc/ directory.
• Registry Scaffolding: New component generation automatically creates the necessary manifest.json, SPEC.md, and SKILL.md files.
• Zero-PAT Workflows: Integrated public GitHub repository registry workflows so common fetches no longer require a Personal Access Token.
• AI-Readable Knowledge Layer: The inclusion of SPEC.md and SKILL.md ensures that AI coding partners (like Claude, Copilot, or ChatGPT) understand exactly how to implement and wire up the component without “hallucinations”.

The new component registry is completely open-source. If you are interested in contributed a new component, you can find the repo here.

🛠 CLI Developer Experience (DX) Upgrades

Manage your entire workspace using the brand new npm run rig:* command suite:

• The Automation Flag: Added a global --yes flag across all commands to unlock seamless, non-interactive CI/CD runs and flawless execution by AI marketing and development agents.

🔒 Security & Integrity Hardening

• Shell-Injection Mitigation: Refactored CLI install execution to utilize spawnSync argument arrays.
• Path Traversal Protection: The CLI now strictly sanitizes incoming manifest data including slugs, filenames, and asset paths.
• Built-in Security Scanning: Integrated security validation directly into rig:test-component and provided OWASP-oriented GitHub Action templates.

How v3.4 Impacts Your Workflow

If you build client sites professionally…

You get perfect baseline performance out of the box—no heavy optimization plugins required. Your builds remain instantaneous thanks to our Bun and Lightning CSS core , and your initial loading states are highly optimized via native critical CSS generation.

If you are scaling with AI and Automation…

The combination of v3.3 agentic readability and v3.4 component structure means your AI pairing sessions will be highly efficient. You can prompt an agent to build a custom feature, and it will output an engineered, registry-ready component that integrates perfectly without breaking your site architecture.

Getting Started with v3.4

Ready to experience the composable era? Upgrade your repository and run through this quick checklist to benchmark your new workflow:

1. Audit your components: npm run rig:list
2. Test for registry compliance: npm run rig:test-component <your-component-slug>
3. Check your performance scores: npm run test:perf

Want to dive deeper into the technical architecture? Check out our updated, AI-optimized documentation platform over at wprig.io (now featuring an llms.txt file mapping for your custom AI workflows!).

The Paradigm Shift Just Got Real.

WordPress theme development is at a crossroads. For years, we’ve iterated, optimized, and pushed the boundaries of what a theme framework can do. We built WP Rig to be the definitive rig—the strongest, most modern, and most performant skeleton for theme builders.

But a new force has entered the chat.

Artificial Intelligence. Coding agents. Builders that work alongside us, suggesting, writing, and debugging code at inhuman speeds.

The community has been asking: “How does my stack adapt to this new reality?”

We’ve been listening. Today, we’re doing more than just answering. We’re leading.

We are excited to announce the release of WP Rig v3.3.

This isn’t just an incremental update. This is a complete, frictionless merger between the industry’s most advanced WordPress framework and the most powerful tool in the modern developer’s toolkit: AI.

The Milestone: Total Agent Empowerment, Right Out of the Box

The headline of v3.3 is simple: You are now completely empowered right out of the box to use your coding agent of choice to build out themes with WP Rig.

We’ve removed the friction. Whether you’re partnering with GitHub Copilot, Claude, OpenAI’s GPT-4, or any specialized coding assistant, v3.3 of WP Rig has been optimized to “understand” and interface with these agents.

Your favorite agent can now navigate WP Rig’s modern build process, structure, and PHP/JS architecture with unprecedented clarity. This sets a new precedence in the WordPress community, making WP Rig the first framework of its kind to explicitly prioritize this new development workflow.

Beyond AI: A Look Inside the Most Modern Framework

WP Rig v3.3 isn’t just a partner for your AI; it remains, by design, the most modern and advanced WordPress theme framework available. We have refined every internal gear:

• Optimized Modern Build Process: The legendary Gulp-based build process is leaner and more robust. We’ve shaved crucial seconds off compilation and optimization times.
• Performance First: v3.3 features updated strategies for asset loading, image compression, and critical CSS generation, ensuring your themes score higher than ever on performance metrics.
• A “Developer-First” Standard: The structure of WP Rig is a testament to best practices. We prioritize modularity, clear file structure, and adherence to the strictest WP coding standards. Your code (and your AI’s code) is built on a foundation that doesn’t just work—it shines.

How to Get Started with v3.3

We know you want to see this in action. The update is live and waiting for you.

1. Read the Full Release Notes: Dive into the technical details and see the change log on GitHub.
2. Download WP Rig v3.3: Use it as the starter for your next project.
3. Fire Up Your Coding Agent: Point your agent at the new framework and experience the synergy.

Check out the Release Notes & Download v3.3 Now!

The Vision Ahead

This release is a commitment. We believe that the future of theme development will be defined by synergy—the combination of human intuition, powerful frameworks like WP Rig, and intelligent AI assistance. WP Rig v3.3 is our first major step into that future.

Many thanks to everyone who has embraced WP Rig. Your feedback, contributions, and belief in this project are what make these milestones possible.

Let’s build the next generation of the web, together.

TL;DR

• WP Rig now builds 10X faster on average
  • esbuild, Lightning CSS, and Gulp 5
• Linting and PHPCS checks moved to more specific scripts
• Now supports Typescript and JSX natively
• Comes with a React-based Settings page configurable with simple JSON file
• Min. PHP version bumped to 8. PHP Type checking added.

Backstory

For the last year, I have been getting deeper and deeper into all things JavaScript. Typescript, React, Node – you name it. As someone who already understands plugin and theme development for WordPress quite well, I wanted to look and go beyond. I’ve been maintaining WP Rig for a few years now and I had still yet to fully understand exactly how the build process worked and how to truly control it. My understanding of Node was relatively novice, and as someone who had already learned Angular, React, and Stencil.js, I still felt like there was a lot going on in the JS universe that I was still not well versed on.

On my quest to change this and improve, I found myself wondering if WP Rig was still “modern” and “progressive” by today’s standards. Issues had been annoying me. Why does it build so slow? Why are dependency issues so common? Do we have to constantly be annoyed by Stylelint, ESLint, and PHPCS errors even if we are using it to build a theme that we will never distribute? Can’t we just selectively run these checks outside of the early phases of iteration? Should we really be relying on Gulp and Gulp plugins to do literally everything in the build? Why can’t I write in Typescript? Shouldn’t we be able to build React functionality within the theme? My mind began to open to the possibility of something greater than what I had inherited.

Version 2.0 was released in 2019. That was a 5+ years ago! Disruptions in JavaScript seem to occur almost monthly these days. While I give enormous credit and gratitude to the previous developers that worked on WP Rig, there have been enormous strides in JS-based build tools since then. I realized, it is my responsibility to keep this thing fresh. So here we are, at the end of 2024, and WordPress themes of 2025 demand more. I realized, it was time to tear this thing apart a bit and start rebuilding from the ground up.

Architecture

Gulp: While I had my issues with Gulp, it has proven effective. Updates seemed slow. However, as fate has it, Gulp decided to release a new major version (Gulp 5) earlier this year. So, for now, I decided rewriting the entire framework without Gulp was a monumental task that might prove too much for a single ambitious developer. So, I started by simple upgrading Gulp to the latest version. That’s a start. I decided to continue to rely on it for orchestrating tasks (which is what it is good at) and managing the image optimization.

JavaScript

I wanted to see if I could find a better, faster and more modern foundation for managing the transpiling of our theme assets. After some broad research into various modern JS frameworks, I found myself inspired by tools like Vite, Astro, and Next.js just to name some. This led me to esbuild. I thought to myself, why not give esbuild a shot at transpiling our JS? I wanted Typescript and JSX and esbuild handles both natively. After some promising proof-of-concept attempts, I realized I was onto something.

CSS

While PostCSS was good, I thought to myself, what else is out there? Can we keep all the best things about our current CSS workflow in Rig and improve it? Turns out, we could. I then found Lightning CSS. With a bit of tinkering and filling some gaps with some custom Node scripting, once again – success! With an all new gulpfile.js, simplifying the build altogether, and stripping out now unnecessary packages, WP Rig was now building 10X faster!

Features

I started to have so many ideas about what I wanted out of WP Rig. How could we dramatically improve the theme authoring experience? We need to streamline workflows, maintain simplicity, and allow theme devs to focus on what themes do best – style.

Theme settings

Previous versions of WP Rig supported settings. However, I became obsessed with the idea of a React-based settings framework a few years back when I got into block development. Unfortunately, the Site Editor has yet to introduce a proper API to allow theme devs to build their theme settings into that UX. So, I decided to do the next best thing. WP Rig now has a React component based theme settings page that can be added/removed using our existing component system. There is now an Options component that facilitates this new system. An important consideration here was that I did not want to force theme authors to learn JSX, React, components…it’s too much for many as has been made obvious by the continued hesitation by many (mainly web agencies) to adopt Gutenberg and full site editing. So, I decided to take inspiration from the EZ_Customizer component and allow theme authors to build out their settings fields by managing a simple JSON file. The app reads the JSON file and uses it to build out the settings fields. This initial implementation is fairly simple currently, but it is effective and it is a good foundation to iterate on in future versions with more field types. Furthermore, the settings auto-save via the REST API. It feels good.

Utility Classes

Default styles now come with utility classes for things like CSS Grid and Flexbox. These utility classes will likely grow in the future, but it’s a decent start.

Fonts

All font considerations have been moved to a fonts controller. Although WordPress now has it’s own build-in font manager, we thought theme authors would like a more straight forward way of adding custom fonts to their themes, so, there is now a home for these considerations. We recommend packaging your fonts with your theme for better performance and less reliance on CDNs. This could also be a decent home for icon libraries you might want to package with your theme.

Recent improvements added in 2.3 worth mentioning

• Add Site Editor compatibility (Full Site Editing) to your theme using a single NPM command.
• Improved PHPCS, Stylelint, and ESLint handling and supports latest version of WP Coding Standards.
• Support for later versions of PHP 8.

Try it now!

If you are interested in helping us test V3 before we push this major release please pull the V3 branch from Github and submit issues as you find them. Thanks in advance for your help in this effort. If you have ideas for features you think should be added to WP Rig, please submit your feature requests here and feel free to tag me.

Possible future features

• Possibly replacing Gulp altogether in the distant future for something like Task.
• A WebP conversion process for image processing system.
• A more obvious cache busting system for scripts/styles