← Back to generator

Project Specification

AI Summary

Build a standalone AI-powered web app that generates complete, valid, installable WordPress Block Themes from natural language descriptions. The generated theme must be visually impressive, use only native core blocks (zero Custom HTML blocks), and output a downloadable ZIP that installs cleanly in WordPress 6.4+.

Must Have

  • • User input interface for site description
  • • AI orchestration with clear prompt construction
  • • Structured JSON/block markup output
  • • Zero Custom HTML blocks
  • • Deliverable theme ZIP package
  • • Robust validation of AI output
  • • Graceful error handling
  • • Unit tests + integration test
  • • README, ADR, “What I'd Do Next”

Bonus

  • • Live theme preview (WordPress Playground)
  • • Iterative refinement via chat
  • • Pattern Library integration
  • • Swappable AI provider

Key Constraint

The generated theme must be composed entirely of standard, core, and well-known pattern blocks. No Custom HTML block for any structural or visual element.

Full Specification

Overview

Build a standalone AI assistant that generates complete, structured WordPress Block Themes (using Full Site Editor / FSE capabilities) based on a user input. The challenge is to go beyond generic, boilerplate themes. The resulting theme must be well-structured, visually appealing, and composed entirely of standard, core, and well-known pattern blocks. Crucially, the generated theme must not use the Custom HTML block for any structural or visual element.

This project requires thoughtful engineering to translate abstract user intent into concrete, structured JSON/PHP files that define a modern, high-quality WordPress theme.

The Challenge

Create a web application where users can:

  1. Input Theme Criteria: Provide a natural language description (e.g., “A dark mode blog theme for photographers with a large, centered hero section and sticky navigation.”) and define specific technical criteria (e.g., color palette, typography).
  2. Generate Theme: Request the AI to generate the complete theme structure (e.g., theme.json, template files, patterns, etc.).
  3. Preview/Download: Allow the user to download the theme as a valid, runnable zip file or view a visual mock-up of the generated theme structure.

Core Requirements

  1. User Input Interface: Your choice on the best way to get the site description from the user. Think about the best way to understand what the user wants within good UX boundaries.
  2. AI Orchestration: A clear component responsible for prompt construction, ensuring the model understands the constraints of WordPress Block Themes (e.g., structure, supported blocks).
  3. Structured Output: The AI must output valid JSON and template files (or the content that forms them) that adhere to the WordPress Block Theme standards.
  4. No Custom HTML Block: The generated theme content (templates, parts, patterns) must exclusively use the native WordPress block syntax (e.g., <!-- wp:paragraph -->, <!-- wp:post-featured-image -->) and cannot use the HTML block.
  5. Deliverable Theme Package: The application must package the generated files into a structure that can be zipped and installed as a working WordPress Block Theme.

Technical Constraints

  • Standalone application: No external services or credentials required from us to run it, outside of the chosen AI provider.
  • Language agnostic: The generated output is WordPress-specific (JSON/PHP/HTML), but the application's stack is your choice.
  • Your choice of AI provider: OpenAI, Anthropic, local models — your call. The integration must be clean enough that swapping providers is not a major rewrite.
  • Your choice of stack: Use the stack you are most effective with. The quality of the generated theme is more important than the choice of framework.

Quality Bar

This is an MVP, but it should be a production-minded one. We are looking for code that reflects good engineering discipline, focusing on reliable data transformation and robust output generation.

Error Handling

  • Graceful handling of API failures and rate limits.
  • Robust validation of the AI's output: if the model generates invalid JSON or malformed block HTML, the application must detect this and provide a meaningful error to the user, not a silent failure.
  • Input validation where it matters (e.g., ensuring theme slug is valid).

Testing

  • Unit tests covering the core logic (prompt construction, output validation, file packaging).
  • At least one integration test covering the end-to-end flow of generating a theme from a simple description.
  • Tests should pass cleanly — a simple npm test or similar should run the checks without setup friction.

Expected Deliverables

  1. Working Application: A functional prototype demonstrating the core workflow: input criteria, generate theme, and download the resulting zip file.
  2. README: How to run it locally, including any environment variables needed. A brief overview of the architecture, especially the output generation process. Known limitations or rough edges.
  3. Architectural Decision Record (ADR): The key technical decisions made. Alternatives considered and why they were rejected. Trade-offs accepted consciously. Security considerations. Design exploration.
  4. “What I'd Do Next”: What you'd prioritize if you had another week. What you'd need to change to make this genuinely production-ready. How you'd approach scaling this to support complex dynamic features.
  5. Code: Clean, typed, tested, and linted. PRs and commits that give a reviewer confidence in how you work.

Evaluation Criteria

Must Have

  • A theme generation process that creates a valid, runnable WordPress Block Theme.
  • Zero usage of the Custom HTML block for structure or content.
  • AI integration that provides structured output reliably.
  • Robust validation of the AI's output structure.
  • Tests that pass cleanly.
  • Clean, readable, well-structured code.
  • Strong commit history and PR discipline.
  • README, ADR, and “What I'd Do Next.”

Raises the Bar

  • A generated theme that is visually high-quality, non-generic, and demonstrates sophisticated block usage.
  • Thoughtful prompt engineering that produces consistently correct and detailed block markup.
  • An ADR that shows genuine product and architectural thinking.
  • A “What I'd Do Next” that addresses the unique challenges of building a dynamic file generation tool.

Bonus Ideas

  • Live Theme Preview: Provide a way for the user to see the resulting theme without needing a separate WordPress instance.
  • Iteration: Give the user a way to make subsequent changes to the theme.
  • Pattern Library Integration: Structure the output so that generated patterns are immediately available in the WordPress Pattern Library interface.
  • Your own ideas: Be creative!
← Back to generator
🏠 Hetzner · Coolify