npm package: @10up/block-renderer-prompt-generator
Description: Generate AI prompts for WordPress block generation
Latest version: 0.1.7

# @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

```bash
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:

```typescript
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:

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

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

### Prompt Options

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```markdown
# 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:

```typescript
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