WordPress Child Theme Development

This skill guides you through working with WordPress child themes using the blank template pattern. Child themes inherit all functionality from their parent while allowing selective customization.

Architecture Principles

Child Theme Pattern

theme.json Inheritance Strategy

WordPress automatically merges child theme.json with parent theme.json. The child theme should start **minimal** and only override specific settings when needed.

**Blank template approach**:

**What parent typically provides** (inherited by default):

Step-by-Step Instructions

1. Initial Setup

When starting work on a child theme:

1. Check if `composer.json` declares parent theme dependency

2. Run `composer install` to install dependencies

3. Verify parent theme location (commonly `~/code/parent-theme-name`)

4. Review child theme file structure:

- `theme.json` - Should be minimal

- `style.css` - Must have child theme header

- `functions.php` - Should only enqueue stylesheet

- `patterns/` - Custom block patterns

- `styles/` - Style variations

- `parts/` - Template part overrides

2. Adding Custom Colors

To override parent colors in the blank template:

1. Check parent theme's `theme.json` to see available color slugs

2. Add only colors you want to override to child `theme.json`:

```json

{

"$schema": "https://schemas.wp.org/trunk/theme.json",

"version": 3,

"settings": {

"color": {

"palette": [

{

"name": "Brand",

"slug": "primary",

"color": "#yourBrandColor"

}

]

}

}

}

```

3. Keep same color slugs for consistency (e.g., "primary", "main", "base")

4. Colors not overridden inherit parent defaults

3. Adding Custom Block Patterns

To add custom patterns:

1. Create pattern files in `patterns/` directory

2. To use parent theme categories, register them in `functions.php`:

```php

register_block_pattern_category('parent-theme/category-name', array(

'label' => __('Category Label', 'child-theme-textdomain')

));

```

3. WordPress automatically detects patterns in the `patterns/` directory

4. Adding Style Variations

To create style variations:

1. Create JSON files in `styles/` directory

2. Follow theme.json schema structure

3. Define custom color palettes or typography settings

4. WordPress automatically detects and lists them in Site Editor

5. Overriding Template Parts

To override parent template parts, create HTML files in `parts/`:

WordPress loads child theme parts first, falling back to parent if not found.

6. Code Quality Checks

Before committing changes, run:

```bash

PHP syntax check

composer lint

WordPress Coding Standards scan

composer wpcs:scan

Auto-fix WPCS issues

composer wpcs:fix

```

7. Syncing with Parent Theme Updates

When parent theme updates:

1. Locate parent theme directory (e.g., `~/code/parent-theme-name/`)

2. Compare `theme.json` files - only merge new features you want

3. **DO NOT** copy parent's entire theme.json - keep child minimal

4. Check parent `functions.php` for new features, but don't duplicate

5. Parent may have `inc/` directory with block extensions - child doesn't need this

Constraints & Important Notes

Example Usage

**User**: "Add a custom brand color to this child theme"

**Expected workflow**:

1. Read parent theme's `theme.json` to check existing color palette

2. Read child theme's `theme.json` to see current state

3. Add only the brand color override to child theme.json

4. Preserve minimal structure - don't copy other parent settings

5. Run `composer wpcs:scan` to verify code standards

**User**: "Override the footer template"

**Expected workflow**:

1. Check if `parts/` directory exists

2. Create `parts/footer.html` if it doesn't exist

3. Add custom footer HTML using WordPress block markup

4. Do not modify parent theme files

**User**: "Prepare this child theme for deployment"

**Expected workflow**:

1. Run `composer install` to ensure dependencies are up to date

2. Run `composer lint` to check PHP syntax

3. Run `composer wpcs:scan` to check WordPress coding standards

4. Fix any issues with `composer wpcs:fix` or manually

5. Verify `style.css` header has correct version number

6. Update `CHANGELOG.md` with changes