Theme Development

Building WordPress themes with the Wikit framework, modern build tools, and best practices.

Quick Start

Themes live inside a project's repositories. Project subcommands route project-first (wdg <project> <command>), so you operate on a theme through its project:

# Start dev mode for the project (npm start with file watching)
wdg my-site dev

# Build production assets
wdg my-site build

# Lint PHP with PHPCS
wdg my-site lint

# Static analysis with PHPStan
wdg my-site analyze

There is no wdg theme command family. Theme work is driven through the project-scoped dev, build, lint, and analyze commands plus the npm scripts inside the theme repository.

Theme Structure

A Wikit-based project theme uses a src/ (PSR-4) + block-editor/ + assets/ layout. The block-editor directory holds Gutenberg block sources, and compiled output lands in dist/.

my-site-theme/
├── style.css              # Theme header (required)
├── functions.php          # Theme bootstrap
├── index.php              # Main template
├── composer.json          # PSR-4 autoload (WDG\Theme\)
├── package.json           # Node dependencies and build scripts
├── webpack.config.js      # Build configuration
├── phpcs.xml              # PHPCS ruleset
├── src/                    # PHP source (PSR-4: WDG\Theme\)
├── block-editor/           # Gutenberg block sources
│   ├── blocks/            # Custom block definitions
│   ├── components/        # Shared editor components
│   ├── filters/           # Editor filters
│   ├── formats/           # Rich-text formats
│   ├── hooks/             # Editor hooks
│   └── plugins/           # Editor plugins
├── assets/                # Static source assets
│   ├── js/
│   ├── scss/
│   └── images/
└── dist/                  # Compiled assets (generated)

Theme Header (style.css)

/*
Theme Name: My Site Theme
Theme URI: https://example.com
Author: WDG Development Team
Author URI: https://wdg.com
Description: Custom WordPress theme built on Wikit framework
Version: 1.0.0
License: Proprietary
License URI: #
Text Domain: my-site-theme
*/

functions.php

<?php
/**
 * My Site Theme bootstrap
 *
 * @package WDG\Theme
 */

namespace WDG\Theme;

// Theme setup
function setup() {
    add_theme_support('title-tag');
    add_theme_support('post-thumbnails');
    add_theme_support('html5', ['search-form', 'comment-form', 'gallery', 'caption']);
    add_theme_support('custom-logo');

    register_nav_menus([
        'primary' => __('Primary Menu', 'my-site-theme'),
        'footer'  => __('Footer Menu', 'my-site-theme'),
    ]);

    add_image_size('hero', 1920, 1080, true);
    add_image_size('thumbnail-large', 600, 400, true);
}
add_action('after_setup_theme', __NAMESPACE__ . '\\setup');

// Enqueue compiled assets
function enqueue_assets() {
    wp_enqueue_style(
        'my-site-theme-style',
        get_template_directory_uri() . '/dist/style.css',
        [],
        wp_get_theme()->get('Version')
    );

    wp_enqueue_script(
        'my-site-theme-script',
        get_template_directory_uri() . '/dist/main.js',
        [],
        wp_get_theme()->get('Version'),
        true
    );

    wp_localize_script('my-site-theme-script', 'themeData', [
        'ajaxUrl' => admin_url('admin-ajax.php'),
        'nonce'   => wp_create_nonce('my-site-theme-nonce'),
    ]);
}
add_action('wp_enqueue_scripts', __NAMESPACE__ . '\\enqueue_assets');

Development Workflow

1. Start Development Mode

wdg my-site dev

This runs the theme's npm start (with prestart), which watches source files, compiles SCSS, and bundles JavaScript. You can also run the npm scripts directly from inside the theme repository:

cd projects/my-site/repositories/my-site-theme
npm run watch     # Watch JS and CSS together
npm run scss      # Compile SCSS once

2. Make Changes

Edit source files:

• block-editor/ - Gutenberg block sources (TypeScript/JS)
• assets/js/ - JavaScript
• assets/scss/ - Sass stylesheets
• src/ - PHP source (PSR-4 WDG\Theme\)

Changes rebuild on save while dev/watch is running.

3. Build for Production

wdg my-site build

This runs the theme's npm run build (with prebuild), producing optimized assets in dist/.

Asset Management

JavaScript

// assets/js/main.js
import Navigation from './components/navigation';
import Slider from './components/slider';

document.addEventListener('DOMContentLoaded', () => {
    new Navigation();
    new Slider('.hero-slider');
});

Sass/SCSS

// assets/scss/style.scss
@import 'variables';
@import 'mixins';
@import 'base/reset';
@import 'base/typography';
@import 'layout/header';
@import 'layout/footer';
@import 'components/buttons';

body {
    font-family: $font-primary;
    color: $color-text;
    background: $color-bg;
}

Working with Blocks

Wikit blocks live in the framework; project block sources live in the theme's block-editor/blocks/ directory. To discover available Wikit blocks and their attributes, use the MCP search tools (in Claude):

• search_wikit_blocks("hero") - find blocks by name or concept
• get_block_schema("...") - inspect a block's attributes and schema

Code Quality

PHP Linting (PHPCS)

# Lint the project theme
wdg my-site lint

# Auto-fix violations (PHPCBF)
wdg my-site lint --fix

# Summary report only
wdg my-site lint --summary

# Limit by severity, or include plugins
wdg my-site lint --severity=5
wdg my-site lint --include-plugins

Static Analysis (PHPStan)

# Run PHPStan inside the project container
wdg my-site analyze

# Override the level, regenerate the baseline, or include plugins
wdg my-site analyze --level=5
wdg my-site analyze --baseline
wdg my-site analyze --include-plugins

Browser Testing

Use the Chrome DevTools MCP tools (in Claude) for automated browser testing, screenshots, and Core Web Vitals analysis against https://my-site.localhost:6443.

PHP Versions

# Show the project's current PHP version
wdg my-site php

# Change PHP version (rebuilds the container)
wdg my-site php set 8.3

Best Practices

1. Use Wikit Blocks - Leverage existing blocks before creating custom ones
2. Mobile-First - Design for mobile, enhance for desktop
3. Accessibility - Follow WCAG guidelines
4. Performance - Optimize images, lazy load, minimize JS
5. Security - Escape output, sanitize input, use nonces

---

See Also:

• Wikit Framework
• Development Workflow
• Debugging