Wp Theme Development

# Missing required files for block theme
[ ! -f templates/index.html ] && [ -f theme.json ] && echo "CRITICAL: Block theme missing templates/index.html"
[ ! -f theme.json ] && [ -d templates ] && echo "CRITICAL: templates/ exists but theme.json missing"

# Missing required files for classic theme
[ ! -f index.php ] && [ ! -d templates ] && echo "CRITICAL: Classic theme missing index.php"

# theme.json with invalid or missing version
test -f theme.json && ! rg -q "\"version\"" theme.json && echo "CRITICAL: theme.json missing version"
rg -n "\"version\": 1" theme.json  # Deprecated
rg -n "\"version\": [^23]" theme.json  # Invalid version

# Missing style.css required header
test -f style.css && ! rg -q "Theme Name:" style.css && echo "CRITICAL: style.css missing Theme Name header"

# v3 theme.json with custom fontSizes but missing defaultFontSizes: false
rg -n "\"fontSizes\"" theme.json
# Manual follow-up: if custom fontSizes are defined, confirm defaultFontSizes is explicitly false.

# v3 theme.json with custom spacingSizes but missing defaultSpacingSizes: false
rg -n "\"spacingSizes\"" theme.json
# Manual follow-up: if custom spacingSizes are defined, confirm defaultSpacingSizes is explicitly false.

# Child theme missing Template header
test -f style.css && ! rg -q "Template:" style.css && echo "CRITICAL: If this is a child theme, style.css is missing Template header"

# theme.json version 2 (should upgrade to v3)
rg -n "\"version\": 2" theme.json

# Hardcoded inline styles in block templates
rg -n "style=\"" templates/ parts/ -g '*.html'

# Hardcoded color hex values in templates
rg -n "#[0-9a-fA-F]{6}" templates/ parts/ -g '*.html'

# Hardcoded pixel font sizes in templates
rg -n "font-size:\s*[0-9]+px" templates/ parts/ -g '*.html'

# Root padding without useRootPaddingAwareAlignments
rg -n "\"padding\"" theme.json
# Manual follow-up: if root padding is present, confirm useRootPaddingAwareAlignments is enabled.

# useRootPaddingAwareAlignments with CSS shorthand padding (won't work)
rg -n "useRootPaddingAwareAlignments.*true" theme.json
rg -n "\"padding\":\s*\"" theme.json

# Block theme with add_theme_support() that should be in theme.json
rg -n "add_theme_support.*editor-color-palette" functions.php
rg -n "add_theme_support.*editor-font-sizes" functions.php
rg -n "add_theme_support.*custom-line-height" functions.php
rg -n "add_theme_support.*custom-spacing" functions.php

# Missing ABSPATH check in functions.php
test -f functions.php && ! sed -n '1,10p' functions.php | rg -q "defined.*ABSPATH" && echo "WARNING: functions.php missing ABSPATH check in first 10 lines"

# Pattern file without required headers
rg -L "Title:" patterns -g '*.php'
rg -L "Slug:" patterns -g '*.php'

# Missing $schema in theme.json
test -f theme.json && ! rg -q "\"\\$schema\"" theme.json && echo "INFO: theme.json missing \$schema"

# Missing style variations directory
[ ! -d styles ] && echo "INFO: Could add style variations in styles/"

# Missing block patterns directory
[ ! -d patterns ] && echo "INFO: Could add block patterns in patterns/"

# Missing templateParts registration in theme.json
test -f theme.json && ! rg -q "\"templateParts\"" theme.json && echo "INFO: theme.json missing templateParts registration"

# Missing customTemplates registration in theme.json
test -f theme.json && ! rg -q "\"customTemplates\"" theme.json && echo "INFO: theme.json missing customTemplates registration"

# Google Fonts CDN usage (could use local fonts)
rg -n "fonts.googleapis.com" .

# Classic theme without theme.json (could be hybrid)
[ -f index.php ] && [ ! -f theme.json ] && echo "INFO: Classic theme could add theme.json for block editor support"

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"appearanceTools": true,
		"useRootPaddingAwareAlignments": true,
		"color": {
			"defaultPalette": false,
			"palette": [
				{
					"slug": "primary",
					"color": "#0073aa",
					"name": "Primary"
				},
				{
					"slug": "secondary",
					"color": "#005177",
					"name": "Secondary"
				},
				{
					"slug": "foreground",
					"color": "#333333",
					"name": "Foreground"
				},
				{
					"slug": "background",
					"color": "#ffffff",
					"name": "Background"
				}
			]
		},
		"typography": {
			"defaultFontSizes": false,
			"fluid": true,
			"fontFamilies": [
				{
					"fontFamily": "\"Inter\", -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
					"name": "Inter",
					"slug": "inter",
					"fontFace": [
						{
							"fontFamily": "Inter",
							"fontWeight": "400",
							"fontStyle": "normal",
							"src": [ "file:./assets/fonts/inter-regular.woff2" ]
						},
						{
							"fontFamily": "Inter",
							"fontWeight": "700",
							"fontStyle": "normal",
							"src": [ "file:./assets/fonts/inter-bold.woff2" ]
						}
					]
				}
			],
			"fontSizes": [
				{
					"slug": "small",
					"size": "0.875rem",
					"name": "Small"
				},
				{
					"slug": "medium",
					"size": "1rem",
					"name": "Medium"
				},
				{
					"slug": "large",
					"size": "1.5rem",
					"name": "Large"
				}
			]
		},
		"spacing": {
			"defaultSpacingSizes": false,
			"spacingSizes": [
				{
					"slug": "30",
					"size": "1rem",
					"name": "Small"
				},
				{
					"slug": "40",
					"size": "1.5rem",
					"name": "Medium"
				},
				{
					"slug": "50",
					"size": "2rem",
					"name": "Large"
				}
			],
			"units": [ "px", "rem", "vh", "vw", "%" ]
		},
		"layout": {
			"contentSize": "640px",
			"wideSize": "1200px"
		},
		"border": {
			"radius": true,
			"color": true,
			"style": true,
			"width": true
		}
	},
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--background)",
			"text": "var(--wp--preset--color--foreground)"
		},
		"typography": {
			"fontFamily": "var(--wp--preset--font-family--inter)",
			"fontSize": "var(--wp--preset--font-size--medium)",
			"lineHeight": "1.6"
		},
		"spacing": {
			"padding": {
				"top": "var(--wp--preset--spacing--50)",
				"right": "var(--wp--preset--spacing--50)",
				"bottom": "var(--wp--preset--spacing--50)",
				"left": "var(--wp--preset--spacing--50)"
			}
		},
		"elements": {
			"link": {
				"color": {
					"text": "var(--wp--preset--color--primary)"
				}
			},
			"heading": {
				"typography": {
					"fontWeight": "700",
					"lineHeight": "1.2"
				}
			}
		},
		"blocks": {
			"core/button": {
				"color": {
					"background": "var(--wp--preset--color--primary)",
					"text": "var(--wp--preset--color--background)"
				}
			}
		}
	},
	"customTemplates": [
		{
			"name": "page-no-title",
			"title": "Page Without Title",
			"postTypes": [ "page" ]
		}
	],
	"templateParts": [
		{
			"name": "header",
			"title": "Header",
			"area": "header"
		},
		{
			"name": "footer",
			"title": "Footer",
			"area": "footer"
		}
	]
}

<!-- wp:template-part {"slug":"header"} /-->

<main style="max-width: 1200px; margin: 0 auto; padding: 2rem; color: #333;">
	<h1 style="font-size: 32px; color: #0073aa;">Post Title</h1>
	<div style="font-size: 16px; line-height: 1.6;">
		<!-- wp:post-content /-->
	</div>
</main>

<!-- wp:template-part {"slug":"footer"} /-->

<!-- wp:template-part {"slug":"header","area":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
	<!-- wp:post-title {"level":1} /-->

	<!-- wp:group {"layout":{"type":"flex","flexWrap":"nowrap"}} -->
	<div class="wp-block-group">
		<!-- wp:post-author {"showAvatar":true} /-->
		<!-- wp:post-date /-->
	</div>
	<!-- /wp:group -->

	<!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

<div style="background: #ffffff; padding: 20px; border-bottom: 1px solid #cccccc;">
	<div style="max-width: 1200px; margin: 0 auto; display: flex; justify-content: space-between;">
		<h1 style="font-size: 24px; color: #0073aa;">Site Title</h1>
		<nav>Navigation</nav>
	</div>
</div>

<!-- wp:group {"align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|40","bottom":"var:preset|spacing|40"}}},"layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
	<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between","flexWrap":"nowrap"}} -->
	<div class="wp-block-group">
		<!-- wp:site-logo {"width":60} /-->
		<!-- wp:site-title {"level":0} /-->

		<!-- wp:navigation {"layout":{"type":"flex","orientation":"horizontal"}} /-->
	</div>
	<!-- /wp:group -->
</div>
<!-- /wp:group -->

{
	"version": 3,
	"styles": {
		"spacing": {
			"padding": {
				"left": "2rem",
				"right": "2rem"
			}
		}
	}
}

{
	"version": 3,
	"settings": {
		"useRootPaddingAwareAlignments": true
	},
	"styles": {
		"spacing": {
			"padding": "2rem"
		}
	}
}

{
	"version": 3,
	"settings": {
		"useRootPaddingAwareAlignments": true
	},
	"styles": {
		"spacing": {
			"padding": {
				"top": "var(--wp--preset--spacing--50)",
				"right": "var(--wp--preset--spacing--50)",
				"bottom": "var(--wp--preset--spacing--50)",
				"left": "var(--wp--preset--spacing--50)"
			}
		}
	}
}

{
	"version": 3,
	"settings": {
		"typography": {
			"fontSizes": [
				{ "slug": "small", "size": "14px" },
				{ "slug": "medium", "size": "16px" }
			]
		}
	}
}

{
	"version": 3,
	"settings": {
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [
				{ "slug": "small", "size": "0.875rem", "name": "Small" },
				{ "slug": "medium", "size": "1rem", "name": "Medium" }
			]
		},
		"spacing": {
			"defaultSpacingSizes": false,
			"spacingSizes": [
				{ "slug": "30", "size": "1rem", "name": "Small" }
			]
		}
	}
}

<?php
// Missing Title and Slug headers
?>
<!-- wp:cover -->
<div class="wp-block-cover">
	<h1>Welcome</h1>
</div>
<!-- /wp:cover -->

<?php
/**
 * Title: Hero Section
 * Slug: mytheme/hero
 * Categories: featured, banner
 * Keywords: hero, banner, header
 * Block Types: core/cover
 * Viewport Width: 1400
 * Description: Full-width hero section with heading and CTA
 */
?>
<!-- wp:cover {"url":"<?php echo esc_url( get_theme_file_uri( 'assets/images/hero.jpg' ) ); ?>","dimRatio":50,"align":"full","style":{"spacing":{"padding":{"top":"var:preset|spacing|60","bottom":"var:preset|spacing|60"}}}} -->
<div class="wp-block-cover alignfull">
	<span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span>
	<img class="wp-block-cover__image-background" alt="" src="<?php echo esc_url( get_theme_file_uri( 'assets/images/hero.jpg' ) ); ?>" data-object-fit="cover" />

	<div class="wp-block-cover__inner-container">
		<!-- wp:heading {"textAlign":"center","level":1} -->
		<h1 class="has-text-align-center"><?php echo esc_html_x( 'Welcome to Our Site', 'Pattern placeholder', 'mytheme' ); ?></h1>
		<!-- /wp:heading -->

		<!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
		<div class="wp-block-buttons">
			<!-- wp:button -->
			<div class="wp-block-button">
				<a class="wp-block-button__link wp-element-button"><?php echo esc_html_x( 'Get Started', 'Pattern placeholder', 'mytheme' ); ?></a>
			</div>
			<!-- /wp:button -->
		</div>
		<!-- /wp:buttons -->
	</div>
</div>
<!-- /wp:cover -->

{
	"settings": {
		"color": {
			"palette": [
				{ "slug": "background", "color": "#1a1a1a" }
			]
		}
	}
}

{
	"version": 3,
	"title": "Dark Mode",
	"settings": {
		"color": {
			"palette": [
				{
					"slug": "foreground",
					"color": "#ffffff",
					"name": "Foreground"
				},
				{
					"slug": "background",
					"color": "#1a1a1a",
					"name": "Background"
				},
				{
					"slug": "primary",
					"color": "#3dadff",
					"name": "Primary"
				}
			]
		}
	},
	"styles": {
		"color": {
			"background": "var(--wp--preset--color--background)",
			"text": "var(--wp--preset--color--foreground)"
		}
	}
}

<?php
function mytheme_setup() {
	add_theme_support( 'align-wide' );
	add_theme_support( 'custom-line-height' );
	add_theme_support( 'custom-spacing' );
	add_theme_support( 'editor-color-palette', array(
		array(
			'name'  => 'Primary',
			'slug'  => 'primary',
			'color' => '#0073aa',
		),
	) );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

<?php
/**
 * Theme setup and initialization
 */

defined( 'ABSPATH' ) || exit;

/**
 * Theme setup
 */
function mytheme_setup() {
	// Still valid in block themes
	add_theme_support( 'wp-block-styles' );
	add_theme_support( 'responsive-embeds' );
	add_theme_support( 'editor-styles' );

	// Load editor stylesheet
	add_editor_style( 'style.css' );

	// Internationalization
	load_theme_textdomain( 'mytheme', get_template_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'mytheme_setup' );

/**
 * Enqueue additional scripts (if needed)
 */
function mytheme_enqueue_assets() {
	// Only if theme needs custom JS
	if ( is_front_page() ) {
		wp_enqueue_script(
			'mytheme-interactions',
			get_theme_file_uri( '/assets/js/interactions.js' ),
			array(),
			wp_get_theme()->get( 'Version' ),
			true
		);
	}
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_assets' );

<?php
// functions.php in classic theme
function classictheme_setup() {
	add_theme_support( 'custom-logo' );
	add_theme_support( 'custom-header' );
	add_theme_support( 'custom-background' );
	add_theme_support( 'editor-color-palette', array(
		array( 'name' => 'Primary', 'slug' => 'primary', 'color' => '#0073aa' ),
	) );
	add_theme_support( 'editor-font-sizes', array(
		array( 'name' => 'Small', 'size' => 14, 'slug' => 'small' ),
	) );
}
add_action( 'after_setup_theme', 'classictheme_setup' );

{
	"version": 3,
	"settings": {
		"layout": {
			"contentSize": "640px",
			"wideSize": "1200px"
		},
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [
				{
					"slug": "small",
					"size": "0.875rem",
					"name": "Small"
				}
			]
		},
		"color": {
			"defaultPalette": false,
			"palette": [
				{
					"slug": "primary",
					"color": "#0073aa",
					"name": "Primary"
				}
			]
		}
	}
}

/*
Theme Name: My Child Theme
Description: A child theme
Author: Author Name
*/

/*
Theme Name: My Child Theme
Template: parent-theme-folder
Description: A child theme extending Parent Theme
Author: Author Name
Author URI: https://example.com
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-child-theme
*/

parent-theme/
├── parts/
│   └── header.html

child-theme/
├── style.css (with Template: parent-theme)
└── parts/
    └── header.html  ← Must match filename exactly to override

# WordPress Theme Review: my-theme

## Theme Type: Block Theme
**Detected:** templates/index.html + theme.json + style.css

## FILE: theme.json

### Line 2: WARNING - theme.json version 2 (upgrade to v3)
theme.json v2 still works but v3 is recommended for WP 6.6+. Breaking changes: defaultFontSizes and defaultSpacingSizes now default to true.

❌ **BAD:**
```json
{
	"version": 2
}

{
	"version": 3,
	"settings": {
		"typography": {
			"defaultFontSizes": false,
			"fontSizes": [ /* custom sizes */ ]
		}
	}
}

{
	"styles": {
		"spacing": {
			"padding": { "left": "2rem", "right": "2rem" }
		}
	}
}

{
	"settings": {
		"useRootPaddingAwareAlignments": true
	},
	"styles": {
		"spacing": {
			"padding": {
				"top": "2rem",
				"right": "2rem",
				"bottom": "2rem",
				"left": "2rem"
			}
		}
	}
}

<div style="max-width: 1200px; padding: 2rem;">

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">

<?php
function mytheme_setup() {

<?php
defined( 'ABSPATH' ) || exit;

function mytheme_setup() {

add_theme_support( 'editor-color-palette', array(
	array( 'name' => 'Primary', 'slug' => 'primary', 'color' => '#0073aa' ),
) );

// In theme.json:
{
	"settings": {
		"color": {
			"palette": [
				{ "slug": "primary", "color": "#0073aa", "name": "Primary" }
			]
		}
	}
}

/*
Theme Name: My Theme
Version: 1.0.0
Requires at least: 6.6
Tested up to: 6.7
Requires PHP: 7.4
*/

## Common Mistakes (THM-25)

Patterns that look like issues but are NOT problems:

| Pattern | Why It's NOT a Problem | Context |
|---------|------------------------|---------|
| **Block theme with minimal style.css** | Block themes use theme.json for styling, style.css is primarily metadata | Correct for block themes - style.css contains theme header, minimal CSS |
| **Classic theme without theme.json** | Classic themes work without theme.json, optional for block editor support | Valid classic theme - theme.json is optional for hybrid approach |
| **Hybrid theme with both index.php and theme.json** | Intentional pattern for incremental block editor adoption | Valid hybrid approach - theme.json enhances block editor, classic templates still work |
| **Template part without theme.json registration** | Template parts work by filename, registration is for UI labels only | Works correctly - registration enhances Site Editor UI but not required |
| **Style variation missing some settings sections** | Variations only need to override specific settings, not full schema | Intentional - variations merge with main theme.json |
| **Block template without template-part blocks** | Not all templates need header/footer, valid for custom layouts | Intentional for special templates (404, search results without chrome) |
| **functions.php with add_theme_support() in block theme** | Some add_theme_support() calls are still valid (wp-block-styles, responsive-embeds, editor-styles) | Valid - these can't be replaced by theme.json |
| **Pattern file with only static markup (no PHP)** | If pattern doesn't need dynamic values, static HTML is fine | Valid - PHP optional for static patterns |
| **Child theme without functions.php** | Child themes don't need functions.php if only overriding styles/templates | Valid minimal child theme - functions.php is optional |
| **Block theme without patterns/ directory** | Patterns are optional, not all themes need bundled patterns | Valid - themes can rely on WordPress.org pattern directory |
| **Missing viewScript in theme** | Themes typically don't need frontend JavaScript, unlike blocks | Expected - most themes are HTML/CSS only |
| **CSS variables in style.css referencing theme.json** | Correct usage - theme.json generates CSS variables that style.css can reference | Intentional integration between theme.json and style.css |

## Version Compatibility Reference

Quick reference for WordPress version requirements:

| Feature | WordPress Version | Notes |
|---------|-------------------|-------|
| Block themes (FSE) | 5.9+ | Full Site Editing stable release |
| theme.json v1 | 5.8+ | Initial theme.json support |
| theme.json v2 | 5.9+ | Expanded settings and styles options |
| theme.json v3 | 6.6+ | Breaking changes: defaultFontSizes and defaultSpacingSizes defaults |
| useRootPaddingAwareAlignments | 6.1+ | Full-width alignment with root padding |
| Template parts areas | 6.0+ | header, footer, uncategorized areas |
| fontFace support in theme.json | 6.0+ | Local font hosting via theme.json |
| Block theme patterns (patterns/) | 6.3+ | Auto-registration of PHP pattern files |
| Navigation block | 5.9+ | Replaces wp_nav_menu() in block themes |
| Site Editor | 5.9+ | Full Site Editing interface |
| Global Styles | 5.9+ | User customization of theme.json via UI |
| Style variations | 6.0+ | Alternate theme.json files in styles/ |

## Deep-Dive References

For advanced theme development patterns, load these companion reference documents:

| Task | Reference to Load |
|------|-------------------|
| theme.json v3 complete schema, all sections explained (settings, styles, templateParts, customTemplates, patterns), property catalog with valid values, v2→v3 migration notes, common mistakes, WordPress.org requirements | `references/theme-json-guide.md` |
| Template hierarchy for both classic and block themes side-by-side, template parts and areas, conditional tags, get_template_part() for classic, block markup in HTML templates, custom templates registration | `references/template-patterns.md` |
| Full Site Editing comprehensive guide: site editor workflow, global styles UI mapping to theme.json, style variations creation, block patterns in themes (patterns/ directory), navigation configuration, font management, layout system (contentSize, wideSize, root padding) | `references/fse-guide.md` |
| Step-by-step classic-to-block migration: functions.php → theme.json mapping table, template.php → template.html conversion, sidebar widgets → template parts, Customizer → global styles, add_theme_support → theme.json equivalents, incremental hybrid adoption path | `references/classic-to-block-guide.md` |

**Note:** Reference docs provide deep-dive content. This SKILL.md is self-sufficient for standard theme reviews.

**Security crossover:** When encountering security-relevant patterns (template escaping in classic themes, child theme security, sanitization in theme customizer), this skill provides brief reminders but defers to wp-security-review for comprehensive security analysis. For detailed security patterns, use `/wp-sec-review` command.

**Plugin crossover:** When encountering plugin-level patterns (functions.php hooks like after_setup_theme, wp_enqueue_scripts, init for CPT registration), this skill provides brief mentions but defers to wp-plugin-development for plugin architecture depth. For detailed plugin patterns, use `/wp-plugin-review` command.

**Block crossover:** When encountering block development patterns (block patterns registration in themes vs plugins, block markup in templates, block supports defined in theme.json), this skill provides brief context but defers to wp-block-development for block-specific depth. For detailed block patterns, use `/wp-block-review` command.