WordPress with AI | Cynosure Design System

Overview

The Cynosure Design System components can be compiled into WordPress Gutenberg blocks using the handoff-wordpress CLI. This page explains how to use AI tools to accelerate that workflow.

See WordPress Integration for full CLI documentation.

AI-assisted block generation workflow

When adding a Cynosure block to a WordPress site, follow this three-step AI workflow:

Step 1: Generate the Handoff component

Provide AGENTS.md as context and ask the LLM to generate the four-file component structure. See Ingesting into LLMs for prompt patterns.

Step 2: Generate the WordPress config entry

Once the component exists in Handoff, ask the AI to generate the handoff-wp.config.json entry:

Code

Context: [paste guidelines/wordpress content or AGENTS.md]

Task: Generate the handoff-wp.config.json import entry for a block called
"posts-latest". It has an array property called "posts" that should be driven
by a WordPress query pulling from the "post" post type. Map these fields:
- image → featured_image
- title → post_title
- excerpt → post_excerpt
- date.day → post_date:day_numeric
- date.month → post_date:month_short
- link.url → permalink

Use selectionMode: "query", renderMode: "mapped", maxItems: 6.

Step 3: Review the generated block

After running handoff-wordpress fetch, the CLI generates:

Code

demo/plugin/blocks/{block-name}/
  ├── block.json           — Gutenberg block registration
  ├── edit.js              — React editor component
  ├── render.php           — PHP template (compiled from Handlebars)
  ├── module.css           — compiled component SCSS
  └── index.js             — block entry point

Ask the AI to review render.php and block.json for correctness before registering the block.

Prompt patterns for WordPress work

Configuring a dynamic block with post queries

Code

Context: [paste AGENTS.md]

I have a Cynosure block called "events-upcoming" that shows a list of upcoming
events. Its "events" array property should be populated from a custom post type
called "tribe_events" (The Events Calendar).

Generate the handoff-wp.config.json entry to:
1. Pull events sorted by event date (meta_key: _EventStartDate, orderby: meta_value)
2. Filter to only future events (meta_query: _EventStartDate >= today)
3. Map: title → post_title, date → _EventStartDate, image → featured_image,
   link.url → permalink, location → _EventVenue
4. Use selectionMode: "query", maxItems: 10

Fixing template compilation issues

Code

Context: [paste AGENTS.md]

The handoff-wordpress CLI compiled my "hero-contact" block's template.hbs into
render.php but the Select2 dropdowns are not initializing on the frontend.
The block's script.js is:

[paste script.js content]

What do I need to add to the block's block.json to enqueue the compiled
main.js from the Handoff design system, and how should I handle the CYNO_DATA
localized data that selects.js depends on?

Adapting a Handlebars template for WordPress inner blocks

Code

Context: [paste AGENTS.md]

The "content" block has a richtext property called "body" that should support
WordPress inner blocks in the editor (so editors can add Gutenberg blocks inside it).

Update the "body" property in content.js to use the "innerBlocks" arrayType,
and update the handoff-wp.config.json entry accordingly.

What AI can and cannot do

Task	AI useful?	Notes
Generate handoff-wp.config.json entries	Yes	Provide the property schema and field mapping requirements
Write the Handlebars template	Yes	Provide AGENTS.md so it uses Handoff conventions, not React
Review compiled render.php	Yes	Useful for catching Handlebars-to-PHP translation issues
Generate block.json registration	Yes	Follows WordPress block API patterns LLMs know well
Fetch from Figma	Partially	Use the Figma Desktop MCP with `get_design_context` for layout reference
Auto-deploy to WordPress	No	Run `handoff-wordpress fetch` and WordPress block registration manually

Useful context to include

When working on WordPress integration with AI, include:

AGENTS.md — Cynosure conventions
The specific block's four files — .js, template.hbs, style.scss, script.js
handoff-wp.config.example.json — shows the config format with real examples
The target WordPress post type schema — so the AI can generate correct field mappings