@10up/block-renderer-prompt-generator

Generate AI system prompts with block documentation, design tokens, and patterns. These prompts guide AI assistants in generating valid WordPress block structures.

Installation

npm install @10up/block-renderer-prompt-generator
# or
pnpm add @10up/block-renderer-prompt-generator

Overview

This package generates comprehensive system prompts for AI assistants that include:

1. Block documentation - Available blocks with their props and constraints
2. Design tokens - Colors, typography, spacing from theme.json
3. Patterns - Available block patterns that can be referenced
4. User preferences - Style guide and preferred blocks
5. Format instructions - How to structure the JSON output

Usage

Generate Complete System Prompt

The main entry point - generates a full system prompt:

import { generateSystemPrompt } from '@10up/block-renderer-prompt-generator';

const prompt = generateSystemPrompt({
  catalog: blockCatalog,
  tokens: themeTokens,
  patterns: patternRegistry,
  preferences: userPreferences,
  compact: false
});

// Use as system prompt for AI

Generate Minimal Prompt

For smaller context windows:

import { generateMinimalPrompt } from '@10up/block-renderer-prompt-generator';

const prompt = generateMinimalPrompt({
  tokens: themeTokens,
  patterns: patternRegistry,
});

Prompt Options

interface GeneratePromptOptions {
  /** Block catalog for documentation */
  catalog?: BlockCatalog;
  /** Theme tokens for color/typography docs */
  tokens?: ThemeTokens;
  /** Available patterns */
  patterns?: PatternRegistry;
  /** User preferences */
  preferences?: BlockPreferencesConfig;
  /** Use compact format for smaller context */
  compact?: boolean;
}

Individual Generators

Block Documentation

import {
  generateBlocksPrompt,
  generateBlockList,
  generateBlockDocumentation,
  generateNestingRulesPrompt,
} from '@10up/block-renderer-prompt-generator';

// Full block documentation
const blocksDoc = generateBlocksPrompt(catalog);

// Simple list of block names
const blockList = generateBlockList(catalog);
// 'core/paragraph, core/heading, core/group, ...'

// Documentation for a single block
const paragraphDoc = generateBlockDocumentation(paragraphDefinition);

// Nesting rules documentation
const nestingDoc = generateNestingRulesPrompt(catalog);

Token Documentation

import {
  generateTokensPrompt,
  generateColorsPrompt,
  generateGradientsPrompt,
  generateTypographyPrompt,
  generateSpacingPrompt,
  generateShadowsPrompt,
  generateLayoutPrompt,
} from '@10up/block-renderer-prompt-generator';

// Complete token documentation
const tokensDoc = generateTokensPrompt(tokens);

// Individual token types
const colorsDoc = generateColorsPrompt(tokens);
const gradientsDoc = generateGradientsPrompt(tokens);
const typographyDoc = generateTypographyPrompt(tokens);
const spacingDoc = generateSpacingPrompt(tokens);
const shadowsDoc = generateShadowsPrompt(tokens);
const layoutDoc = generateLayoutPrompt(tokens);

Pattern Documentation

import {
  generatePatternsPrompt,
  generatePatternList,
  generatePatternDocumentation,
  generateCompactPatternList,
} from '@10up/block-renderer-prompt-generator';

// Full pattern documentation
const patternsDoc = generatePatternsPrompt(patterns);

// Simple list of pattern slugs
const patternList = generatePatternList(patterns);
// 'theme/hero-section, theme/feature-grid, ...'

// Documentation for a single pattern
const heroDoc = generatePatternDocumentation(heroPattern);

// Compact list for smaller context
const compactList = generateCompactPatternList(patterns);

Section Styles Documentation

import {
  generateSectionStylesPrompt,
  generateSectionStyleList,
  generateSectionStyleDocumentation,
  generateCompactSectionStyleList,
} from '@10up/block-renderer-prompt-generator';

// Full section styles documentation
const stylesDoc = generateSectionStylesPrompt(sectionStyles);

// Simple list of style names
const styleList = generateSectionStyleList(sectionStyles);

// Documentation for a single section style
const heroStyleDoc = generateSectionStyleDocumentation('hero', heroStyle);

// Compact list for smaller context
const compactList = generateCompactSectionStyleList(sectionStyles);

Ignite WP Documentation

import {
  generateIgnitePrompt,
  generateCompactIgnitePrompt,
} from '@10up/block-renderer-prompt-generator';

// Full Ignite WP documentation (typography presets, fluid values)
const igniteDoc = generateIgnitePrompt(igniteTokens);

// Compact version for smaller context
const compactIgniteDoc = generateCompactIgnitePrompt(igniteTokens);

Critical Styling Rules

import { generateCriticalStylingRules } from '@10up/block-renderer-prompt-generator';

// Generate rules for consistent AI styling decisions
const rules = generateCriticalStylingRules();
// Returns markdown with best practices for block styling

Generated Prompt Structure

A complete generated prompt includes:

# WordPress Block Generation

You are generating WordPress blocks using a JSON format...

## Block Tree Format

The JSON structure you should generate...

## Available Blocks

### core/paragraph
Text block with the following props:
- content (string): The paragraph text
- dropCap (boolean): Enable drop cap
...

### core/heading
Heading block with levels 1-6...

## Design Tokens

### Colors
Available colors: primary (#0073aa), secondary (#23282d), ...

### Typography
Font sizes: small (13px), medium (16px), large (20px), ...

### Spacing
Spacing scale: 20 (0.5rem), 30 (0.75rem), 40 (1rem), ...

## Available Patterns

### theme/hero-section
A full-width hero with heading and CTA...

### theme/feature-grid
Three-column feature grid...

## User Preferences

### Preferred Blocks
- core/group (for containers)
- core/columns (for layouts)

### Style Guide
- Always use constrained layout for groups
- Prefer semantic heading levels

Compact Mode

For AI models with smaller context windows, use compact mode:

const prompt = generateSystemPrompt({
  catalog,
  tokens,
  patterns,
  compact: true  // Shorter, more concise output
});

Compact mode:

• Uses shorter descriptions
• Omits detailed attribute documentation
• Lists only essential tokens
• Removes examples

Complete Exports

System Prompt

| Function | Description | |----------|-------------| | generateSystemPrompt(options) | Generate complete system prompt | | generateMinimalPrompt(options) | Generate minimal prompt | | generateCriticalStylingRules() | Generate critical styling rules |

Block Documentation

| Function | Description | |----------|-------------| | generateBlocksPrompt(catalog) | Full blocks documentation | | generateBlockList(catalog) | Simple comma-separated list | | generateBlockDocumentation(definition) | Single block documentation | | generateNestingRulesPrompt(catalog) | Nesting rules documentation |

Token Documentation

| Function | Description | |----------|-------------| | generateTokensPrompt(tokens, options?) | Complete tokens documentation | | generateColorsPrompt(tokens) | Color tokens documentation | | generateGradientsPrompt(tokens) | Gradient tokens documentation | | generateTypographyPrompt(tokens) | Typography documentation | | generateSpacingPrompt(tokens) | Spacing tokens documentation | | generateShadowsPrompt(tokens) | Shadow tokens documentation | | generateLayoutPrompt(tokens) | Layout settings documentation |

Pattern Documentation

| Function | Description | |----------|-------------| | generatePatternsPrompt(patterns) | Full patterns documentation | | generatePatternList(patterns) | Simple comma-separated list | | generatePatternDocumentation(pattern) | Single pattern documentation | | generateCompactPatternList(patterns) | Compact pattern list |

Section Styles Documentation

| Function | Description | |----------|-------------| | generateSectionStylesPrompt(styles) | Full section styles documentation | | generateSectionStyleList(styles) | Simple list of style names | | generateSectionStyleDocumentation(name, style) | Single section style docs | | generateCompactSectionStyleList(styles) | Compact section style list |

Ignite WP Documentation

| Function | Description | |----------|-------------| | generateIgnitePrompt(tokens) | Full Ignite WP documentation | | generateCompactIgnitePrompt(tokens) | Compact Ignite WP documentation |

Types

| Type | Description | |------|-------------| | GeneratePromptOptions | Options for prompt generation | | TokenPromptOptions | Options for token prompt generation |

License

MIT