Portfolio-2026/README.md

# SoloFrame Evo

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](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](docs/getting-started.md) | Setup from zero, local WordPress, environment config, troubleshooting |
| [Architecture](docs/architecture.md) | Bootstrap flow, layers, namespace conventions, hooks, enqueue system, theme.json |
| [Creating Blocks](docs/creating-blocks.md) | Step-by-step ACF block creation tutorial with examples |
| [Reference](docs/reference.md) | Hooks/filters, design tokens, CSS architecture, JS modules, CLI commands, deployment |

## Project Structure

```plain
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

1. Create a new repo using this one as a template.
2. Clone the repo to your local dev folder.
3. Install dependencies:

   ```bash
   composer install
   npm install
   ```

4. 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`)

5. Run the initial build:

   ```bash
   npm run build
   ```

6. Activate the theme in WordPress admin.

> **Warning:** Theme activation automatically installs plugins, creates pages, and modifies WordPress settings. See [Getting Started](docs/getting-started.md#theme-activation-warning) 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](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) 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`.