- Block Showcase: Powerful development tool (admin-only) to discover, preview, and inspect all registered blocks with their attributes in an organized, interactive format.
- Template-specific style loading: Template and CPT CSS are built separately and enqueued only when the current request matches (404, search, archive, page templates, custom post types). Styles in
build/css/templates/are discovered automatically—no PHP config needed. Reduces unused CSS for better Lighthouse scores. - Automatic cache versioning: All theme-built CSS and JS use file modification time as the version query string so caches update after each build without manual version bumps.
- Lighthouse script: Run
npm run lighthouseto audit Performance, Accessibility, Best Practices, and SEO for mobile and desktop; scores printed in the terminal only. URL via prompt or CLI argument. - Dominant Color Images: Automatic calculation and storage of dominant colors for uploaded images, used as placeholders while images load.
- Image Prioritizer: Automatically prioritizes above-the-fold images with fetchpriority="high" for improved page load performance.
- WebP Uploads: Automatically generates WebP versions of uploaded JPEG and PNG images for better compression and faster loading.
- ESLint 9 Migration: Upgraded to ESLint 9 with flat config format for modern JavaScript linting.
Table of Contents
WDS BT is a foundational WordPress block theme designed for maximum flexibility and customization. It integrates seamlessly with the native WordPress block editor, providing an intuitive and adaptable user experience. WDS BT is specifically developed as a foundational rather than parent theme, giving developers a clean and versatile base for advanced customizations.
| Feature | Description |
|---|---|
| Native Block Support | Built for native WordPress blocks and site editor integration. |
| Responsive Design | Ensures optimal display and functionality across devices. |
| Foundation Theme | Flexible base theme optimized for extensive customization. |
| Automated Code Quality | Modern linting configurations with PHP 8.3 compatibility, ESLint 9 flat config, WordPress coding standards, and automated quality checks. |
| Cross-Platform PHP Support | Automatic PHP binary detection and extension handling for Mac, Linux, and CI/CD environments. |
| Third-party Block Style Overrides | Conditionally enqueue and override third-party block styles for efficient asset delivery. |
| Accessibility Compliance | Built-in WCAG 2.2 compliance with automated Pa11y checks. |
| Enhanced Webpack Configuration | Refined Webpack setup for improved dependency resolution and optimized asset management. |
| Block Creation Script Enhancements | Options for static, dynamic, or interactive blocks; automatically includes view.js for rendering. |
| Block Showcase | Development tool to discover, preview, and inspect all registered blocks with their attributes. |
| Dominant Color Images | Automatic dominant color calculation for images, used as background placeholders during image loading. |
| Image Prioritizer | Automatically prioritizes above-the-fold images with fetchpriority="high" for faster page loads. |
| WebP Uploads | Automatically generates WebP versions of uploaded images for better compression and performance. |
| Template-specific style loading | Template and CPT styles are loaded only when needed (404, search, archive, page templates, custom post types); improves Lighthouse by reducing unused CSS. |
| Automatic cache versioning | Built CSS/JS use file modification time as the version query string so caches update automatically after each build. |
| Lighthouse | Run Performance, Accessibility, Best Practices, and SEO audits (mobile + desktop) from the terminal; scores only, no report files. |
| Lefthook Integration | Required for pre-commit hooks and automated code quality checks. |
- WordPress 6.4+ (tested upto 6.9.1)
- PHP 8.2+ (fully tested with PHP 8.4)
- NPM (v11+)
- Node (v25+)
- Composer 2+
- License: GPLv3
- Clone this repository to your WordPress theme directory (
wp-content/themes/). - Activate WDS BT from your WordPress admin panel under Appearance > Themes.
- Run
npm run setupto install dependencies and perform an initial build.
Full documentation is in the docs/ folder. Use it for setup details, NPM scripts, fonts, version management, linting and Lefthook, performance and images, Block Showcase, customizations, and accessibility/quality.
| Doc | Description |
|---|---|
| Development | Theme structure, setup, NPM scripts |
| Font Management | Font organization, tools, workflow |
| Version Management | Version bump and release workflows |
| Linting & Lefthook | PHP/JS/CSS linting, strict mode, fix-on-commit, no-verify policy |
| Performance & Images | Asset loading, dominant color, prioritizer, WebP |
| Block Showcase | Admin block discovery and preview tool |
| Customizations | Block styles, variations, mixins |
| Accessibility & Quality | A11y, Lighthouse, security, cross-platform |
Theme structure, setup steps, and a full NPM scripts reference are in docs/development.md. Quick start: cd to the theme directory, then npm run setup.
Fonts are organized by purpose (headline/, body/, mono/ under assets/fonts/). Run npm run fonts to process them and update theme.json and preload links. Full workflow and tools: docs/fonts.md.
Set VERSION=1.4.0 in .env (or use the env var), then run npm run version-update to sync version in style.css, package.json, composer.json, and README. Release workflows and troubleshooting: docs/version-management.md.
Run npm run create-block from the theme root and follow the prompts; the block is scaffolded under assets/blocks/. Then run npm run build to compile assets. See Development for the full script list.
Admin-only tool to list and preview all registered blocks with their attributes. Create a page and assign the Block Showcase template. Full steps and options: docs/block-showcase.md.
Template and CPT styles load only when relevant; block styles are enqueued per block or when used. Built assets use modification-time cache versioning. Dominant color placeholders, image prioritizer, and WebP generation are built in. Details: docs/performance.md.
Register block styles in inc/hooks/register-block-styles.php. Override core blocks with SCSS in assets/scss/blocks/core/, third-party in assets/scss/blocks/third-party/. Add variations in assets/js/block-variations/ and unregister blocks in assets/js/editor.js. Responsive and mobile-only mixins are in assets/scss/abstracts/. Full guide: docs/customizations.md.
PHP (PHPCS), JavaScript (ESLint), and CSS/SCSS (Stylelint) use the latest WordPress standards; warnings are treated as failures. On commit, Lefthook runs auto-fix, re-stages changed files, then runs strict lint. Do not use --no-verify; CI runs the same checks. Full config and policy: docs/linting-and-hooks.md.
Block pattern categories are registered from subfolders of patterns/. Add a folder (e.g. patterns/cards/), put pattern PHP files in it, and set each file’s Categories header to the folder name (e.g. Categories: cards). No extra code is required.
Run npm run a11y for Pa11y-based accessibility checks and npm run lighthouse for performance and SEO scores. CI runs security and code-quality checks. Cross-platform notes (rimraf, PHP detection) are in docs/accessibility-and-quality.md.
Contributions and issues are welcome. See CONTRIBUTING.md before opening a pull request.
WDS BT is free software under the GPL v2 or later. See LICENSE.md.
The WDS-BT theme was initially inspired by the Powder theme. We thank the creators of Powder for their work.