How We Sped Up WooCommerce Pattern Development with Elayne CLI

The Problem: Block Validation Was Killing Productivity

Building the WooCommerce store vertical for the Elayne theme took 47 commits and around 8,300 lines. A large chunk of that effort wasn’t spent on design or content — it was spent fighting WordPress 6.6+ block validation errors. At one point we had 46 validation failures in a single pattern file.

The root causes were consistent. Inline gap values stripped from rendered HTML. core/cover attributes missing from block comments. The wrong CSS class for font sizes. Button attribute ordering that failed silently. None of these are obvious from the block editor UI — they only surface when you insert a pattern and check the browser console.

The round-trip cost was high: write a pattern, insert it in the editor, reload the page, spot the validation error in DevTools, re-edit the PHP file, reload again. That loop added days to what should have been hours of work.

The Solution: Scaffold First, Customize Second

The new workflow flips the order. Instead of writing block JSON from scratch and then debugging validation errors, you start with a scaffolded template that already has all the required attributes in place. Then you customize content only — text, colors, copy — without touching the block structure.

This is now enforced at the workflow level. The /pattern command in Claude Code, and the underlying Elayne CLI tool it wraps, will refuse to write block JSON from scratch. Every new pattern starts from a scaffolded template.

Elayne CLI: What’s Inside

Elayne CLI is a Composer-installed tool that ships with the Elayne theme at vendor/imagewize/elayne-cli/. Version 1.4.0 — released alongside this workflow update — ships 21 templates and 12 snippets.

21 Templates

11 general-purpose templates cover the patterns all verticals share: hero covers, feature grids, two-column text/image layouts, stats bars, testimonial grids, CTA sections, and contact sections. 10 WooCommerce-specific templates cover every store page section built for the store vertical:

• woo-hero — full-bleed hero with image and CTA buttons
• woo-ticker — animated marquee with category labels
• woo-shop-categories — flat CSS grid with featured bento card
• woo-featured-products — product collection block with menu_order query
• woo-our-story — two-column brand section with watermark CSS
• woo-testimonials — testimonial grid with avatar circles
• woo-newsletter — newsletter signup section
• woo-shop-landing — pattern shell that loads all section sub-patterns
• woo-cart — wrapper for the native woocommerce/cart block
• woo-checkout — wrapper for the native woocommerce/checkout block

12 Snippets (the Validation Guards)

Six layout snippets cover reusable UI sub-patterns: eyebrow + heading + body, button pairs, 3-column grid wrappers, stat items, testimonial cards, and cover cards with floating badges.

Six WP 6.6+ validation guard snippets cover the specific blocks that most commonly fail validation:

• valid-cover.txt — wp:cover with all required attributes including dimRatio, backgroundColor, and root-level integer minHeight
• valid-columns-wp66.txt — wp:columns without inline gap or margin; isStackedOnMobile:false maps to the is-not-stacked-on-mobile class
• responsive-grid-min-width.txt — wp:group grid layout using minimumColumnWidth (preferred over wp:columns for 3+ columns)
• valid-button-attr-order.txt — wp:button with className and colors before style; font size via style.typography.fontSize, never root-level fontSize
• valid-fullwidth-section.txt — alignfull outer group with margin reset and constrained inner group
• valid-heading-with-preset.txt — wp:heading with a font size slug in JSON and the matching has-{slug}-font-size CSS class in HTML

The Pattern Compliance Checker: Now With Autofix

The compliance checker at scripts/elayne/pattern-check/class-patterncompliancechecker.php grew by 405 lines during the store vertical branch. Every hard-fought bug fix turned into a new automated check. The checker is now the most valuable artifact that branch produced.

Version 1.4.0 ships an --autofix flag. One command, run against the entire patterns directory, auto-fixes roughly 80% of validation issues without human review:

php scripts/elayne/pattern-check/class-patterncompliancechecker.php \
  --autofix demo/web/app/themes/elayne/patterns/

What autofix handles automatically:

• Inject inline gap: on flex group divs (was the dominant failure mode — ~30 patterns affected)
• Strip inline gap: from constrained or default groups
• Strip inline margin: from flex groups and columns
• Reorder wp:button JSON keys so className comes before style
• Inject the correct has-{slug}-font-size class on heading and paragraph blocks
• Migrate root-level fontSize on buttons to style.typography.fontSize

What autofix intentionally skips (requires human judgment): hardcoded hex colors, untranslated text strings, hardcoded media IDs, and external URLs. Those need to be reviewed before fixing.

In one pass against the store vertical patterns, autofix raised the pass rate from 60 to 90 patterns out of 111. The remaining 12 failures all fell into the non-autofixable buckets — and were fixed manually in a single focused session.

The Workflow in Practice

For a full new vertical (new industry, new design), the /vertical command orchestrates everything in sequence: HTML prototype generation, design token extraction, style variation JSON, and all 7 core patterns scaffolded and validated. That’s the right entry point when starting from zero.

For a single new pattern within an existing vertical — which is what store development looks like now — the /pattern command is the entry point:

• It lists available CLI templates and matches your request to the closest one
• Scaffolds via CLI: composer pattern:create -- --template=<name> --title="..." --slug="elayne/..." --category="elayne/woocommerce" --output-dir=patterns/woocommerce/
• Reads the relevant snippets from vendor/imagewize/elayne-cli/snippets/ before customizing
• Runs the compliance checker before reporting done

For the remaining store patterns — filter sidebar, sort bar, product carousel, promo banners — the workflow is: pick the closest woo-* template or use blank for patterns with no close match, scaffold, read the validation guard snippets relevant to the blocks involved, customize content only, then autofix and check.

The Pre-Commit Hook

The compliance checker is also wired into a pre-commit Git hook at .git/hooks/pre-commit. It runs automatically on any staged pattern PHP file before the commit lands. This changes the feedback loop: errors surface at commit time (2 seconds) instead of at editor-insert time (30+ seconds per round-trip including reload and DevTools inspection).

#!/usr/bin/env bash
staged=$(git diff --cached --name-only --diff-filter=ACM | grep '^demo/web/app/themes/elayne/patterns/.*\.php$')
[ -z "$staged" ] && exit 0
php scripts/elayne/pattern-check/class-patterncompliancechecker.php $staged

What This Means for Future Verticals

The store vertical was built before these tools existed in their current form. The pattern set was built by hand, debugging validation errors one by one. The workflow improvements are a direct response to that experience — every pain point from the store branch was turned into a tool, a template, or a snippet.

Future verticals start with a validated skeleton for every pattern. The compliance checker runs before any commit reaches the repository. The --autofix flag handles the mechanical fixes automatically. The remaining effort is content and design — which is where it should have been all along.

The store vertical patterns will be live at demo.imagewize.com/store/ at a later stage. The WooCommerce store subsite runs Elayne with the Store style variation active — Cormorant Garamond headings, the charcoal and cream palette, and the full homepage pattern suite including hero, marquee, categories grid, featured products, brand story, testimonials, and newsletter sections.