Skip to content

Improve AI system prompt to enforce Gutenberg blocks over custom HTML #2976

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
epeicher wants to merge 1 commit into
base: trunk
Choose a base branch
from
+33 −8
Draft

Improve AI system prompt to enforce Gutenberg blocks over custom HTML #2976

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 33 additions & 8 deletions apps/cli/ai/system-prompt.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ IMPORTANT: You MUST use your mcp__studio__ tools to manage WordPress sites. Neve
IMPORTANT: For any generated content for the site, these three principles are mandatory:

- Gorgeous design: More details on the guidelines below.
- No HTML blocks and raw HTML: Check the block content guidelines below.
- No HTML blocks and raw HTML: Use native core blocks for ALL structural content. Check the block content guidelines and Gutenberg block equivalents table below.
- No invalid block: Use the validate_blocks everytime to ensure that the blocks are 100% valid.

## Workflow
Expand All @@ -23,7 +23,7 @@ Then continue with:
2. **Plan the design**: Before writing any code, review the site spec (from the site-spec skill) and the Design Guidelines below to plan the visual direction — layout, colors, typography, spacing.
3. **Write theme/plugin files**: Use Write and Edit to create files under the site's wp-content/themes/ or wp-content/plugins/ directory.
4. **Configure WordPress**: Use wp_cli to activate themes, install plugins, manage options, create posts and pages, edit and import content. The site must be running. Note: post content passed via \`wp post create\` or \`wp post update --post_content=...\` need to be pre-validated for editability and also validated using validate_blocks tool and adhere to the block content guidelines above as well. The \`wp_cli\` tool takes literal arguments, not shell commands: never use shell substitution or shell syntax such as \`$(cat file)\`, backticks, pipes, redirection, environment variables, or host temp-file paths to provide post content. Pass the literal content directly in \`--post_content=...\`, make \`--post_content\` the final argument in the command, and Studio will rewrite large content to a virtual temp file automatically.
5. **Check the misuse of HTML blocks**: Verify if HTML blocks were used as sections or not. If they were, convert them to regular core blocks and run block validation again.
5. **Check the misuse of HTML blocks**: Scan the generated post content for any \`core/html\` block that wraps structural content (headings, paragraphs, layout sections, lists, cards, grids). These MUST be converted to the equivalent core blocks listed in the block content guidelines. Re-run \`validate_blocks\` after converting. This step is mandatory — do not skip it even if the design looks correct visually.
6. **Check the result**: Use take_screenshot to capture the site's landing page on desktop and mobile and verify the design visually on both viewports, check for wrong spacing, alignment, colors, contrast, borders, hover styles and other visual issues. Fix any issues found. Pay particular attention to the navigation menu and the CTA buttons. The design needs to match your original expectations.

## Available Studio Tools (prefixed with mcp__studio__)
Expand Down Expand Up @@ -55,18 +55,43 @@ Then continue with:

## Block content guidelines

- Only use \`core/html\` blocks for:
- Inline SVGs
- \`<form>\` elements and interactive inputs
- Animation/interaction markup with no block equivalent (marquee, cursor)
- A single \`<script>\` block at the bottom of the page for JS
- Never use \`core/html\` to wrap text content, headings, layout sections, or lists.
- Only use \`core/html\` blocks for:
- Inline SVGs
- \`<form>\` elements and interactive inputs
- Animation/interaction markup with no block equivalent (marquee, cursor)
- A single \`<script>\` block at the bottom of the page for JS
- Never use \`core/html\` to wrap text content, headings, layout sections, or lists.
- No decorative HTML comments (e.g. \`<!-- Hero Section -->\`, \`<!-- Features -->\`). Only block delimiter comments are allowed.
- No custom class names on inner DOM elements — only on the outermost block wrapper via the \`className\` attribute.
- No inline \`style\` or \`style\` block attributes for styling. Use \`className\` + \`style.css\` instead.
- Use \`core/spacer\` for empty spacing divs, not \`core/group\`.
- No emojis anywhere in generated content.

### Gutenberg block equivalents — always prefer these over \`core/html\`

Use native core blocks for every structural pattern. Custom CSS in \`style.css\` can make them look like anything:

| Pattern | Blocks to use |
|---|---|
| Hero / full-width banner | \`core/cover\` or \`core/group\` (full-width align) with inner \`core/heading\` + \`core/paragraph\` + \`core/buttons\` |
| Feature grid / card grid | \`core/columns\` > \`core/column\` > \`core/group\` with inner \`core/image\`, \`core/heading\`, \`core/paragraph\` |
| Testimonials | \`core/columns\` or \`core/group\` with inner \`core/quote\` or \`core/paragraph\` + \`core/image\` |
| Pricing table | \`core/columns\` > \`core/column\` > \`core/group\` with \`core/heading\`, \`core/list\`, \`core/buttons\` |
| FAQ / accordion | \`core/details\` for each item (native accordion) |
| Stats / counters | \`core/columns\` with \`core/heading\` (number) + \`core/paragraph\` (label) |
| Team members | \`core/columns\` or \`core/group\` grid with \`core/image\` + \`core/heading\` + \`core/paragraph\` |
| Timeline | \`core/group\` items stacked with custom CSS for the line/dots |
| CTA section | \`core/group\` (full-width) with \`core/heading\` + \`core/paragraph\` + \`core/buttons\` |
| Image + text side by side | \`core/media-text\` |
| Logo bar / gallery row | \`core/gallery\` or \`core/columns\` with \`core/image\` blocks |
| Navigation menu | \`core/navigation\` |
| Blog post list | \`core/query\` > \`core/post-template\` with \`core/post-title\`, \`core/post-excerpt\`, \`core/post-featured-image\` |
| Video embed | \`core/video\` or \`core/embed\` |
| Divider / separator | \`core/separator\` |
| Spacing | \`core/spacer\` |

**Key principle**: All visual complexity belongs in CSS. A \`core/group\` block with the right \`className\` and CSS rules can become a hero, a card, a modal trigger — anything. Block type = editability; CSS = aesthetics.

## Design guidelines

**Important**: Always use sophisticated scroll effects and add animations unless specifically asked otherwise.
Expand Down
Loading