Portfolio-2026/README.md

VDI WordPress Theme Starter v5

VDI WordPress Theme Starter v5 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/Vincent-Design-Inc/VDI-Starter-v5 AC Bug/Issue Tracking: https://next-app.activecollab.com/119590/projects/4553?modal=Task-98192-4553

Key Features

• Tailwind CSS v4 (CSS-first configuration, no tailwind.config.js)
• Namespaced PHP (BasicWP 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

VDI-Starter-v5/
├── acf/                            # ACF 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 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 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	BasicWP	All PHP files
Text domain	basicwp	WordPress translations
Block category	vdi-blocks	Groups blocks in the editor
Script module IDs	basicwp-theme, basicwp-button, basicwp-admin	JS module registration
WP Engine folder	vdi-v5	Deployment target
Theme directory	VDI-Starter-v5	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:

   composer install
   npm install
   

4. Copy .env.example to .env and set:

   • LOCALHOST_URL: Your local development URL (e.g., http://localhost:1000)
   • BROWSERSYNC_PORT: Port for BrowserSync (default: 5000)

5. Run the initial build:

   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 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.

License

MIT