Theme Configuration

Everything WP Rig does — asset compilation, paradigm gating, design tokens, exports — is driven by a small set of JSON files in the config/ directory. There is no hidden state: change a config value, rebuild, and every dependent artifact follows.

The configuration chain

WP Rig merges three config files in a fixed order. Later files win:

config/config.default.json   →   config/config.json   →   config/config.local.json

config.default.json is the complete set of defaults shipped with the framework — read it as the reference documentation for every available option. config.json is your project’s version-controlled overrides: theme identity, paradigm, token preferences. config.local.json is gitignored personal-machine state (local dev URLs, credentials) that should never reach the repository.

The merge is deep: objects merge key-by-key, so you only override what you need. One exception to remember: rig-init strips the paradigm keys (theme.themeType, theme.enableBlocks) from config.local.json on every run so your interactive choice is always authoritative.

Theme identity settings

The theme section defines your theme’s identity and paradigm:

// config/config.json
{
  "theme": {
    "slug": "my-theme",
    "name": "My Theme",
    "author": "Your Name",
    "PHPNamespace": "My_Theme",
    "themeType": "universal"
  }
}

slug, name, author, and PHPNamespace are stamped into style.css, file headers, and the PHP namespace at bundle time — set them before you start building. themeType selects the paradigm (classic, universal, or block-based) and gates every paradigm-dependent feature in both the build and the runtime. See Theme Paradigms for the full matrix.

The framework version is tracked separately in config/framework.json and never ships with a built theme; your theme’s own version lives in theme.version.

Paradigm and feature gating

The tag → theme-type matrix lives in config/paradigms.json. You rarely edit it — it exists so that build scripts (scripts/lib/paradigm.js) and the PHP runtime (inc/Paradigm.php) resolve features from a single source of truth. Block-era features (block patterns, _blocks-based.css, rig:bake) are active only when themeType is universal or block-based and never ship in the classic core.

Design tokens

Colors, typography, spacing, and breakpoints come from config/tokens.json (layered: primitives → semantic light/dark → component). The theme.designTokens config controls how tokens are emitted:

{
  "theme": {
    "designTokens": {
      "enabled": true,
      "colorBinding": "auto",
      "legacyAliases": false,
      "emit": {
        "tailwind": false
      },
      "contrast": {
        "level": "AA",
        "onFail": "warn"
      }
    }
  }
}

colorBinding (independent, wp-preset, or auto) decides whether semantic tokens alias WordPress preset variables — paradigm-aware, and classic themes never emit preset references. emit.tailwind opts into generating a Tailwind config. contrast runs a WCAG gate over your palette. Run npm run rig:tokens to regenerate theme.json and CSS custom properties after edits.

Development settings

The dev section controls the local build:

{
  "dev": {
    "browserSync": {
      "live": true,
      "proxyURL": "wprig.test:8888",
      "bypassPort": "8181",
      "https": false,
      "devPort": 3000
    },
    "styles": {
      "stage": 3,
      "features": {
        "mobile-nav-type": "modern"
      }
    },
    "debug": {
      "styles": false,
      "scripts": false,
      "phpcs": true
    }
  }
}

browserSync.live enables live reload during npm run dev; proxyURL points at your local WordPress install. The debug flags skip minification and control whether PHPCS runs during the build. Note that the dev server itself is npm-script based — WP Rig v3 removed Gulp and the old BrowserSync gulp integration.

Export, child themes, and patterns

export controls the production bundle (zip creation, .pot file generation, files copied into the package). child configures child theme conversion (npm run setup-child — paradigm-aware, and it strips framework metadata from the shipped child). patterns.categories seeds the block pattern categories registered for universal and block-based themes.

config.local.json — local only

Anything machine-specific goes here: a different proxyURL for a colleague’s machine, temporary debug flags, experimental paradigm choices while evaluating a switch. It is gitignored by default and its overrides win over config.json — which is exactly why rig-init keeps the paradigm keys inside it clean.

Pair this document with Theme Paradigms (how themeType gates features), CSS in WP Rig (the token pipeline), and WP Rig Node Scripts (every build command that reads this config).