---
name: midground
description: Use when building or changing pages on a WordPress site that has Midground Builder – landing pages, product pages, scroll stories with pinned scenes, parallax, text reveals or 3D models – through the site's Midground MCP tools (midground-get-catalog, midground-create-page, midground-update-element, midground-add-effect, midground-publish and the rest).
compatibility: Midground Builder 1.2 or later on WordPress 6.9 or later (the Abilities API), reached through the WordPress MCP Adapter 0.7 or later. Tested with WordPress 7.1 and PHP 8.3.
---

# Midground pages

Midground is a WordPress theme and visual builder for scroll motion, pinned scenes, parallax and
real 3D. The steps of building its pages are WordPress abilities; through the WordPress MCP
Adapter they are MCP tools. Everything you do runs as the WordPress user you connected with,
with that user's rights in the Midground editor – and every save is cleaned exactly as the
editor cleans it.

Not connected yet? See `references/connect.md` (Claude Code, Cursor, Codex; local and remote).

## When to use

- "Make a landing page / product page / scroll story with Midground."
- "Add a pinned scene, a 3D model, parallax or a text reveal to this page."
- "Change the headline / the pictures / the colours on the Midground page …"

## Inputs required

- What the page is for, and its real texts (ask for them, or write honest placeholder copy the
  user can replace – never invent facts, prices or quotes).
- Pictures, films and 3D models must already be in the WordPress media library;
  `midground-list-media` finds them and gives the exact value to use.

## Procedure

1. **Look first.** `midground-get-catalog` (no arguments) lists the element types, the effects
   and the library of ready-made sections and page layouts. Start from library sections: they
   are designed, responsive and tested. `part=library|effects|styles|elements` gives details;
   `element=<type>` gives one element's settings.
2. **Make the page.** `midground-create-page` with a `title`, the library `sections` in order
   (and/or your own `content` nodes) and `settings.layout`: `full` (edge to edge between the
   theme's header and footer – the default), `default` (inside the theme's page) or `canvas`
   (no theme header and footer). It is a draft unless you pass `status: "publish"`.
3. **Find what to change.** `midground-get-document` with `format: "outline"` gives element ids,
   types, a little of their text and their effects.
4. **Make it theirs.** `midground-update-element` changes texts (`props.text` on headings,
   `props.content` HTML on text), links, pictures and style (`style.base`, `style.tablet`,
   `style.mobile`; `null` removes a value). `midground-add-elements` adds nodes or a library
   section, at a position or inside an element. `midground-remove-element` removes one.
5. **Add motion with care.** `midground-add-effect` with a `recipe` from the catalog and a
   `trigger` (`view`, `appear`, `reveal`, `pin`, `page`, `pointer`, `hover`). One or two effects
   per section is plenty. Visitors who ask for reduced motion get a calm page automatically.
6. **Show, then publish.** Give the user the `preview` link (or `editor` link to fine-tune in the
   visual editor). Call `midground-publish` only when they ask for it.

`midground-save-document` replaces a whole document (as `get-document` returns it) – use it for
large rewrites, not small changes.

## How a page is built

A document is `{ "settings": { "layout": "full" }, "content": [ nodes ] }`. A node:

```json
{
  "type": "heading",
  "props": { "text": "Light you can turn", "level": "h2" },
  "style": { "base": { "typo": "display", "textAlign": "center" }, "mobile": { "typo": "h1" } },
  "fx": [ { "recipe": "rise", "trigger": "view" } ],
  "children": []
}
```

- Top level: `section` (and `hero`, `scene` …). Inside: `columns` → `column`, `container`,
  `stack`, `grid`, and content such as `heading`, `text`, `button`, `image`, `video`, `model3d`.
  `get-catalog` says which children each element takes.
- Use the site's design values, not raw colours: `var(--mg-c-<colour>)` (ink, paper, accent …),
  spacing `var(--mg-s-1)`…`var(--mg-s-9)`, type presets in `style.base.typo` (`display`, `h1`,
  `h2`, `lead`, `small`).
- Ids are made for nodes without one. Results list the ids of what changed.

`references/patterns.md` has working node trees: a pinned scene in acts, a 3D product, a text
reveal, parallax pictures.

## Good pages

- One idea per section; a clear heading order (one `h1`).
- Real alternative text on pictures and a description on 3D models; never put the only copy of
  important information in an animation, a film or a 3D view.
- Keep enough contrast; on dark sections set the text colour on the section.
- Check the phone: set `style.mobile` where the desktop size is too big.

## Verification

- Every write result has `warnings`: what the cleaning changed (unknown element types, values out
  of range). Fix what they point at and save again.
- Open the `preview` link (or ask the user to) and scroll through it on a computer and a phone.

## Failure modes

- *"You are not allowed …"*: the connected user lacks the right (making pages needs an editor or
  administrator; publishing needs the right to publish – otherwise it is saved for review).
- *"… is editing this content right now."*: someone has the page open in the editor; wait or ask.
- *"There is no element / effect / library section …"*: use the ids and names from
  `get-document` (outline) and `get-catalog`.
- Through the adapter's default server you only see `mcp-adapter-discover-abilities`,
  `mcp-adapter-get-ability-info` and `mcp-adapter-execute-ability`: call the abilities by name
  (`midground/create-page` …) with `execute-ability`, or connect to the Midground server instead
  (`references/connect.md`).

## Escalation

Uploading files, theme settings, menus and the site's design values (colours, fonts) are done in
WordPress or in the Midground editor (Design panel) – send the user there with the `editor` link.