WDS BT
Version: 1.4.6
What’s New in 1.4.6
- 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 lighthouse to 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
Overview
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. |
| DevContainer |
Recommended: .devcontainer for theme development (PHP 8.2, Node 24, Composer). This is the standard environment for active development on this repo. Matches wds-devcontainer when using the project template. |
| 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. |
Requirements
- WordPress 6.4+ (tested upto 6.9.1)
- Development: use the dev container (supported path for PHP, Node, Composer, and linting). It ships PHP 8.2 and Node 24 aligned with this theme.
- PHP 8.2+ and Composer 2+ when running outside the container (CI, deployment, or contributor preference)
- NPM (v11+) and Node (v24+ per
package.json engines) for build scripts
- License: GPLv3
Getting Started
- Clone this repository into your WordPress theme directory (
wp-content/themes/), or symlink it there.
- Open in the dev container: In Cursor or VS Code, choose Reopen in Container so PHP, Node, and Composer match the project (see .devcontainer/README.md).
- From the theme root, run
npm run build (after postCreateCommand’s npm ci && composer install). Use npm run setup when you need a full reset and install from scratch.
- Activate WDS BT from your WordPress admin under Appearance → Themes.
Contributors should use the dev container for day-to-day work so PHPCS, ESLint, and builds share one environment. PHP coding standards run through Composer (composer run-script phpcs) and invoke vendor/bin/phpcs directly.
Documentation
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 |
Development
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.
Font Management
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.
Version Management
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.
Creating Blocks
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.
Block Showcase
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.
Customizations
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.
Linting & Lefthook
PHP (PHPCS), JavaScript (ESLint), and CSS/SCSS (Stylelint) use the latest WordPress standards; warnings are treated as failures. Composer scripts invoke vendor/bin/phpcs and vendor/bin/phpcbf (see composer.json). 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.
Dynamic Block Pattern Categories
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.
Accessibility & Quality
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. Additional tooling notes are in docs/accessibility-and-quality.md.
Contributing and Support
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.
Acknowledgements
The WDS-BT theme was initially inspired by the Powder theme. We thank the creators of Powder for their work.
🔝 Back to Top
评论