SoloFrame Evo is a minimal WordPress theme designed as a starting point for custom theme development. It focuses on modern development approaches with a lean architecture that avoids the overhead of theme frameworks.

Repo: https://github.com/ksolomon/SoloFrame-Evo

Key Features

Tailwind CSS v4 (CSS-first configuration, no tailwind.config.js)
Namespaced PHP (SoloFrameEvo namespace) for isolation
Built-in support for ACF blocks with auto-registration
Fast development workflow with BrowserSync live reload
WordPress 6.5+ script modules for modern JS loading
Automated theme activation (plugin installs, page creation, settings)

Documentation

Guide	Description
Getting Started	Setup from zero, local WordPress, environment config, troubleshooting
Architecture	Bootstrap flow, layers, namespace conventions, hooks, enqueue system, theme.json
Creating Blocks	Step-by-step ACF block creation tutorial with examples
Reference	Hooks/filters, design tokens, CSS architecture, JS modules, CLI commands, deployment

Project Structure

SoloFrame-Evo/
├── acf/                            # ACF/SCF field group JSON definitions
├── bin/                            # Build scripts (.build.js, .watch.js, .utils.js)
├── content/                        # Sample page and post content for testing
├── docs/                           # Documentation guides
├── lib/                            # PHP library files
│   ├── activation.php              # Theme activation handler (plugins, pages, settings)
│   ├── class-acf.php               # ACF/SCF integration (JSON sync paths)
│   ├── class-breadcrumbs.php       # Breadcrumb generation with Schema.org markup
│   ├── class-enqueue.php           # Assets enqueuing (CSS, JS, fonts)
│   ├── class-menuitems.php         # Navigation menu builder
│   ├── class-resources.php         # Custom Resources post type
│   ├── extras.php                  # Sidebar, page header, Owner role, embed wrapper
│   ├── helpers.php                 # Utility functions and globals ($theme, $views)
│   ├── hooks.php                   # WordPress hooks, filters, and cleanup
│   ├── search-features.php         # Enhanced search functionality
│   └── show-template.php           # Debug: shows active template in HTML comment
├── static/
│   ├── dist/                       # Compiled assets (theme.css)
│   └── js/                         # JavaScript files
│       ├── components/             # JS custom elements (button, backToTop)
│       ├── modules/                # JS theme modules (Navigation, GetHeaderHeight, TagExternalLinks)
│       ├── admin.js                # Admin-specific JS
│       └── theme.js                # Main theme JS (entry point)
├── styles/                         # CSS styles
│   ├── backend/                    # Admin and editor styles
│   ├── base/                       # Base styles (typography, colors, forms, etc.)
│   ├── blocks/                     # Block-specific styles
│   ├── components/                 # Component styles (breadcrumbs, pagination, etc.)
│   ├── fonts/                      # Icon font styles (Lineicons)
│   ├── navigation/                 # Navigation styles (default, mega, accordion, sliding)
│   └── theme.css                   # Main CSS entry point (Tailwind + imports)
├── tests/                          # Automated Playwright tests
│   └── site-a11y.spec.js           # Site Accessibility tests
├── views/                          # Template views
│   ├── blocks/                     # Custom ACF/SCF blocks (accordion, button, grid, section, etc.)
│   ├── icons/                      # SVG icon templates
│   ├── forms/                      # Form templates (search)
│   └── partials/                   # Reusable template parts (page-hero, social-media)
├── 404.php                         # 404 error template
├── footer.php                      # Footer template
├── front-page.php                  # Front page template
├── functions.php                   # Main functions file (autoloads lib/)
├── header.php                      # Header template
├── index.php                       # Main template
├── page.php                        # Page template
├── search.php                      # Search results template
├── sidebar.php                     # Primary sidebar template
├── sidebar-page.php                # Page sidebar template
├── single.php                      # Single post template
├── style.css                       # Theme metadata
├── theme.json                      # Block editor design system (colors, fonts, spacing)
└── whitelist.php                   # Tailwind class whitelist for editor-only classes

Namespace Conventions

The project uses several naming conventions. Here's how they relate:

Convention	Value	Where Used
PHP namespace	`SoloFrameEvo`	All PHP files
Text domain	`sf-evo`	WordPress translations
Block category	`sf-blocks`	Groups blocks in the editor
Script module IDs	`sf-evo-theme`, `sf-evo-button`, `sf-evo-admin`	JS module registration
WP Engine folder	`<change-me>>`	Deployment target
Theme directory	`SoloFrame-Evo`	Git repo name

Included Blocks

Block	Purpose
Accordion	Collapsible content sections
Buttons	Container for Button blocks
Button	Configurable button element (`<x-button>` custom element)
Contact Info	Contact information display
Grid	Flexible grid layout (restricts children to Grid Cell)
Grid Cell	Individual grid item
Homepage Hero	Hero section for the front page
Media Text	Image or video with accompanying text
Media Text with Inner Blocks	Media-text with nested block support
Page Children	Displays child pages of current page
Section	Container with background and width options

Development

Setup

Create a new repo using this one as a template.
Clone the repo to your local dev folder.
Install dependencies:
```
composer install
npm install
```
Copy .env.example to .env and set:
- LOCALHOST_URL: Your local development URL (e.g., http://site-dev.local)
- BROWSERSYNC_PORT: Port for BrowserSync (default: 5000)
Run the initial build:
```
npm run build
```
Activate the theme in WordPress admin.

Warning: Theme activation automatically installs plugins, creates pages, and modifies WordPress settings. See Getting Started for details.

Development Server

Run npm run start or npm run watch to start the development server with live reloading.
Changes to PHP, CSS, and JS files trigger automatic reload.

Production Build

Run npm run build to compile and optimize CSS for production.
This is normally handled by GitHub Actions during deployment.

Deployment

Deployment to WP Engine is handled via GitHub Actions.
Update .github/workflows/wpengine.yml with the correct WP Engine deployment configuration.

Testing

Accessibility

Tests use Playwright and Axe:

Run via the VSCode Playwright extension or npx playwright test --ui
Test file: tests/site-a11y.spec.js

PHP Code Standards

Run composer lint to check PHP files against WordPress coding standards.
Results are saved to phpcs-results.txt.
Auto-fix with composer fix.