Sage or a custom theme? Which one do you use?

Both, and the hosting platform decides. WordPress VIP constrains what a theme may do at runtime, so there we build a classic PHP theme with logic split across inc, template-parts and classes rather than collecting in functions.php. On Kinsta, Ymir or a Trellis-provisioned DigitalOcean host we use the Roots stack: WordPress versioned by Composer, Acorn, Blade templates, and Vite with Tailwind for assets. This site runs that second setup. We make the call in the first week, because it is not reversible without rewriting the templates.

How is this different from your block system?

Theme setup is the ground the block system stands on. It fixes the hosting target, the build pipeline, the token layer and the package boundaries. The block system is the part editors actually touch. The two are built to fit. Each of the 48 block types has exactly one PHP handler class and one Blade template, both inside the structure theme setup defines. Change the foundation afterwards and every block moves with it. The editorial side is covered on the 40Q Atomic Block System page.

Can we keep the theme we already have?

Sometimes. We look at three things: whether the build is reproducible from a lockfile, whether presentation and logic are separated, and whether the editor has guardrails or an open canvas. If a theme fails all three, making it maintainable usually costs more than a clean foundation and still inherits the original constraints. If it fails one, we fix that one. We tell you which case you are in before you commit. Asset organization and loading strategy are part of the same decision, which is why this runs alongside performance work rather than after it.

What do you need from us before setup starts?

Five things, and the first one blocks the rest: The hosting target, confirmed. VIP, Kinsta, Ymir and DigitalOcean lead to different builds. A repository we can work in, with your CI if you already run it. Agreement from your engineering team on the toolchain, since they will maintain it. Brand tokens or a design manual, if you want the visual layer wired in from the start. A named technical owner who can approve architectural calls. None of this requires a finished design. Theme setup is deliberately decoupled from the visual outcome, so it can start before design is signed off.

What do we receive at handoff?

The theme structured to the conventions above, with every dependency declared and locked. A build that runs with one command and produces the same output on every machine. Editor configuration already constrained to your tokens. A README covering naming conventions for views, blocks and functions. The standard we hold ourselves to: a developer who has never seen the project can clone it, build it and find where a change belongs without asking anyone.

Theme Setup

Enterprise WordPress theme architecture that holds up at year three

Q: Why do you lock the color palette and font sizes in the editor?

Because an open color picker is a brand system with no enforcement. Every hex value typed by hand is a value nobody approved, and nobody can change it later without finding it first. Design tokens are defined once in CSS and compiled into the editor at build time. From there: The WordPress default palette, default gradients, default duotones and default font sizes are switched off. Custom color, gradient, duotone and font size inputs are switched off alongside them. What remains on this site is 96 approved colors and 13 type sizes. Editors keep real choice. What they lose is the ability to invent a value.

Hosting target, build pipeline, editor guardrails, package boundaries, local environment. Five decisions taken in the first week, none visible at launch, all still setting the cost of every change three years later.

Home
Capabilities
Theme Setup

Foundation decisions

Five decisions that are cheap now and expensive later

Theme setup is not installing a theme. It is the set of structural calls that decide whether the platform is still maintainable years after launch.

The hosting target decides the theme

WordPress VIP does not permit the same build as Kinsta, Ymir or a Trellis-provisioned DigitalOcean host. On VIP we ship a classic PHP theme with logic split across inc, template-parts and classes. Everywhere else we run the Roots stack: WordPress versioned by Composer, Acorn, Blade. Decide it late and you write the templates twice.

A build pipeline that still runs in three years

Every dependency is declared and locked, so the build is reproducible rather than reconstructed from memory. This site runs Vite and Tailwind CSS v4, PHP floored at 8.3, and WordPress core managed as a Composer package. Upgrading becomes a reviewed diff, not an operation nobody wants to own.

Editorial guardrails compiled into theme.json

Design tokens defined once in CSS compile into the WordPress editor at build time. On this site that yields 96 approved colors and 13 type sizes, with the WordPress default palette, default gradients, default font sizes and every free-text override switched off.

Package boundaries instead of a growing functions.php

Anything that is not presentation lives in its own Composer package, developed in-repo through path repositories and symlinked into vendor. This codebase carries six, from the AI hub to the SEO assistant and the MCP abilities. Each can be versioned, tested and removed without touching a template.

A local environment that mirrors staging

The local setup is provisioned against the hosting target rather than whatever each developer already had installed: Docker, Herd or Trellis, chosen by where the site will actually run. The rule is that what works locally works the same way on staging. A setup that cannot promise that turns every deploy into a test.

Reference implementation

The reference implementation is this website

These are not client results. They describe the codebase behind 40q.agency as of August 2026 and will move as it does. A foundation claim you cannot inspect is worth very little.

48

Block types, each with exactly one PHP handler class and one Blade template. One to one, no exceptions

96 and 13

Approved colors and type sizes generated into the editor from the token file, with WordPress defaults and free-text overrides off

13 and 5

Section background options and vertical padding steps offered to editors. Layout is a menu, not a CSS field

What it buys you

What the foundation is worth once you stop looking at it

The point of this work is not elegance. It is what stays cheap after launch, when nobody is watching the architecture.

Onboarding measured in days

Conventions are written down and then enforced by structure. Block names, template locations and attribute shapes follow one pattern, so a new developer learns one convention and applies it 48 times instead of learning 48 exceptions.

Design changes that stay out of the code

Colors, type scale and spacing live in one token file that compiles into both the frontend and the editor. A rebrand becomes an edit to tokens instead of a hunt for hardcoded hex values across templates.

Upgrades you can actually review

Core, plugins and internal packages are declared in composer.json and pinned by a lockfile. Every upgrade arrives as a diff someone can read and a build someone can run, which keeps a platform patchable long after launch.

What engineering leads ask us before a build starts

The questions that decide whether a foundation is worth paying for.

Related insights

Keep reading on architecture and maintainability

Setup choices, custom themes, and the cost of skipping maintainability.

A man in a blue checkered shirt stands at a desk in a modern office, working on a computer. Papers, a coffee mug, and a snack bar are on the desk, with large windows showing a cityscape in the background.

Feb 5, 2026

WordPress

Have an engineer review your theme architecture

Send us the repository or a staging URL. We will look at how the theme is structured, whether the build is reproducible and where the editor can go off-brand, then send you what we find.

Request an architecture review Talk to a WordPress engineer