WP Theme Forge

AI-powered child theme generator for WordPress. Describe your brand, upload a logo, and get a production-ready child theme in minutes.

WP Theme Forge takes a brand description and an optional logo, extracts colors using K-means clustering, pairs typography from a curated Google Fonts library, and uses Claude to generate a complete child theme with style.css, theme.json, and template files. The result is a valid, accessible WordPress theme ready to activate or export as a ZIP.

Features

• Natural language input -- describe your brand's personality and aesthetic
• Logo color extraction -- K-means clustering on GD extracts a 5-color palette from uploaded logos (JPEG, PNG, GIF, WebP)
• Intelligent typography pairing -- 25+ keyword-matched Google Fonts pairings (modern, elegant, playful, tech, etc.)
• Parent theme support -- generates child themes for Twenty Twenty-Four, GeneratePress, and other block themes
• Accessibility validation -- WCAG contrast ratio checking on extracted color palettes
• theme.json generation -- proper WordPress theme.json with color palette, typography, and layout settings
• Theme preview -- preview generated themes in the Customizer before activating
• One-click activation -- switch to your generated theme directly from the admin
• ZIP export -- download themes as ZIP files for deployment to other sites
• Version tracking -- stores generation snapshots with the prompt and file manifest
• Theme management -- list, activate, delete generated themes from a dedicated admin page

Requirements

• WordPress 6.0+
• PHP 7.4+
• GD extension (for logo color extraction)
• A block theme installed as parent (e.g., Twenty Twenty-Four)

Installation

1. Upload the wp-theme-forge directory to wp-content/plugins/.
2. Run composer install inside the plugin directory.
3. Activate the plugin through the WordPress admin.
4. Navigate to Theme Forge > Settings to configure your AI provider.

Configuration

AI Provider

The plugin uses Claude (Anthropic) for theme generation. Configure access via:

• SmartWeb Proxy -- enter your proxy URL and site token
• Direct API Key -- enter your Anthropic API key (encrypted at rest)

Parent Theme

WP Theme Forge auto-detects your active theme and determines its CSS framework. You can also specify a parent theme explicitly when generating. Supported parent themes include:

Parent Theme	Detection
Twenty Twenty-Four (TT24)	Default WordPress block theme
GeneratePress	Popular lightweight theme
Any FSE/block theme	Auto-detected via theme.json presence

Usage

Generating a Theme

1. Go to Theme Forge in the admin menu.
2. Enter a brand description:

   "A modern, minimalist photography portfolio. Clean lines, lots of whitespace, dark accents. Professional but approachable."

3. Optionally upload a logo -- the plugin will extract your brand colors automatically.
4. Optionally select a parent theme (or let the plugin auto-detect).
5. Click Generate.

The generation pipeline runs through these steps:

1. Parent theme detection -- identifies the parent and its CSS framework
2. Color extraction -- K-means clustering pulls 5 colors from your logo (primary, secondary, accent, background, text)
3. Accessibility check -- validates WCAG contrast ratios on the palette
4. Typography pairing -- matches fonts to brand keywords in your description
5. Prompt assembly -- builds a detailed prompt with colors, fonts, and parent theme context
6. AI generation -- Claude generates style.css, theme.json, and template files
7. Validation -- verifies style.css headers and theme.json schema
8. Write to disk -- files go to wp-content/themes/{slug}/
9. Database registration -- stores the theme record and version snapshot

Color Extraction

When you upload a logo, the ColorExtractor uses PHP GD to:

1. Sample up to 1,000 pixels (evenly distributed across the image)
2. Skip transparent, near-white, and near-black pixels (background removal)
3. Run K-means clustering with 5 centroids and up to 20 iterations
4. Label clusters by dominance: primary, secondary, accent, background, text
5. Ensure background (#ffffff) and text (#333333) defaults if not enough distinct colors

Supported image formats: JPEG, PNG, GIF, WebP.

Typography Pairing

The TypographyPairer matches keywords in your brand description against 25+ curated Google Fonts pairings:

Keyword	Heading Font	Body Font
modern	Inter	Inter
elegant	Playfair Display	Lato
tech	JetBrains Mono	Inter
playful	Fredoka	Nunito
corporate	Roboto Slab	Roboto
photography	DM Serif Display	DM Sans
...and 20 more

If no keywords match, defaults to Inter/Inter at 18px base size.

Theme Preview

After generation, use the Preview button to see your theme in the WordPress Customizer before committing to activation.

Theme Export

Click Export on any generated theme to download a ZIP file containing all theme files. Deploy the ZIP to any WordPress site via Appearance > Themes > Add New > Upload.

REST API

All endpoints are under the wtf/v1 namespace and require manage_options capability (except activate, which requires switch_themes).

Generate a Theme

POST /wp-json/wtf/v1/generate

Body (JSON):

{
  "description": "A warm, rustic bakery website with earthy tones",
  "logo_id": 456,
  "parent_theme": "twentytwentyfour"
}

Response (200):

{
  "id": 7,
  "slug": "warm-rustic-bakery",
  "name": "Warm Rustic Bakery",
  "parent_theme": "twentytwentyfour",
  "colors": {
    "primary": { "hex": "#8B4513", "name": "Primary", "usage": "headings, buttons, links" },
    "secondary": { "hex": "#D2B48C", "name": "Secondary", "usage": "backgrounds, accents" }
  },
  "fonts": { "heading": "Vollkorn", "body": "Nunito Sans", "base_size": "18px" },
  "files": ["style.css", "theme.json", "templates/home.html", "parts/header.html"]
}

List Generated Themes

GET /wp-json/wtf/v1/themes

Activate a Theme

POST /wp-json/wtf/v1/themes/{id}/activate

Export as ZIP

POST /wp-json/wtf/v1/themes/{id}/export

Returns { "zip_url": "..." }.

Delete a Theme

DELETE /wp-json/wtf/v1/themes/{id}

Removes theme files from disk and the database record.

Extract Colors from Image

POST /wp-json/wtf/v1/colors/extract

Body (JSON):

{
  "attachment_id": 456
}

Returns the 5-color labeled palette without generating a full theme. Useful for previewing color extraction results.

Development

Project Structure

wp-theme-forge/
  src/
    AI/
      ClaudeProvider.php          # Anthropic API client for theme generation
      PromptBuilder.php           # Theme-specific prompt assembly
      ProviderInterface.php       # Provider contract
    Admin/
      SettingsPage.php            # Plugin settings UI
      ThemeManager.php            # Admin page: list, activate, delete, export
      ThemePreview.php            # Customizer preview integration
    Generator/
      AccessibilityChecker.php    # WCAG contrast ratio validation
      ColorExtractor.php          # K-means color extraction from images (GD)
      ParentThemeDetector.php     # Detect parent theme and CSS framework
      StyleGenerator.php          # Validate/fix style.css headers
      TemplateGenerator.php       # Template part generation
      ThemeGenerator.php          # Full pipeline orchestrator
      ThemeJsonGenerator.php      # theme.json generation and validation
      ThemeValidator.php          # Final theme validation pass
      TypographyPairer.php        # Keyword-based Google Fonts matching
    Theme/
      ThemeExporter.php           # ZIP export
      ThemeRegistry.php           # CRUD for wtf_themes table
    Plugin.php                    # Singleton bootstrap, DB tables, admin assets
  generated-themes/               # Staging area for theme files
  assets/
    css/admin.css                 # Admin styles
    js/admin.js                   # Admin JavaScript
  templates/                      # Admin page templates
  languages/                      # Translation files

Autoloading

PSR-4 via Composer. Namespace WPThemeForge\ maps to src/.

Database Tables

Two tables created on activation:

• {prefix}wtf_themes -- theme records (slug, name, description, parent_theme, colors JSON, typography JSON, status)
• {prefix}wtf_versions -- version snapshots (theme_id, files_snapshot JSON, prompt, version string)

Coding Standards

composer install
./vendor/bin/phpcs --standard=phpcs.xml src/

Dev dependencies include squizlabs/php_codesniffer, wp-coding-standards/wpcs, and phpcompatibility/phpcompatibility-wp.

Generated Theme Output

Themes are written to wp-content/themes/{slug}/ using WP_Filesystem. A typical generated theme contains:

• style.css -- with proper theme headers and child theme Template: declaration
• theme.json -- WordPress theme.json v2 with color palette, font families, layout settings
• templates/ -- block template files (e.g., home.html, single.html)
• parts/ -- template parts (e.g., header.html, footer.html)

Changelog

1.0.0

• Initial release
• Claude-powered theme generation from brand descriptions
• K-means color extraction from logos (GD)
• 25+ curated typography pairings
• WCAG accessibility validation
• Parent theme auto-detection
• theme.json generation
• ZIP export
• Customizer preview

License

GPL-2.0-or-later. See LICENSE.