Archives: Onboarding Lessons

WP Rig includes a highly advanced, pre-packaged directory of **AI Skills** inside its long-term memory configuration (`.ai/skills/`). These skill files provide specialized, localized instructions that teach AI assistants how to write bug-free code matching WP Rig’s coding standards.

In this lesson, we will explore the **Top 5 Handiest AI Skills** available inside WP Rig.

🚀 The Top 5 AI Skills

1. The Styles & Breakpoints Skill (`skills/styles/`)

2. The Gutenberg Block Development Skill (`skills/gutenberg-blocks/`)

3. The PHP Filters & Hooks Skill (`skills/php-filters/`)

4. The WP-CLI Automation Skill (`skills/wp-cli/`)

5. The Testing & Pre-Flight Standards Skill (`skills/code-quality-standards/`)

How to Trigger AI Skill Loading

If your AI coding client (such as Cursor or VS Code) supports workspace indexing: 1. Reference the skill file path directly in your prompt chat (e.g., typing `@SKILL.md` or linking `.ai/skills/styles/SKILL.md`). 2. Use explicit directive statements in your prompt, e.g.: *”Please read `.ai/skills/php-filters/SKILL.md` before refactoring this action hook.”*

By loading these localized guidelines, your AI coding assistant stays aligned with WP Rig’s high-performance architectural patterns, saving you hours of troubleshooting!

When developing block themes or hybrid layouts in WP Rig, you must understand standard Gutenberg engineering practices.

In this lesson, we will explore managing Full Site Editing (FSE) theme style variations, registering block styles, and authoring custom React blocks.

1. Theme Style Variations (`/styles`)

WordPress FSE themes allow you to offer multiple pre-packaged color and typography schemes. These are known as **Style Variations**.

Creating a Style Variation

2. Managing Custom Block Styles & Variations

You can extend existing core WordPress blocks without building complete custom blocks from scratch.

Custom Block Styles

register_block_style(
    'core/button',
    array(
        'name'         => 'dotted-border',
        'label'        => __( 'Dotted Border', 'wp-rig' ),
        'inline_style' => '.is-style-dotted-border { border: 2px dashed var(--color-primary); }',
    )
);

Custom Block Variations

3. Authoring Custom React Blocks

For complex custom elements requiring advanced frontend behavior, authoring custom React-based Gutenberg blocks is necessary.

Scaffolding a React Block

Example: A Minimal `edit.js`

export default function Edit( { attributes, setAttributes } ) { const blockProps = useBlockProps(); return (

Example: A Minimal `save.js`

export default function Save( { attributes } ) { const blockProps = useBlockProps.save(); return (

By mastering these block layout approaches, you can build visually stunning editorial designs that remain highly customizable for site authors!

WP Rig is an exceptional starter boilerplate for parent themes, but it is also fully optimized for **Child Theme Development**.

In this lesson, you will learn how to leverage the automated `childify` command to create lightweight child themes that inherit parent functionality while keeping WP Rig’s high-efficiency build pipeline!

1. What is WP Rig "Childification"?

In standard WordPress setups, developing a child theme manually means setting up a new folder, writing a `style.css` header referencing the parent, and enqueuing parent styles in PHP. While simple, you lose access to modern CSS, Javascript, and block compilers for your custom child styles.

WP Rig resolves this by incorporating a dedicated **childify** script.

When you run childify, WP Rig: * Converts your active development workspace into an optimized child theme configuration. * Enforces template inheritance in `functions.php`. * Keeps all source folders (`assets/css/src/`, `assets/js/src/`) and **compiler setups (Bun / Lightning CSS)** active locally.

This allows you to write optimized CSS/JS on top of any parent theme (like Twenty Twenty-Five) while letting WP Rig build, compile, and bundle your child theme files dynamically!

2. Running the Childify Script

To convert your WP Rig theme into a lightweight child theme, execute the following steps in your terminal:

1. Set the Parent Theme Variable

{
  "theme": {
    "parent": "twentytwentyfive"
  }
}

2. Run the Command

3. Review the Script Execution

3. Developing inside a Child Theme

Once childified: 1. **Write Styles Globally:** Add custom styles to `assets/css/src/global.css` or specific block style overrides. 2. **Run Dev Compilers:** Run `npm run dev` to watch child changes and inject them into your local browser window. 3. **Bundle child Theme:** When ready for production deployment, run `npm run bundle` to output an optimized, directory-ready child theme zip archive!

WP Rig’s PostCSS compilation pipeline enables you to write highly structured, modern CSS with powerful design capabilities out of the box.

In this lesson, you will learn how to use pre-defined custom media queries, build an integrated dark mode, and reference theme image assets dynamically inside your stylesheets.

1. Custom Media Queries

Instead of repeating complex, error-prone pixel values inside media queries (e.g., `@media (max-width: 768px)`), WP Rig uses standard-compliant **Custom Media Queries**.

Breakpoints Definition

Usage inside Stylesheets

@media (–medium-query) { .card { width: 50%; } } “`

2. Dynamic Theme Image Referencing in CSS

Referencing images inside your CSS files is notoriously brittle in WordPress because theme URLs change based on site environments. WP Rig provides a custom PostCSS function helper to resolve theme image URLs dynamically!

How to Reference Dynamic Images

3. Built-In Dark Mode Capabilities

Providing a dark mode ensures premium, accessible visual designs. You can implement dark mode easily using native CSS custom properties.

System-Based Dark Mode

“`css :root { –color-bg: #ffffff; –color-text: #1a202c; –color-primary: #3182ce; }

@media (prefers-color-scheme: dark) { :root { –color-bg: #1a202c; –color-text: #f7fafc; –color-primary: #63b3ed; } } “`

Class-Based Toggle

body.dark-mode {
    --color-bg: #1a202c;
    --color-text: #f7fafc;
    --color-primary: #63b3ed;
}

By leveraging these built-in CSS capabilities, your design remains modern, fast, and fully responsive across all device sizes and color preferences!

Performance and optimization are core pillars of WP Rig. In this lesson, we will explore how WP Rig handles automatic image compression and how to configure privacy-first, locally-hosted web fonts.

1. Automatic Image Compression via `sharp`

High-resolution images are the biggest contributor to slow page weights and poor Core Web Vitals. WP Rig resolves this by integrating **sharp** — an extremely fast, high-performance Node.js image processing library powered by `libvips`.

How the Pipeline Works

During builds or development watch runs, WP Rig automatically: 1. **Compresses & Minifies:** Compresses image sizes while preserving visual quality. 2. **Performs Lossless Auditing:** Truncates metadata profiles and converts assets. 3. **Generates Optimized Output:** Outputs compressed images straight to `assets/images/` as production-ready artifacts.

Triggers

2. Privacy-First Google Fonts Integration

Loading fonts directly from Google’s CDNs (`fonts.googleapis.com`) violates GDPR compliance regulations and triggers external network connection delays. WP Rig uses a **locally-hosted, privacy-first font loader**.

The Font Downloading Engine

How to Configure Custom Fonts

By serving your images and web fonts locally from your host server, you guarantee maximum performance, perfect GDPR compliance, and sub-second page rendering!

In this final lesson, we will explore the underlying configuration parameters that define WP Rig’s development behaviors, design tokens, and production bundler.

1. Customizing Theme Meta

Under `config/config.json`, you define configuration settings that govern the overall theme name, directories, and assets:

{
  "theme": {
    "slug": "excalibur",
    "name": "Excalibur Theme",
    "author": "My Web Studio"
  }
}

During initialization or compilation, WP Rig dynamically parses this file to: * Perform global search-and-replace naming operations across files. * Update theme directory names. * Write appropriate comments and standard style metadata headers inside `style.css`.

2. Managing Design Tokens

WP Rig integrates design configurations inside `config/tokens.json` (or standard `theme.json`). This centralized file controls: * **Typography:** Registering custom web fonts, defining font weights, line-height scales, and letter spacing values. * **Colors:** Specifying your brand color palettes, theme backgrounds, and gradients. * **Layout Grid:** Declaring custom widths, gutter sizes, margins, and section padding systems.

By updating your properties inside this JSON index, your style compilers automatically lower these settings into **CSS Custom Properties** (`var(–color-primary)`) globally, allowing you to re-brand the theme visually in seconds!

3. Bundling for Production

Once development is complete and you are ready to upload your theme to a live staging or production environment, run:

npm run bundle

This command triggers a comprehensive production compilation sequence: 1. Compiles, minifies, and prefixes all CSS and Javascript source files, deleting source folders inside the production build. 2. Compresses and optimizes theme images (SVG, PNG, JPG). 3. Performs strict security checks on PHP classes. 4. Generates a clean, production-ready zip archive under `/artifacts/` named `[theme-slug].zip`.

You can upload this zip file directly to any production WordPress site via the native installer!

🎉 Congratulations!

You have successfully completed the WP Rig v3 onboarding curriculum!

You are now equipped with the advanced knowledge required to build lighting-fast, standards-compliant, and AI-accelerated block-enabled themes. Keep this guide bookmarked for quick command lookups, and happy theme coding!

WP Rig excels at providing pre-configured structures, but its true power lies in its modular extensibility. In this lesson, we will explore generating custom OOP PHP components and developing modern, zero-JS custom Gutenberg blocks.

1. Generating Custom PHP Components

Every core feature in WP Rig (Styles, Fonts, sidebars, Menus) is organized into a modular **Component** class under `inc/`.

To create a new custom PHP feature (for example, registering a custom post type or third-party API tracker), do not write procedural code in `functions.php`. Instead, generate a new component!

Generate via CLI

“`php namespace WP_RigWP_RigMy_Tracker;

use WP_RigWP_RigComponent_Interface;

class Component implements Component_Interface { public function get_slug(): string { return ‘my-tracker’; } public function initialize(): void { add_action( ‘init’, array( $this, ‘register_hooks’ ) ); } public function register_hooks(): void { // Your OOP Hook Logic Here } } “`

WP Rig’s core theme bootstrap automatically registers this class on boot, keeping your theme modular, organized, and trace-friendly!

2. Developing Custom Blocks

WP Rig includes a built-in block scaffolding engine that makes block development extremely simple.

Traditional React-based Block

WordPress 7.0 PHP-Only Block (Zero JS)

3. Server-Side Block Manifest Compilation

Registering blocks individually via filesystem directory scanning can degrade site speeds on every page hit. To optimize performance, WP Rig v3 uses a pre-compiled **Block Manifest** (`assets/blocks/blocks-manifest.php`).

When you compile your blocks: “`bash npm run build:blocks “` WP Rig scans all configurations and writes them into a unified, memory-cacheable PHP array, loading custom blocks near-instantaneously!

In our final lesson, we will master the layered configuration parameters and tokens to customize your theme designs!