Base Theme
Developer Guide

Overview

Project identity and naming conventions for the base theme.

This WordPress starter theme is maintained by Enfection Labs. It is used as the foundation for all new client WordPress projects. The theme is generic by design — no client-specific code should exist in this repository.

Starting a New Client Project

When spinning up a new client site from this base:

1. Rename the function prefix from theme_ → {project}_ (e.g. acme_)
2. Update the text domain from base-theme → {project}
3. Replace all design tokens in sources/sass/abstract/_variables.scss
4. Swap in the client's Google Fonts in inc/enqueue.php
5. Update BrowserSync proxy in gulpfile.js line 54

Stack

Technologies and libraries bundled into every project.

Build & Setup

Commands to install dependencies and compile assets.

What Gulp does

• Compiles sources/sass/theme.scss → assets/css/theme.css (with sourcemaps in dev)
• Concatenates & minifies sources/js/**/*.js → assets/js/theme.js
• Reloads browser on file change via BrowserSync

Sass Architecture

sources/sass/theme.scss is the single Sass entry point. Load order matters.

Adding a New Page Template

Three files required every time:

1. Create page-templates/my-template.php
2. Create sources/sass/theme/_my-template.scss
3. Add @use "theme/my-template"; to sources/sass/theme.scss

<?php
/**
 * Template Name: My Template
 * @package Base_Theme
 */
defined( 'ABSPATH' ) || exit;
get_header();
// template output here
get_footer();

Adding a Single Post Type Template

Create single/single-{post_type}.php — WordPress's single.php routes to it automatically via the template hierarchy.

Design Tokens

All tokens live in sources/sass/abstract/_variables.scss — the single source of truth.

How It Works

The variables file defines named Sass variables. Sass maps are then derived from those variables and used to generate:

• CSS custom properties in _global.scss — e.g. --color-primary, --space-4, --bp-md
• Color utility classes in _colors.scss — e.g. .bg-primary, .text-secondary
• Font utility classes in _common.scss — e.g. .primary-font, .secondary-font

Spacing Scale

Colors

Defined in $colors map in _variables.scss. Generates .text-*, .bg-*, and .border-* utility classes automatically.

Changing a Color

// sources/sass/abstract/_variables.scss
$color-primary:   #132D51;    // ← change this
$color-secondary: #0a1628;
$color-surface:   #1e3a5f;

Breakpoints

Defined in $breakpoints map. Use the mixin in Sass, the CSS var in inline contexts.

Usage in Sass

// Mobile-first (min-width)
@include respond-to('md') {
  /* applies at ≥768px */
}

// Max-width (below a breakpoint)
@include respond-below('lg') {
  /* applies at <1024px */
}

Mixins

Defined in sources/sass/abstract/_mixins.scss. Use with @include.

Utility Functions

Defined in sources/sass/abstract/_functions.scss.

// In your SCSS
.hero-title {
  font-size: rem(48px);   // → 3rem
}

@include respond-to('xl') {
  .hero-title {
    font-size: get-vw(72px); // → 3.75vw (scales with viewport)
  }
}

Page Templates

Each page template lives in page-templates/ and is paired with a Sass file.

Template Checklist

1. Add the Template Name: docblock at the top of the PHP file
2. defined('ABSPATH') || exit; on line 1
3. Call get_header() and get_footer()
4. Create the paired Sass file and @use it in theme.scss

Single Post Type Templates

WordPress routes single-{post_type}.php automatically via the template hierarchy.

Create the file in the single/ directory:

// single/single-news_insight.php
<?php
defined( 'ABSPATH' ) || exit;
get_header();

if ( have_posts() ) :
  while ( have_posts() ) :
    the_post();
    // output single post content
  endwhile;
endif;

get_footer();

PHP Conventions

Standards to follow in all PHP files in this theme.

Escaping Examples

// Text content
echo esc_html( get_the_title() );

// URLs
echo esc_url( get_permalink() );

// Attributes
echo esc_attr( get_field( 'alt_text' ) );

// HTML (limited tags allowed)
echo wp_kses_post( get_the_content() );

ACF Fields

Advanced Custom Fields configuration for the global options page.

Options Page Fields

Getting an Options Field

$logo = get_field( 'theme_logo_header', 'option' );
if ( $logo ) {
  echo '<img src="' . esc_url( $logo['url'] ) . '" alt="' . esc_attr( $logo['alt'] ) . '">';
}

Nav Menus

Two menu locations registered in theme_setup().

wp_nav_menu( [
  'theme_location' => 'primary',
  'menu_class'     => 'nav-list',
  'container'      => false,
] );

Customizer Options

Available under Appearance → Customize in the WordPress admin.

$sticky = get_theme_mod( 'theme_sticky_header', false );
if ( $sticky ) {
  // add sticky class to header
}

Required Plugins

These plugins must be installed for full theme functionality.

New Project Kickstart

Step-by-step checklist for spinning up a new client project from this base theme.

1. Clone & Rename

1. Clone or copy this theme folder and rename it to {project}-theme
2. Find + replace all instances of theme_ with {project}_ across all PHP files
3. Find + replace text domain base-theme with {project}
4. Update style.css header: Theme Name, Description, Author, Version

2. Design Tokens

1. Open sources/sass/abstract/_variables.scss
2. Update all $color-* variables with client brand colors
3. Set $primary-font and $secondary-font to the project fonts
4. Add Google Fonts <link> tags to inc/enqueue.php

3. Build Setup

1. Run npm install to install Gulp dependencies
2. Edit gulpfile.js line 54: set proxy to your Local WP URL
3. Run gulp to start development

4. WordPress Setup

1. Activate the theme in WordPress admin
2. Install and activate ACF Pro and Classic Editor
3. Create the ACF options page fields (import JSON if available)
4. Create nav menus and assign them to primary and footer locations
5. Create pages and assign page templates

5. Page Templates

For each new page template needed on the project:

1. Duplicate an existing template in page-templates/
2. Update the Template Name: docblock
3. Create sources/sass/theme/_{name}-template.scss
4. Add @use "theme/{name}-template"; to sources/sass/theme.scss