WDS BT v1.4.0-beta - Block Showcase & Performance Optimization

WDS BT v1.4.0-beta - Block Showcase & Performance Optimization

⚠️ BETA RELEASE
This is a beta release. Please test thoroughly before using in production. Report any issues via GitHub Issues.

Overview

This beta release introduces the Block Showcase development tool, automatic WebP image generation, performance optimizations to reduce render-blocking JavaScript, and accessibility enhancements for better color contrast compliance.

What's New:

• Block Showcase (admin-only) for block discovery and inspection
• WebP Uploads - Automatic WebP generation for uploaded images
• Performance optimizations reducing render-blocking JavaScript
• Accessibility improvements for link contrast compliance

---

Key Features and Enhancements

1. Block Showcase (Admin-Only)

A powerful development tool to discover, preview, and inspect all registered blocks with their attributes in an organized, interactive format.

• Admin-only access for security
• Interactive block previews with live rendering
• Detailed attribute inspection for each block
• Organized by categories for easy navigation
• Supports both core and third-party blocks

How to use:

1. Navigate to any page in the WordPress admin
2. Use the Block Showcase shortcode or template
3. Browse blocks by category
4. Click any block to view its attributes and preview

2. Performance Optimizations

Reduced Render-Blocking JavaScript

• Block variations script moved to editor-only (no longer loads on frontend)
• Main theme script now uses defer attribute for non-blocking execution
• Eliminated unnecessary WordPress core scripts (blocks.js, primitives.js, rich-text.js, data.js, warning.js, shortcode.js) from frontend pages
• Result: Significant reduction in render-blocking requests, improving First Contentful Paint (FCP) and Largest Contentful Paint (LCP) metrics

Image Performance

• 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

3. WebP Uploads

• Automatic generation of WebP versions when JPEG or PNG images are uploaded
• Server-side replacement via WordPress filters for seamless integration
• Client-side JavaScript fallback ensures WebP images are served even if server-side processing misses any
• Domain validation prevents external images (CDNs, other domains) from being incorrectly converted
• LCP image preloading automatically uses WebP URLs when available
• All image sizes are automatically converted, including thumbnails and responsive sizes
• WP-CLI command available for batch regeneration of WebP images

How it works:

1. When you upload a JPEG or PNG image, WebP versions are automatically generated
2. The theme serves WebP images to browsers that support them
3. Original images are kept as fallbacks for older browsers
4. Only local images are converted - external images are left untouched

4. Accessibility Enhancements

• Link underlines added to content links for better color contrast compliance (WCAG 2.1)
• Improved focus states with visible outlines for keyboard navigation
• Smart link styling: Navigation and button links remain without underlines (appropriate for their interactive contexts)
• Links now have visual distinction beyond color alone, meeting accessibility standards

5. Technical Improvements

• LCP image detection refactored to use parse_blocks() directly for better compatibility
• Enhanced error handling in block parsing functions
• Improved URL validation for WebP replacement in both PHP and JavaScript
• Better domain detection with is_local_url() helper function

---

Bug Fixes

• Fixed render-blocking JavaScript loading unnecessarily on frontend pages

---

Beta Testing Instructions

We're looking for feedback on:

1. Block Showcase functionality - Does it work as expected? Any missing blocks?
2. WebP Uploads - Test automatic WebP generation with various image formats and sizes
3. Performance improvements - Please test page load times and report any issues
4. Accessibility - Test with screen readers and keyboard navigation
5. Cross-browser compatibility - Test on Chrome, Firefox, Safari, Edge

How to test:

1. Pull the latest code from the main branch
2. Run composer install and npm install to ensure all dependencies are up to date
3. Clear any caching (object cache, browser cache, CDN cache)
4. Test the Block Showcase feature in the admin area
5. Test WebP Uploads: Upload new JPEG/PNG images and verify WebP versions are automatically generated
6. Verify that external images are not being converted to WebP (domain validation working correctly)
7. Test page load performance with browser DevTools
8. Verify accessibility with keyboard navigation and screen readers

Report issues:

• Open a GitHub Issue with the beta label
• Include steps to reproduce
• Include browser/WordPress/PHP versions
• Include any error messages or console logs

---

Known Issues

• None at this time, but please report any issues you encounter during testing

---

Testing & Validation

This beta release has been tested for:

• Performance: Reduced render-blocking JavaScript verified with Lighthouse audits
• WebP generation: Tested with both Imagick and GD libraries
• Accessibility: Color contrast compliance verified with accessibility audit tools
• Cross-browser compatibility: Tested on Chrome, Firefox, and Safari
• WordPress compatibility: Tested with WordPress 6.4+ and PHP 8.2+

---

Acknowledgments

Thank you to everyone involved in this release, especially the development team for their work on performance optimization and accessibility improvements.

---

Full Changelog: Compare previous version

WDS BT v1.3.5 - Dynamic Block Pattern Category Registration

Release Notes: Dynamic Block Pattern Category Registration

New Features:

Automatic Pattern Category Registration

• The theme now automatically registers block pattern categories based on subfolders in the patterns/ directory.
• How it works:
  • Any subfolder you add to patterns/ (e.g., patterns/cards/, patterns/hero/) will be registered as a block pattern category.
  • The folder name is used as the category slug, and a human-friendly label is generated for the block editor.
  • Pattern files placed in these subfolders and using the correct Categories header (matching the folder name) will appear in the block editor under the appropriate category.
• No manual code changes are needed to add new pattern categories—just add a subfolder to patterns/.
• How to use:
  1. Create a new subfolder inside patterns/ (e.g., patterns/cards/).
  2. Place your pattern PHP files in that subfolder.
  3. In each pattern file, set the Categories header to the folder name (e.g., Categories: cards).
  4. The new category will appear in the block editor, and your patterns will be listed under it.

Flush Object Cache and Transients

• Added a "Flush Object Cache and Transients" button to the Theme Options page (Tools > WDSBT Settings).
• When used, this button:
  • Unregisters all custom block patterns and re-registers pattern categories.
    • This would not force a full rescan of the /patterns folder which would automatically show the new pattern category.
    • Switching themes is the only 100% reliable way to force a full re-scan of the /patterns folder.
    • Flushing all caches and transients, and hard refreshing, are the next best options.
    • There is no official WordPress function to force this without a theme switch.
  • Flushes the WordPress object cache and deletes all transients to help ensure new code and/or style changes appear as soon as possible in the block editor.
  • Injects a JavaScript event to notify open block editor tabs to refresh their pattern/category cache.
  • Displays a clear admin notice explaining WordPress’s caching limitations and that a theme switch or full cache clear may still be required for new categories to appear immediately.
• How to use:
  1. Add or update patterns/categories in your theme’s /patterns folder.
  2. Go to Tools > WDSBT Settings in the WordPress admin.
  3. Click the "Flush Object Cache and Transients" button.
  4. Reload the block editor to see new patterns/categories, or follow the admin notice instructions if they do not appear immediately.

Important:
Due to WordPress core caching, new pattern categories may not appear immediately after a flush.
If you do not see your new categories:

• Try switching to another theme and then back to your theme, or
• Wait several minutes for caches to expire, or
• Clear all object caches and browser caches.

This is a WordPress limitation and does not affect production sites where patterns/categories are set before launch.

WDS BT v1.3.0 - Modern WordPress Block Theme Foundation

Overview

WDS BT is a modern, foundational WordPress block theme designed for maximum flexibility and customization. This release brings enhanced developer experience, improved accessibility, and robust code quality tools to streamline your WordPress development workflow.

Version History

From 1.1.0 to 1.3.0 - A Major Modernization Release

This release represents a significant leap forward in WDS BT theme's evolution, skipping version 1.2.0 to mark the substantial improvements and modernization efforts.

Why the Version Jump?

• Major Modernization: Complete overhaul of development tooling and configurations
• PHP 8.3 Compatibility: Full support for the latest PHP version
• WordPress 6.8.x Preparation: Enhanced compatibility with upcoming WordPress releases
• Developer Experience: Significant improvements to build processes and code quality tools

Previous Versions

• v1.0.0 - Initial release
• v1.0.1 - Bug fixes and improvements
• v1.1.0 - Enhanced block support and patterns
• v1.1.1 - Security and performance updates
• v1.2.0 - Minor feature additions
• v1.3.0 - Major modernization release (current)

This version jump reflects the substantial nature of the improvements and the theme's evolution toward a more robust, modern development foundation.

Key Features

Modern Block Theme Architecture

• New Automated Font Management System: Purpose-driven font processing with automatic theme.json registration, preload optimization, and seamless integration into your design system.
• Native WordPress Block Support: Built specifically for WordPress 6.4+ (tested up to WP 6.8.1) with full site editor integration
• Foundation Theme Design: Optimized as a base theme for extensive customization rather than a parent theme
• Responsive Design: Mobile-first approach ensuring optimal display across all devices
• Custom Color Palette: Comprehensive color system with primary, secondary, tertiary, and semantic color variations

Developer Experience

• Enhanced Webpack Configuration: Refined build system with optimized asset management and dependency resolution
• Block Creation Scripts: Automated block generation with options for static, dynamic, or interactive blocks
• Third-party Block Style Overrides: Conditional enqueuing for efficient asset delivery
• Modern Build Tools: Webpack 5, PostCSS, Sass, and Babel with React support
• Cursor Rules Generation: Allows automatic generation of MDC rules for Cursor based on Node/Composer config file variables (using JQ)

Code Quality & Standards

• Automated Quality Checks: PHP 8.3 compatibility with WordPress coding standards
• Strict Lefthook Integration: Pre-commit hooks for consistent code formatting and linting
• Multi-language Linting: ESLint, Stylelint, PHPCS, and Prettier configurations
• Accessibility Compliance: WCAG 2.2 AA compliance with automated Pa11y testing

Accessibility & Performance

• WCAG 2.2 Compliance: Built-in accessibility features and automated testing
• Performance Optimized: Image optimization, CSS/JS minification, and efficient asset loading
• SEO Ready: Semantic HTML structure and optimized for search engines

What's Included

Templates & Patterns

• Core Templates: index.html, single.html, page.html, archive.html, search.html, 404.html
• Specialized Templates: page-blank.html, page-no-title.html
• Block Patterns: Header, footer, post hero, comments, and primary category patterns
• Template Parts: Header, footer, post meta, and comments components

Asset Management

• SCSS Architecture: Organized with abstracts, base, blocks, and template-specific styles
• Font Integration: Inter, Oxygen, and Roboto Mono font families with automated management
• Icon System: SVG-based icon library with spritemap generation
• Image Optimization: WebP support with automatic optimization

Development Tools

• Block Template Generator: Mustache-based templates for rapid block development
• Accessibility Testing: Automated Pa11y CI integration with sitemap-based testing
• Version Management: Automated version updating across all theme files
• Package Management: Composer for PHP dependencies, NPM for JavaScript
• Font Processing Tools: Automated font detection, organization, and theme.json generation

Getting Started

Requirements

• WordPress 6.4+ (tested up to WP 6.8.1)
• PHP 8.2+ (fully tested with PHP 8.3)
• Node.js 20+ (fully tested with Node 22)
• NPM 10+
• Composer 2+

Quick Setup

# Clone the repository
git clone https://github.com/WebDevStudios/wds-bt.git

# Install dependencies and build
npm run setup

# Start development
npm run start

Available Scripts

• npm run build - Production build
• npm run start - Development mode with hot reloading
• npm run create-block - Generate new custom blocks
• npm run a11y - Run accessibility tests
• npm run lint - Run all linting checks
• npm run format - Format all code files
• npm run fonts - Process fonts and update theme.json

How to Update

Base Theme Patching Strategy

Since WDS BT is designed as a foundational theme, we use a patching approach for updates rather than direct version upgrades. This ensures that projects built on specific versions maintain their integrity and customizations.

Why Patching?

• Version Integrity: Each project maintains the exact version it was built on
• Customization Safety: Prevents conflicts with project-specific modifications
• Screenshot Consistency: Ensures theme screenshots match the actual deployed version
• Stable Foundation: Provides a reliable base for long-term project maintenance

Update Process

For New Projects

# Clone the latest version for new projects
git clone https://github.com/WebDevStudios/wds-bt.git
cd wds-bt
npm run setup

For Existing Projects

1. Review Changes: Check the changelog for relevant improvements
2. Selective Patching: Apply only the specific features or fixes you need
3. Test Thoroughly: Verify compatibility with your customizations
4. Version Lock: Keep your project's version number for reference

Recommended Patching Approach

Development Workflow

# Create a patch branch for testing
git checkout -b patch/wds-bt-1.3.0-updates

# Apply specific improvements (example)
# - Copy new theme options
# - Update webpack configuration
# - Apply accessibility improvements

# Test thoroughly in your project context
npm run build
npm run a11y

# Merge only after validation
git checkout main
git merge patch/wds-bt-1.3.0-updates

What to Patch

• Security Updates: Always apply security-related patches
• Performance Improvements: Webpack config, asset optimization
• Accessibility Fixes: WCAG compliance improvements
• New Features: Theme options, block patterns (if needed)
• Bug Fixes: Critical functionality fixes

What to Avoid

• Breaking Changes: Major structural changes that could affect customizations
• Version Dependencies: Updates that require WordPress version changes
• Unnecessary Features: Features not relevant to your project

Version Management

• Keep Version Numbers: Maintain your project's original WDS BT version
• Document Changes: Track which patches have been applied
• Backup Strategy: Always backup before applying patches
• Rollback Plan: Have a plan to revert if issues arise

Support Resources

• GitHub Issues: Report problems with specific patches
• Documentation: Check README.md for detailed implementation guides
• Community: Join discussions in GitHub discussions
• Professional Support: Contact WebDevStudios for enterprise support

Customization

Color System

The theme includes a comprehensive color palette with:

• Primary Colors: 8 shades from 50 to 700
• Secondary & Tertiary: Brand accent colors
• Semantic Colors: Success, warning, error states
• Grey Scale: 10 shades for typography and UI elements

Block Styles

• Core Block Support: Full styling for all WordPress core blocks
• Third-party Integration: Conditional styling for popular block plugins
• Custom Variations: Block style variations and filters

Typography

• Automated Font Management:
  • Comprehensive processing with tools/font-processor.php
  • Automatic theme.json generation using standardized font slugs
  • Preload link generation in inc/setup/font-preload.php for optimized loading
  • Improved font detection and debugging tools for easier troubleshooting
• Responsive Typography: Fluid type scaling for all devices
• Accessible by Design: High contrast ratios and readable font sizes
• Comprehensive Documentation: Updated README.md covering font organization, processing, and integration
• Developer Experience: Streamlines font integration workflow
• Performance: Automatic preload link generation for optimal font loading
• Maintainability: Purpose-based organization makes font management intuitive
• Standards Compliance: Follows WordPress block theme best practices
• Extensibility: Easy to add new fonts by simply placing them in appropriate folders

Advanced Features

Performance Optimizations

• Asset Optimization: CSS/JS minification and compression
• Image Processing: Automatic WebP conversion and optimization
• Dependency Management: Efficient loading of third-party assets
• Caching Ready: Optimized for WordPress caching plugin...

Release 1.1.0 – 2025-03-07

What's New?

This release focuses on performance improvements, security enhancements, and workflow optimizations while refining styles and development processes. Expect a smoother, more efficient experience with improved CI/CD reliability, faster builds, and better theme compatibility.

---

Key Highlights

Cleanup & Code Improvements

• Removed unused files and redundant CSS classes.
• Cleaned up unregister_core_blocks for better maintainability.
• Fixed incorrect paths and standardized function naming conventions.

Build & Performance Optimizations

• Refactored Webpack for faster, more efficient builds.
• Removed deprecated @import functions in Sass.
• Integrated an image optimizer to enhance loading speed.
• Eliminated image-webpack-loader (no longer needed).
• Minified and optimized CSS/JS assets for better frontend performance.
• Enabled Webpack tree shaking to eliminate unused dependencies.

Updated Packages & Dependencies

• Upgraded various npm packages for security and stability.
• Updated stylelint to v16 and removed deprecated rules.
• Fixed compatibility issues with the latest @wordpress/scripts.

Styles & Theme Enhancements

• Resolved stylelint issues with version 16.
• Improved theme.json for better customization and compatibility.
• Added an option to enqueue third-party block styles only when necessary.
• Introduced functionality for loading style overrides in third-party blocks.
• Adjusted typography and color settings for a more polished appearance.

Workflow & Automation

• Enhanced CI/CD workflows for more reliable deployments.
• Implemented GitHub Actions for automated PR testing.
• Improved build scripts to catch errors earlier in the process.
• Added automated accessibility checks for key components.

Security & Stability

• Strengthened security by properly escaping output in key areas.
• Applied WordPress coding standards for safer, cleaner code.
• Removed unused JavaScript to streamline page performance.
• Deferred non-essential scripts for better loading speeds.

---

How to Update

1. Backup your current setup before updating.
2. Run the following commands:

   git pull origin main
   npm run setup
   

3. If applicable, clear caches to ensure all updates are applied correctly.

---

Note

📌 Notes for Developers & Reviewers

• Ensure your environment is up to date: npm run setup.
• Test new block styles and layout adjustments in the editor.
• Run npm run lint to check for code quality issues.
• Use npm run a11y to verify accessibility compliance.
• Confirm CI/CD tests complete successfully before merging.

---

📅 What’s Next?

We’re continuously improving performance, security, and user experience while refining block editor features. Stay tuned for upcoming enhancements!

If you run into any issues, feel free to report them in the repository.

Release Notes: WDS-BT v1.0.0

Release Summary

This release of WDS-BT v1.0 introduces several enhancements, new features, and bug fixes aimed at improving performance, user experience, and content navigation. The primary focus areas include the automated versioning system, styling improvements, and template updates, as well as the introduction of a new WDS Block Template creation script.

---

Key Features and Enhancements

1. WDS Block Template Creation Script

• New Block Template: This release includes a block creation template designed to streamline block development using the @wordpress/create-block tool.
• Usage: To create a block using this template, run the following command in your terminal:

  npx @wordpress/create-block --template ../../inc/block-template --no-plugin

• Generated Block Structure:
  Upon running the command, the following structure will be created:

  📁src
  └── 📁blocks
      └── 📁{example-block}
          └── block.json
          └── edit.js
          └── editor.scss
          └── index.js
          └── render.php
          └── style.scss
  

  This configuration ensures that developers can quickly scaffold a block that is ready for registration and immediate use within the theme.

2. Automated Versioning System

• The Automated Versioning process is designed to increment the BUILD number automatically upon merges to the main branch.

3. Style Adjustments

• Button Size Variations: Missing styles for button size variations have been re-added, ensuring a consistent appearance across different button types.
• Latest Posts and Query Block Styling: Styles for the Posts Block have been updated for better visual consistency.

4. Template Updates

• Single and Archive Templates: Enhancements to single and archive templates improve overall layout design, leading to a more cohesive and polished user experience.

5. Build Process Improvements

• Composer and Webpack Updates: The build process has been optimized by updating Composer, Webpack, and related packages. These updates streamline the development workflow and fix minor issues related to paths and configurations.

6. Block Patterns and Responsiveness

• Block Patterns Tweaks: Adjustments to block patterns improve alignment and ensure that content displays correctly on both desktop and mobile devices.
• Mobile Responsiveness: All updates prioritize responsiveness, enhancing the mobile user experience.

7. Bug Fixes and Performance Enhancements

• Improved Block Editing Experience: Various updates were made to ensure smoother interactions with blocks and improve the theme's adaptability to different use cases.
• Theme.json Errors: Fixed errors related to theme.json for version 3.
• Performance Optimizations: Styles and template rendering have been optimized to reduce load times and improve overall site performance.
• README and Package Updates: Documentation has been updated to reflect the latest changes, including package updates.

8. Workflow Enhancements

• Pull Request Workflow: The CI/CD workflow has been enhanced to run only on pull requests, streamlining the development and review process.

---

How to Upgrade

To upgrade to this release:

1. Pull the latest code from the main branch.
2. Run composer install and npm install to ensure all dependencies are up to date.
3. Use the new block creation script with npx @wordpress/create-block --template ../../inc/block-template --no-plugin to generate new blocks quickly.
4. Deploy the theme and test the related posts block, templates, and style variations to verify that the changes have been applied correctly.

---

Known Issues

No known issues at this time. Please report any bugs or anomalies via Jira.

---

Testing & Validation

This release has been tested across multiple browsers and devices to ensure cross-browser compatibility and mobile responsiveness. Specific focus was placed on:

• Visual regression testing to confirm that existing functionality has not been negatively impacted by the changes.
• Cross-browser compatibility for Chrome, Firefox, and Safari.
• Accessibility testing to validate that updates meet accessibility standards.

---

Acknowledgments

Thank you to everyone involved in this release, especially the development team for their hard work on improving WDS-BT.

---

New Contributors

• @ramiwds made their first contribution in #22
• @itsamoreh made their first contribution in #27

Full Changelog: v0.1.0...v1.0

v0.1.0 - WDS-BT Initial Public Release

WDS Block Theme v0.1.0 Release Notes

We are excited to announce the release of WDS Block Theme v0.1.0, a starter block theme tailored for both WordPress users and developers. Featuring native block support and seamless compatibility with the site editor, WDS BT provides a modern and intuitive interface that seamlessly integrates with the WordPress block editor. Its contemporary design guarantees a polished appearance and outstanding performance across all devices. Developers will appreciate the theme's flexibility and ease of customization, making it an ideal choice for building WordPress websites with advanced block functionalities.

Key Features of WDS-BT:

• Native Block Support: Harness the power of WordPress's native blocks and the site editor to effortlessly craft captivating content.
• Sleek and Modern Design: Elevate your website's aesthetic appeal with a contemporary design that leaves a lasting impression.
• Intuitive User Interface: Navigate seamlessly through the theme's user-friendly interface for a delightful user experience.
• Seamless Integration with Block Editor: Unlock the full potential of the WordPress block editor for efficient content creation and customization.
• Foundation Theme Flexibility: Built as a foundational theme, WDS Block Theme offers unparalleled flexibility, serving as a blank canvas for your creative vision.
• Responsive Design: Ensure your website looks stunning across all devices with responsive design principles that adapt to varying screen sizes.
• Automated Workflow Actions: Streamline your development process with automated workflow actions that ensure code security and uphold quality standards.
• Accessibility Compliance: Prioritize inclusivity with adherence to Web Content Accessibility Guidelines (WCAG) standards, ensuring everyone can access and enjoy your website.
• Comprehensive Documentation: Access detailed documentation to guide you through the theme setup, customization, and optimization process, empowering you to create exceptional websites.

Check out the README for information on getting started.

Contribution and Support

We welcome your contributions and support tickets. Before submitting a pull request, please review our contributing guidelines.

--
A heartfelt thank you goes out to all who participated in the numerous discussions and demos over the past few weeks.