Architecture

Directory structure

Parent theme (core framework)

wage/
├── functions.php              # Loads bootstrap
├── style.css                  # Theme header
├── index.php                  # Required fallback
└── inc/core/
    ├── bootstrap.php          # Theme setup, asset loading, WP cleanup
    ├── flags.php              # Feature flags (wireframe, components, etc.)
    ├── components.php         # Reusable PHP component functions (wage_*)
    ├── seo.php                # SEO engine
    ├── forms.php              # Form handler (spam, validation, email, storage)
    ├── styleguide.php         # Built-in dashboard (style guide, components, SEO)
    └── css/
        ├── tokens.css         # Default design tokens (neutral defaults)
        └── core.css           # Reset, structural layout, component skeletons

Child theme (per client)

wage-{client}/
├── style.css                  # Theme header with Template: wage
├── functions.php              # Project setup (fonts, forms, API keys)
├── header.php                 # Site header
├── footer.php                 # Site footer
├── front-page.php             # Homepage template
├── page-*.php                 # Page templates
├── assets/
│   ├── css/tokens.css         # Brand tokens (overrides parent defaults)
│   └── css/site.css           # ALL visual styling
├── assets/js/main.js          # Project JS
├── inc/
│   ├── wage-components.php    # Project-specific components (can override core)
│   └── seo-data.php           # Project SEO data
├── data/                      # Protected file storage
├── CLAUDE.md                  # Project instructions
└── SETUP.md                   # New project checklist

Key paths

Constant / Function	Points to
get_template_directory() / WAGE_CORE_DIR	Parent theme (core)
get_stylesheet_directory() / WAGE_CHILD_DIR	Child theme (project)
WAGE_IS_CHILD	true when a child theme is active

CSS load order

Assets load in this order so that overrides cascade correctly:

1. wage-tokens — inc/core/css/tokens.css (neutral defaults)
2. wage-core — inc/core/css/core.css (framework structural styles)
3. {client}-tokens — assets/css/tokens.css (brand overrides)
4. {client}-site — assets/css/site.css (all visual styling)

PHP load order

require_once .../inc/core/components.php;   // wage_* functions
require_once .../inc/wage-components.php;    // project overrides

The child’s wage-components.php loads before core checks function_exists(), so project overrides take priority automatically.

Rules

• Never put project-specific code in the parent theme. It gets shared across all sites.
• Core CSS is structural only. All visual styling lives in the child’s site.css.
• All wage_* functions use function_exists() guards so child themes can override them.
• Child’s wage-components.php loads before core so overrides work automatically.

Updating core

Push changes to the parent theme repo. Pull on each server. Child themes are unaffected — they inherit the updated core.