The first year was chaos. Then we wrote it down.

Ten projects in, our team was building the same agency’s sites in three different ways.

One developer was using Elementor Forms because it was already in the layout. Another was switching them out for Gravity Forms because that was the agency’s standard. A third was leaving the existing forms alone, on the grounds that “if it works, don’t touch it.” Three different builds. Three different post-launch experiences for the agency. Three different review threads for the same kind of question.

That was the cleanest of the disagreements.

There was also the question of which CSS units to use. Whether to leave the WordPress sample page in or delete it on day one. Whether headings should be Title Case (Personal Injury) or sentence case (Personal injury). Whether the homepage’s hero needed a custom breakpoint at 1280 pixels, or whether the default Elementor breakpoints were fine. Whether to install a caching plugin on WP Engine. (WP Engine has caching built in. The plugin doubles it. That fact was not common knowledge across our team in the first six months.)

Every one of these had a right answer, and every one had three live versions of the wrong answer running on different sites at the same time.

The agency knew. They told us. Politely, repeatedly, and across multiple project reviews. The conversation was always the same shape: this site uses X, but the previous one used Y; can you pick a lane?

We could not pick a lane, because we were not all in the same lane. Each developer had landed on a personal default through a mix of habit, browsing the project’s existing setup, and assumptions about what the agency wanted. None of those defaults aligned. The result was a quality that was technically passable on every individual site and visibly inconsistent across the portfolio.

That was the pain. The cure was not training. The cure was writing it down.

What “writing it down” actually means

The temptation, when a team’s outputs are inconsistent, is to schedule a meeting. Get everyone in a room, walk through the conventions, agree on the standards, move on. We tried that. It works for one week. By the second week, half of what was agreed has dissolved back into “well, on this project I thought…” and the other half has fragmented into competing interpretations.

What actually shifted things was the slow accumulation of a written guideline — one rule at a time, each rule attached to a real conflict that had cost real time. The first version had five rules. The current version has more than thirty. Almost every rule traces back to a specific moment of friction we wanted to never have again.

The current internal version of the document opens like this:

# xpro · WordPress build conventions
# v17 — 2026-04-30

stack:
  page-builder:  elementor-pro-only
  forms:         gravity-forms          # not Elementor Forms
  seo:           rank-math
  caching:       none                   # WP Engine has built-in cache
  hosting:       wp-engine-standard     # agency-supplied environment

content:
  heading-case:  title-case             # "Personal Injury", not "Personal injury"
  h1-per-page:   1
  units:         px-only                # no vw, no clamp without justification
  breakpoints:   elementor-defaults     # custom breakpoints disabled

phone-numbers:
  format:                  tel:+1XXXXXXXXXX
  always-clickable:        true
  always-include-country:  true

Each line is a settled argument. Most of them took a project to settle.

A few examples, with their hidden histories:

“Use Elementor Pro for all page building. Avoid other builders.”
This rule existed because at one point we had a project where one developer started in Elementor and another, taking it over, switched a page to a different builder because the original layout was, in their words, “easier to redo than fix.” When the agency reviewed the build, they could not understand why two pages had been engineered against two different toolchains. Neither could we, when we tried to debug a regression six months later. The single-builder rule did not exist to enforce taste. It existed because divergent builders make a site impossible to reason about.

“Gravity Forms only. Do not use Elementor Forms.”
Gravity Forms had the agency’s stable email-deliverability setup, the conditional logic the agency relied on, and the tracking integrations that fed into their reporting. Elementor Forms is a perfectly reasonable plugin for a different kind of project. On these projects, mixing the two meant some forms had analytics and some did not, some had spam protection and some did not, and the agency’s review process had to discover this for each new site. The rule wasn’t about the better plugin. It was about not having two answers to the same question.

“WP Engine has built-in caching. Do not install caching plugins.”
This one cost a half-day of debugging on a staging environment that kept serving stale assets after a deploy. The cause was a caching plugin our developer had installed out of habit, sitting on top of WP Engine’s own cache layer. Two caches, racing each other. The fix was to remove the plugin. The rule was to not install it next time.

“Phone numbers must use the tel:+1XXXXXXXXXX format. Always include the country code.”
A phone number rendered as plain text on a page won’t trigger the dial dialog when a visitor taps it on iPhone. A phone number with tel: but no country code may dial a wrong number on a phone that’s roaming. The agency had been getting reports about phones not dialling correctly across the portfolio. The fix was three characters per number. The rule was to write those three characters every time.

“Headings and menu items use Title Case for each word.”
This is the kind of detail that looks petty until you’ve reviewed twenty sites in a week. Half of them use Personal Injury and half use Personal injury. Both are defensible style choices. Neither is defensible together. The agency’s brand sense was unified; the developer outputs were not. The rule wasn’t about which case was better. It was about not making the agency choose this argument every Tuesday.

“Pixel units only. No vw, no clamp unless explicitly required.”
This rule looks like a constraint on creativity. It is not. It is a rule about predictability. A site built with clamp and vw looks beautiful on the developer’s monitor and unpredictable everywhere else. The agency’s reviewers were on a mix of laptops, tablets, and external displays at different scaling settings. A pixel-based layout was the same on all of them. A responsive-units layout was three different layouts. The rule wasn’t about taste in CSS. It was about giving the reviewer the same site we built.

“One <h1> per page. Follow the heading hierarchy.”
This one is supposed to be common knowledge, and yet our first audit of fifteen completed sites found six with two <h1> tags. Why? Because the developer dropped in a hero widget configured as <h1>, then dropped in a section heading also configured as <h1> because it looked correct visually. The browser doesn’t care; the audit report does. The rule wasn’t about SEO theory. It was about not redoing the heading hierarchy on every audit.

“Disable Elementor’s custom breakpoints. Use only the defaults.”
Custom breakpoints look like a feature. They are a tax. Every developer who configures their own breakpoints creates a site that the next developer has to re-learn. Default breakpoints are documented, predictable, and understood by every reviewer. Custom breakpoints are a layer of personalisation that nobody asked for. The rule wasn’t about technical limitation. It was about reducing the surface area of “things you have to figure out before you can edit this site.”

We could keep going. There are rules about which fonts to load through TypeKit and which never to upload manually. Rules about which sitemap entries to include and which to suppress. Rules about how to mark a target="_blank" on outgoing links. Rules about removing the WordPress sample page on day one. Rules about UpdraftPlus during development and never as a permanent backup solution.

None of them are clever. All of them are settled.

What changed when the document existed

Three things happened, all of them within the first quarter after the document went live.

First, the review conversations changed shape. Before the document, every review had a section that began with “let’s talk about how this build differs from the last one.” After the document, that section was gone. The build either followed the rules, or the deviation was visible and could be discussed as a deviation, not as a default. The agency’s reviewers were spending their time on real work — content accuracy, layout polish, brand alignment — not on convention re-litigation.

Second, the onboarding curve for new developers compressed sharply. Before the document, a new developer joined a project, looked at the existing site, asked three or four questions, and made decisions based on inference. Their first build always had at least one or two convention violations because they were inferring from a portfolio that was itself inconsistent. After the document, a new developer could read it in an afternoon and start work the next morning with the conventions internalised. Their first build looked like every other build the team produced. The friction of “introducing a new person to how we work” went from a multi-week process to a one-day read.

Third — and this was the one we did not expect — the agency’s trust shifted. Before the document, every project was a fresh negotiation. The agency’s reviewers carried a low-grade anxiety about what they would find this time. After the document, projects started arriving for review with a baseline they could trust. The reviewers’ time shifted from defensive scanning to focused inspection. Their feedback became more substantive because they were not spending half of it on convention drift. The agency began saying things like “this one came in clean” — a phrase that had not existed in our review history.

The lesson for the agency

If you are a marketing agency that subcontracts WordPress builds — to one shop or to many — the absence of a written guideline is a tax that you are paying every week. You do not see it as a tax. You see it as “the normal cost of working with developers.” It is not normal. It is the cost of letting each developer reinvent the conventions of your portfolio, and then absorbing the resulting inconsistency through your reviewers’ time.

Two practical observations from our side of this:

One. A guideline document does not need to be perfect to start. Five rules, written down and agreed, will save more time in their first month than a fifty-rule document that took six months to draft. Start with the conflicts you have already had. Add a rule each time a new conflict surfaces. Within a year, you will have something serious. Within two, you will wonder how you worked without it.

Two. When evaluating a new development partner, ask if they have such a document — not as a marketing artefact, but as a working internal standard. A partner who can hand you a written guideline they actually use is a partner whose builds will be predictable across projects. A partner who cannot is offering you their first year of chaos as your first year of supervising them. You can choose to absorb that cost — sometimes the partner is worth it. But the cost is real, and you should know you are paying it.

The first year of working without conventions is unavoidable, the first time. The second time is a choice.

We chose to write it down. Most of what we now produce as a studio is downstream of that single decision.