AI Block Creator

Speak it, type it, or screenshot it into existence.
Create, iteratively refine, and insert custom Gutenberg blocks on the fly directly within the WordPress Block Editor without context switching.

✨ Features

• 🧭 Plans Before It Builds: A first, fast AI pass decides whether your request should become a brand-new custom block, a block style on an existing block, a block variation, or a block pattern — then tells you which it chose and why, with one click to rebuild it as any of the others. A "make pull quotes gold" request becomes an option in the Quote block's own Styles panel rather than a bespoke block nobody will find again, and "a hero section with two buttons" becomes a pattern of ordinary blocks you can edit normally.
• 🧷 Schema-Validated Generation: Every request carries a JSON schema of the shape it expects, so providers that support structured output are constrained rather than merely asked. A response that still comes back malformed gets one automatic repair turn — and everything stored is independently validated regardless. Variations are checked against the target block's own block.json attributes, so they can't be saved with settings that would quietly do nothing.
• 💬 Conversational Block Creation: Describe any component ("3-tier pricing table with a featured plan", "Testimonial card with 5 star rating", "FAQ accordion") and refine it through multi-turn chat.
• 🎙️ Voice Dictation ("Speak it into existence"): Click the microphone button and dictate your block requirements hands-free using the browser's Web Speech API.
• 📸 Screenshot-to-Block ("Screenshot it into existence"): Paste (Cmd+V / Ctrl+V), drag & drop, or upload UI screenshots or mockups. The AI interprets the design and structures a matching Gutenberg block.
• 🎨 Live Interactive Preview: Test block rendering, change preview attributes in real time, and inspect generated HTML and scoped CSS before inserting.
• 📚 Block Library: Every saved block shows up in the AI Block Library panel (editor's More menu), where you can insert it again, reopen it for conversational refinement, or delete it.
• ⚡ Instant Dynamic Registration: Blocks are immediately registered in the Gutenberg client runtime (wp.blocks.registerBlockType) and saved to the database (ai_block_def CPT) with dynamic server-side rendering and scoped CSS injection.
• 🔌 Native WordPress 7.0+ AI Client Integration: Connects seamlessly with WordPress core's AiClient (WordPress\AiClient\AiClient) and works with any configured provider (such as local LLMs via OpenAI-compatible servers, Ollama, vLLM, or cloud models).
• 🎛️ Follows Your Admin Color Scheme: The creator UI's accent color adapts to whichever admin color scheme (Blue, Coffee, Midnight, ...) you've chosen in your WordPress profile, instead of a fixed brand color.

🚀 Getting Started

🎮 Live Demo in WordPress Playground

Test AI Block Creator immediately in your browser — with the core ai plugin and OpenAI-compatible provider pre-installed:

Note: The blueprint lands directly on the Settings > Connectors screen so you can configure your AI provider (e.g. OpenAI API key, Ollama, LM Studio, or local vLLM endpoint) to test generation against.

Requirements

• WordPress: 7.0 or higher.
• PHP: 7.4 or higher (PHP 8.2+ recommended).
• Required Plugin: WordPress AI Plugin (Requires Plugins: ai).
• AI Connector: An active connector registered with the WordPress AI Client (e.g., AI Provider for OpenAI Compatible Servers).

Installation

1. Clone or download this repository into your WordPress wp-content/plugins/ directory:

   git clone https://github.com/georgestephanis/ai-block-creator.git wp-content/plugins/ai-block-creator

2. Install dependencies and build assets:

   cd wp-content/plugins/ai-block-creator
   npm install
   npm run build

3. Activate the plugin in WordPress Admin > Plugins or via WP-CLI:

   wp plugin activate ai-block-creator

🛠️ Usage

1. Open the Block Editor to edit or create a post (Posts > Add New).
2. Click the ✨ Create Block with AI button in the top toolbar, or type /ai-block in the editor.
3. Enter your prompt, speak into the microphone, or paste a screenshot.
4. Interact with the live preview and chat with the AI to refine styles or attributes.
5. Click 🚀 Insert into Post to add the newly created block directly onto your page canvas, or Save to Library to keep it for later without inserting it now.
6. To reuse a saved block later, open the AI Block Library panel from the editor's More menu (⋮). From there you can insert it again, click Refine to reopen it in the creator for further changes, or delete it.

Permissions

Anyone who can edit posts can generate and preview blocks. Saving a block to the library (and therefore inserting it, since inserting saves first) requires the unfiltered_html capability — Administrators and Editors have this by default on a standard WordPress install; Authors and Contributors do not. This is intentional: a saved block's HTML and CSS are served to every visitor of your site, the same trust boundary WordPress already applies to post content from those roles.

🧑‍💻 Development

# Install JS dependencies
npm install

# Start development build with file watcher
npm run start

# Production build
npm run build

# Lint JS/CSS (composer install first, then composer lint, for PHP)
npm run lint-js
npm run lint-css

# Run the test suites
npm run test-unit-js   # Jest
composer test           # PHPUnit — needs `composer install` first

build/ is committed to this repository — installing via a Git checkout (e.g. the Playground blueprint's git:directory step) doesn't run a build step, so a PR touching src/ should include a rebuilt build/.

The PHPUnit suite boots a real WordPress install (see tests/php/bootstrap.php) rather than the synthetic WP core test harness; if this plugin isn't checked out at the conventional wp-content/plugins/<slug>/ depth, point it at one with WP_ROOT=/path/to/wordpress composer test.

🪝 Hooks

Every hook is prefixed ai_block_creator_. All are optional — the plugin works without touching any of them.

Capability detection — override what the plugin thinks the site can do, e.g. to force the UI on while developing against a stubbed provider.

Model requests

What the AI may target — the default lists are curated rather than "every registered block", because a site with a dozen plugins has hundreds of them and most are noise in a prompt. Both results are intersected with the block registry after filtering, so you can add your own blocks but can't put a block this site doesn't have in front of the model.

Example — let the AI style your theme's own blocks:

add_filter(
    'ai_block_creator_target_block_candidates',
    function ( array $blocks ): array {
        $blocks[] = 'mytheme/callout';
        return $blocks;
    }
);

🤖 AI Disclosures & Model Contributions

This project embraces collaborative AI-assisted development across multiple models. Detailed logs of all contributing models and their specific architectural and code contributions are maintained in AI-DISCLOSURES.md.

📄 License

This project is licensed under the GPL-2.0-or-later License. See LICENSE for details.