Documentation

AI Best Practices

How to brief the AI so it produces editable, on-brand, accessible pages instead of a wall of hardcoded markup.

Set the site up before you ask for anything

The AI reads your site before it designs. Give it something to read:

Design tokens — Settings → Design Tokens. Colours, fonts, spacing, radius.
Business info — phone, email, address, socials.
Global sections — header and footer.

Skip this and it will invent a palette, and every page will invent a different one.

Design tokens: set them once and every page follows.

Brief it like a designer, not like a search box

Weak: "make a homepage"

Better: "Homepage for a family dental practice in Portland. Warm and calm, not clinical. Sections: hero with a booking CTA, three services, meet-the-dentist with a photo, two patient testimonials, insurance logos, contact with the CF7 form. Keep every headline and body paragraph editable."

Say what sections you want, what the page is for, and who edits it afterwards.

Rules the AI is given

Content

Benefit-driven headlines, never "Welcome to our site".
Action-oriented CTAs — "Start Free Trial", "Get Your Quote" — never "Submit" or "Click Here".
Use social proof: testimonials, stats, logos, trust badges.
Break up text with subheadings and bullets.
One clear purpose per section.

SEO

Exactly one <h1> per page, used for the main headline.
Descriptive, keyword-bearing <h2>/<h3> section headings.
Real structured content — lists and paragraphs, not divs full of text.
Meaningful alt text on every image.
Descriptive anchor text on internal links.
Important content above the fold.

Accessibility

WCAG AA contrast: 4.5:1 body, 3:1 large text.
Everything interactive reachable by keyboard, with a visible focus indicator.
aria-label on icon-only buttons.
Labels associated with form inputs.
Never convey information by colour alone.
A skip-to-content link on long pages.

Performance

Shallow DOM — minimise nested divs.
CSS for visual effects (gradients, shadows, shapes), not images.
No inline styles; use scoped_css.
Low CSS specificity, class selectors.
Images are optimized automatically at render time — srcset, sizes, width, height, loading and fetchpriority are injected for you. Don't hand-roll them.

Workflow

For complex components — timelines, tabs, pricing tables, bento grids, accordions, carousels — call get_component_templates first and start from the proven skeleton. Don't build them from scratch.
For CSS fixes, use css_overrides in patch_section rather than resending the whole scoped_css. It saves 60–80% of the tokens on iterative edits.
patch_section for surgical changes (a headline, one CSS rule). replace_section only when the whole structure changes.

The habit that matters most: keep it editable

Every headline and paragraph a human might ever change belongs in a content field, not baked into template_html. The plugin warns the AI when a section is too hardcoded, but a clear brief prevents it in the first place. Ask for a content_fields_schema too — that's what turns Content Mode into a properly labelled form.

Working alongside the AI safely

Edit locks — MCP writes honour WordPress post locks. If someone has the page open you get a 409 post_locked rather than a silent overwrite. Only force it when you know what you're overwriting.
Section versions — if_version gives optimistic locking at section level, so two editors on the same page can't clobber each other.
Attribution — pass an actor when your client knows who the real human is. It appears in the revision history above the token owner. Don't invent one.
Comments — the AI can flag an assumption for a human to confirm instead of guessing. Use them; that's what the channel is for.

Iterating

Preview after each meaningful change (get_preview_url), and run validate_page — it catches icon-name typos, broken image URLs and malformed CSS. Validation returns warnings, not errors; pages save either way.

Bust the render cache after direct database changes with bust_cache — and remember page caches and CDNs must be purged separately.