Designer-led WordPress build workflow

Designer surface

Three windows on the designer's machine: Claude Code (or Studio Code) running in a terminal, a web browser pointed at the local site URL, and Figma open in a desktop app or browser tab. Claude Code is the only interface the designer types into; the browser and Figma are for viewing.

Agent layer

Claude Code with four MCP servers configured per project: Figma MCP for design source, Playwright MCP for visual validation, the WordPress MCP Adapter for site operations, and Filesystem MCP for project files. Five slash commands, four skills, and four review agent sub-agents are registered in the project's .claude/ directory.

Local site (WordPress Studio)

WebAssembly-compiled PHP with SQLite — no Docker, no MySQL service, no Apache config. The starter project's wp-content mounts directly into Studio's site folder; Claude's file edits show up immediately. The WordPress MCP Adapter plugin runs inside this local site.

WPEngine production

Two environments: staging for pre-production review, production for the live site. Deploys via SFTP (theme files, custom plugins, must-use plugins). Promotion from staging to production uses WPEngine's environment-copy API. Cache flushed via WP-CLI over WPEngine's SSH gateway.

What the build agent does

Reads Figma frames via Figma MCP. Writes theme code and block patterns via Filesystem MCP. Creates pages and configures plugins via the WordPress MCP Adapter. Takes screenshots via Playwright MCP. Dispatches agents at workflow boundaries. Integrates findings — auto-fixes safe issues, surfaces judgment calls for the designer.

Where the agents run

Each agent runs inline during build (dispatched by the primary, fast feedback to the designer). The same agent definition also runs in CI against the pre-deploy build (last-mile gate). Both contexts read the same agent files in .claude/agents/. Critical findings in either context block the deploy.

Figma MCP

The agent's source of truth for what to build. Reads the Figma file structure — frames, components, styles, design tokens — and returns it in a form the agent can reason about.

What it does

• Fetches file metadata and frame trees
• Retrieves specific frames by node ID
• Extracts design tokens — colors, typography, spacing, shadows
• Returns component structures with computed styles
• Downloads image and asset exports

Used by

• Primary build agent — initial reads of frames
• Figma review agent — comparison source for visual diffs
• Responsive agent — checks against Figma's responsive frames

Auth: Figma API token in the project .env; never exposed to the designer.

WordPress MCP Adapter

Structured WordPress operations exposed as MCP tools. Runs as a plugin inside the local WP Studio site. Replaces the older REST API + WP-CLI ad-hoc approach with a unified, permission-aware protocol.

What it does

• Creates and updates posts, pages, custom post types
• Inserts and edits Gutenberg blocks within content
• Manages navigation menus and menu items
• Sets WordPress options and theme settings
• Lists, activates, deactivates, and configures plugins
• Manages users, roles, and capabilities
• Queries content with structured filters
• Runs WP-CLI commands inside the site context

Used by

• Primary build agent — most page-building operations
• Content import workflow — bulk post creation
• Pull-content workflow — DB sync from staging

Auth: Local-only access; the plugin auto-authorizes the designer's machine.

Playwright MCP

Browser automation. Navigates URLs, takes screenshots, evaluates JavaScript in page context. Used wherever the agent needs to see what the rendered site actually looks like.

What it does

• Navigates to local or remote URLs
• Takes screenshots at specified viewports — 375, 768, 1440
• Evaluates JavaScript inside the loaded page
• Inspects DOM elements and computed styles
• Runs axe-core in the page context for a11y checks
• Performs interactions — click, type, scroll — for end-to-end testing

Used by

• Figma review agent — captures rendered output for visual diff
• Responsive agent — viewport screenshots
• Accessibility agent — runs axe-core, navigates, inspects
• Primary build agent — final-state verification screenshots

Auth: none — runs locally against local URLs.

Filesystem MCP

Direct read and write access to project files. The agent's primary interface for editing theme code, design tokens, block patterns, and any other file-based config.

What it does

• Reads files — theme PHP, CSS, JS, JSON, MD, any text
• Writes files — creates new, updates existing in place
• Lists directory contents recursively
• Checks file existence and metadata
• Moves and renames files

Used by

• Primary build agent — edits style.css, theme.json, functions.php, templates, block patterns
• All agents — read project configuration and conventions
• CSS iteration workflow — write-test-screenshot loop

Auth: scoped to the project directory; cannot reach files outside the project root.

WPEngine deploy interfaces

Three traditional tools wrapped in scripts handle the connection to WPEngine. Not MCP — these existed before MCP and stay because they're well-understood and fast.

SFTP

• Uploads theme and plugin files to staging and production
• Excludes .env, wp-content/uploads/, and other non-deploy paths
• Wrapped in scripts/wpe-sftp.sh for repeatable use

SSH (WPEngine gateway)

• Runs WP-CLI commands remotely against staging or production
• Flushes cache, updates plugins, queries DB, manages cron
• Wrapped in scripts/wpe-wp.sh

WPEngine REST API

• Environment management — copy staging → production
• Triggers on-demand backups before risky operations
• Invalidates the global edge cache
• Wrapped in scripts/wpe-api.sh

Used by the /deploy-staging command, the /promote-to-production command, and the /pull-content workflow.

Git

Version control. Both the designer and the agent operate on the same repository, but the designer never types git commands — the agent commits automatically at workflow boundaries.

What it does

• Tracks changes to project files
• Auto-commits at workflow boundaries — after successful builds, before deploys, after promotions
• Auto-pushes to the Newfangled Git host on commit
• Tags deploys (e.g., staging-2026-05-22-1430) so rollbacks have anchors
• Triggers CI workflows on push

Used by

• Primary build agent — auto-commits after successful build cycles
• Deploy slash commands — tag releases
• CI pipeline — pulls latest, runs validation, gates deploys

Auth: HTTPS credentials cached at OS level; designer never enters them manually.

Build a page from a Figma frame

Designer says

"Build the homepage from the Hero frame in Figma."

Agent does

1. Filesystem MCP — reads CLAUDE.md for project context, conventions, and Figma file URL
2. Figma MCP — fetches the Hero frame and its component tree
3. Figma MCP — extracts design tokens (colors, typography, spacing) from the frame and the file's design system
4. Filesystem MCP — reads current theme.json, style.css, and existing block patterns
5. Reconciles new tokens against existing — adds new ones, flags any conflicts
6. Filesystem MCP — writes updated theme.json and any new block-pattern files
7. WordPress MCP Adapter — creates the Home page, sets it as the front page
8. WordPress MCP Adapter — inserts the new block patterns as the page content
9. WordPress MCP Adapter — flushes WordPress cache
10. Playwright MCP — navigates to local URL, screenshots at 375 / 768 / 1440
11. Dispatches the four review agents — figma review, security, accessibility, responsive
12. Integrates findings — auto-fixes safe issues, surfaces judgment calls
13. Git — commits with a descriptive message; auto-pushes
14. Presents result to designer with screenshot links and a plain-language summary

Designer sees

• The local site rendering the new homepage at the local URL
• The agent's summary of what was built and which design tokens were used
• Any agent findings that need designer attention (e.g., "the hero's hover state isn't in the Figma; I used your standard interaction pattern")

Iterate on CSS or design tokens

Designer says

"Make the hero taller and the CTA button green."

Agent does

1. Identifies the target — usually the current page or last-edited frame from conversation context
2. Filesystem MCP — reads current theme.json, style.css, and the affected block pattern
3. Locates the relevant rules — hero block CSS, CTA button styles, height tokens, color tokens
4. Prefers updating design tokens over hardcoded values; updates the token only if the change is semantic ("brand green" not "this one element")
5. Filesystem MCP — writes the updated CSS / theme.json / pattern files
6. WordPress MCP Adapter — flushes cache
7. Playwright MCP — captures before/after screenshots of the affected page area
8. Dispatches relevant agents — accessibility (for contrast, e.g., new green vs. white text) and responsive (does the taller hero still work at 375?)
9. Auto-fixes contrast or layout issues if the change broke something fixable
10. Git — commits the CSS change
11. Presents diff to designer — old vs. new screenshot, any findings

Designer sees

• The updated local site reflecting the change
• A before/after comparison for the changed area
• Any agent concerns ("the new green doesn't meet 4.5:1 contrast against white text; I adjusted to the nearest brand-compliant green")

Build out the rest of the site and enter content

Designer says

"Build the About, Services, and Contact pages from their Figma frames." Or later: "Import the team bios from this Google Doc as team-member posts."

Agent does

1. For each new page:
   • Figma MCP — fetches the matching frame
   • Filesystem MCP — checks for existing block patterns that match the layout
   • Filesystem MCP — writes any new block patterns needed
   • WordPress MCP Adapter — creates the page
   • WordPress MCP Adapter — inserts blocks/patterns into the page
2. WordPress MCP Adapter — updates the primary navigation menu to include the new pages
3. WordPress MCP Adapter — configures Yoast SEO meta for each new page (or leaves defaults)
4. Playwright MCP — screenshots each created page at three viewports
5. Dispatches the four review agents against each new page
6. Auto-fixes safe issues
7. For content import:
   • Reads the source — file, URL, pasted text, or doc
   • Parses into structured posts — title, body, taxonomies, featured image
   • WordPress MCP Adapter — creates each post via batch operation
   • WordPress MCP Adapter — uploads featured images and attaches them
8. Git — commits and pushes
9. Presents a summary — what was created, where to view it, what needs designer review

Designer sees

• All new pages live on the local site
• Updated navigation including the new pages
• For content imports: a summary of how many posts were created and any parsing ambiguities
• Screenshots of each new page for review

What every workflow has in common

Each workflow follows the same shape — designer triggers, agent reads context, agent makes calls across the interfaces, agent validates, agent commits, designer sees pre-validated work.

Universal sequence

1. Read context (Filesystem MCP, CLAUDE.md, conversation history)
2. Read source (Figma MCP, designer instructions, existing project state)
3. Make changes (Filesystem MCP, WordPress MCP Adapter)
4. Validate (Playwright MCP for rendering, dispatched agents for review)
5. Auto-fix safe issues; flag the rest
6. Commit (Git)
7. Present result with screenshots and summary

What stays constant

• The designer triggers with plain language
• The agent uses the same interfaces for every workflow
• The review agents always run before the designer sees the work
• Git is always invisible to the designer

Common failures

• Studio site won't boot — restart Studio, then restart the site
• Claude can't connect to Figma MCP — re-authenticate Figma, restart Claude Code
• Claude can't connect to WordPress MCP — verify Studio site is running
• Deploy times out — retry the slash command
• Quality gate fails — review findings, ask Claude to fix specific issues
• Local site is in an unexpected state — run /reset-local
• Staging shows stale assets — flush staging cache

Escalation paths

• Any production issue — always escalate
• SSH or SFTP authentication errors — ops territory
• WPEngine environment-copy fails mid-promotion
• Plugin update breaks something
• PHP fatal error outside the theme
• Repository state diverged from main
• CI gate consistently misdiagnoses an issue