feat(skill): enhance WordPress Block Pattern Validator with new validation checks for fontFamily attributes, font size classes, and non-WordPress comments

Author: krugazul

.github/skills/wordpress-block-pattern-validator/README.md

@@ -4,6 +4,10 @@ Validates and automatically fixes WordPress block pattern files to ensure HTML o
 
 ## Recent Updates
 
+✅ **Comment Validation** - Now detects and flags non-WordPress block comments (descriptive HTML comments) that shouldn't exist in block templates!
+
+✅ **Critical Block Validation Error Detection** - Now detects redundant `fontFamily` attributes and malformed font size classes that cause WordPress editor validation errors!
+
 ✅ **Button Block Handling** - The validator now correctly validates button blocks by checking the inner `<a class="wp-block-button__link">` tag instead of the wrapper div, matching WordPress core rendering behavior. No more false positives!
 
 ✅ **Custom Notation Support** - Now handles both `var:preset|` and `var:custom|` notation for colors, spacing, typography, and border properties.
@@ -43,6 +47,60 @@ node validate-patterns.cjs patterns/ --fix --dry-run
 
 ## What It Checks
 
+### ⚠️ Critical Block Validation Errors
+
+#### Redundant Font Family Attributes
+Detects when `fontFamily` is specified in block attributes but will be stripped by WordPress (causing validation errors):
+
+```html
+<!-- ❌ CAUSES VALIDATION ERROR -->
+<!-- wp:heading {"style":{"typography":{"fontFamily":"var:preset|font-family|roboto-serif"}}} -->
+<h3 class="wp-block-heading">Text</h3>
+
+<!-- ✅ FIXED - fontFamily removed -->
+<!-- wp:heading {} -->
+<h3 class="wp-block-heading">Text</h3>
+```
+
+#### Malformed Font Size Classes
+Catches typos in font size class names:
+
+```html
+<!-- ❌ WRONG - extra dash causes validation error -->
+<!-- wp:heading {"fontSize":"h3"} -->
+<h3 class="wp-block-heading has-h-3-font-size">Text</h3>
+
+<!-- ✅ CORRECT -->
+<!-- wp:heading {"fontSize":"h3"} -->
+<h3 class="wp-block-heading has-h3-font-size">Text</h3>
+```
+
+#### Invalid HTML Comments (Non-WordPress Block Comments)
+Detects descriptive HTML comments that shouldn't exist in block templates:
+
+```html
+<!-- ❌ INVALID - Descriptive comment not allowed -->
+<!-- Social Media Icons -->
+<!-- wp:social-links {...} -->
+<ul class="wp-block-social-links">...</ul>
+<!-- /wp:social-links -->
+
+<!-- ✅ VALID - Only WordPress block comments -->
+<!-- wp:social-links {...} -->
+<ul class="wp-block-social-links is-style-logos-only header-social">...</ul>
+<!-- /wp:social-links -->
+```
+
+**Valid comments:**
+- `<!-- wp:blockname {...} -->` (opening block)
+- `<!-- /wp:blockname -->` (closing block)
+- `<!-- wp:namespace/blockname {...} -->` (third-party blocks like WooCommerce)
+
+**Invalid comments (will be flagged):**
+- `<!-- Social Media Icons -->` ❌
+- `<!-- Top Navigation Links -->` ❌
+- `<!-- Newsletter Section -->` ❌
+
 ### ✅ Color Classes
 - `backgroundColor` → `has-{color}-background-color has-background`
 - `textColor` → `has-{color}-color has-text-color`

.github/skills/wordpress-block-pattern-validator/SKILL.md

@@ -2,18 +2,115 @@
 
 ## Description
 
-Expert in validating and fixing WordPress block pattern files to ensure HTML output matches block comment attributes according to WordPress core rendering rules. Detects and corrects mismatches between block attributes (JSON in comments) and their corresponding HTML output.
+Expert in validating and fixing WordPress block pattern files to ensure HTML output matches block comment attributes according to WordPress core rendering rules. Detects and corrects mismatches between block attributes (JSON in comments) and their corresponding HTML output, including redundant fontFamily attributes and malformed font size classes that cause block validation errors.
 
 ## Capabilities
 
 - Parse WordPress block comments and extract JSON attributes
 - Validate HTML output against WordPress core rendering rules
 - Detect missing or incorrect CSS classes
 - Detect missing or incorrect inline styles
+- **Detect redundant `fontFamily` attributes that WordPress strips on save**
+- **Detect malformed font size classes (e.g., `has-h-3-font-size` vs `has-h3-font-size`)**
+- **Detect and flag non-WordPress block comments (descriptive HTML comments)**
 - Auto-fix common rendering errors in pattern files
 - Scan multiple pattern files for validation errors
 - Generate validation reports with line-by-line error details
 
+## Critical Block Validation Error Checks
+
+### Redundant Font Family Attributes
+
+WordPress optimizes saved content by stripping CSS properties that match theme defaults. This causes block validation errors when:
+
+**Problem:**
+- Block attributes include: `"style":{"typography":{"fontFamily":"var:preset|font-family|roboto-serif"}}`
+- WordPress renders it in the editor with: `style="font-family:var(--wp--preset--font-family--roboto-serif)"`
+- But the saved database content omits it (because it matches the theme default)
+- Result: **Block validation error** ❌
+
+**Solution:**
+- Remove `fontFamily` from block attributes if it matches your `theme.json` default
+- The validator detects this pattern and warns you
+
+**Example:**
+```html
+<!-- BEFORE (causes validation error) -->
+<!-- wp:heading {"style":{"typography":{"fontFamily":"var:preset|font-family|roboto-serif"}}} -->
+<h3 class="wp-block-heading">Text</h3>
+
+<!-- AFTER (no validation error) -->
+<!-- wp:heading {} -->
+<h3 class="wp-block-heading">Text</h3>
+```
+
+### Malformed Font Size Classes
+
+Typos in font size class names cause block validation mismatches.
+
+**Problem:**
+- Block attributes: `"fontSize":"h3"`
+- Expected HTML: `class="wp-block-heading has-h3-font-size"`
+- Actual HTML: `class="wp-block-heading has-h-3-font-size"` (extra dash)
+- Result: **Block validation error** ❌
+
+**Solution:**
+- Ensure font size class matches the pattern: `has-{fontSize}-font-size`
+- No extra dashes or characters in the slug
+
+**Example:**
+```html
+<!-- WRONG (causes validation error) -->
+<!-- wp:heading {"fontSize":"h3"} -->
+<h3 class="wp-block-heading has-h-3-font-size">Text</h3>
+
+<!-- CORRECT (no validation error) -->
+<!-- wp:heading {"fontSize":"h3"} -->
+<h3 class="wp-block-heading has-h3-font-size">Text</h3>
+```
+
+### Invalid HTML Comments (Non-WordPress Block Comments)
+
+WordPress block templates and patterns should **only** contain WordPress block comments. Descriptive HTML comments are not allowed and may interfere with block parsing.
+
+**Problem:**
+- Template contains descriptive comments like: `<!-- Social Media Icons -->`, `<!-- Top Navigation Links -->`, `<!-- Newsletter Section -->`
+- These are standard HTML comments, not WordPress block comments
+- WordPress block template parser expects only block-related comments
+- Result: **Potential parsing issues** ❌ and template pollution
+
+**Valid WordPress Block Comments:**
+- Opening block: `<!-- wp:blockname {...} -->`
+- Closing block: `<!-- /wp:blockname -->`
+- Third-party blocks: `<!-- wp:namespace/blockname {...} -->` (e.g., `<!-- wp:woocommerce/mini-cart -->`)
+
+**Invalid Comments (will be flagged):**
+- `<!-- Social Media Icons -->` ❌
+- `<!-- Top Navigation Links -->` ❌
+- `<!-- Newsletter CTA Section -->` ❌
+- `<!-- Column 1: About Us -->` ❌
+
+**Solution:**
+- Remove ALL descriptive HTML comments from block templates
+- WordPress block structure should be self-documenting through proper nesting and block types
+- Use meaningful class names instead of comments to identify sections
+
+**Example:**
+```html
+<!-- WRONG (validator will flag these) -->
+<!-- Social Media Icons -->
+<!-- wp:social-links {...} -->
+<ul class="wp-block-social-links">...</ul>
+<!-- /wp:social-links -->
+
+<!-- CORRECT (no descriptive comments) -->
+<!-- wp:social-links {...} -->
+<ul class="wp-block-social-links is-style-logos-only header-social">...</ul>
+<!-- /wp:social-links -->
+```
+
+Note: The validator checks for any HTML comment that doesn't start with `wp:` or `/wp:` and flags it as an error.
+
 ## Common WordPress Block Rendering Rules
 
 ### Color Attributes

.github/skills/wordpress-block-pattern-validator/validate-patterns.cjs

@@ -220,6 +220,7 @@ class WordPressBlockValidator {
     const errors = [];
     const missingClasses = [];
     const extraClasses = [];
+    const warnings = [];
 
     // Check for missing classes
     expectedClasses.forEach(expectedClass => {
@@ -244,14 +245,46 @@ class WordPressBlockValidator {
       }
     }
 
-    if (missingClasses.length > 0 || missingStyles.length > 0) {
+    // NEW CHECK: Detect redundant fontFamily that WordPress strips
+    if (block.attributes.style?.typography?.fontFamily) {
+      const fontFamilyValue = this.convertPresetNotation(block.attributes.style.typography.fontFamily);
+      if (html.styles && html.styles.includes(`font-family:${fontFamilyValue}`)) {
+        warnings.push({
+          type: 'redundant-font-family',
+          message: `Block has fontFamily in attributes that appears in HTML but WordPress may strip it if it matches theme default: ${fontFamilyValue}`,
+          fix: 'Remove fontFamily from block attributes if it matches your theme.json default',
+        });
+      }
+    }
+
+    // NEW CHECK: Detect malformed font size classes (e.g., has-h-3-font-size instead of has-h3-font-size)
+    if (block.attributes.fontSize) {
+      const expectedFontSizeClass = `has-${block.attributes.fontSize}-font-size`;
+      // Check for common typo: extra dashes in font size slug
+      const malformedPattern = html.classes.find(cls => {
+        return cls.startsWith('has-') && cls.endsWith('-font-size') && cls !== expectedFontSizeClass;
+      });
+      
+      if (malformedPattern && !html.classes.includes(expectedFontSizeClass)) {
+        warnings.push({
+          type: 'malformed-font-size-class',
+          message: `Font size class is malformed: "${malformedPattern}" should be "${expectedFontSizeClass}"`,
+          current: malformedPattern,
+          expected: expectedFontSizeClass,
+          fix: `Change "${malformedPattern}" to "${expectedFontSizeClass}"`,
+        });
+      }
+    }
+
+    if (missingClasses.length > 0 || missingStyles.length > 0 || warnings.length > 0) {
       return {
         lineNumber,
         blockType: block.blockType,
         blockComment,
         htmlTag,
         missingClasses,
         missingStyles,
+        warnings,
         expectedClasses,
         expectedStyles,
         currentClasses: html.classes,
@@ -309,6 +342,35 @@ class WordPressBlockValidator {
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i];
 
+      // Check for non-WordPress block comments (these are not allowed)
+      const htmlCommentMatch = line.match(/<!--\s*(.+?)\s*-->/);
+      if (htmlCommentMatch) {
+        const commentContent = htmlCommentMatch[1].trim();
+        // Valid WordPress block comments start with "wp:" or "/wp:"
+        const isWordPressComment = commentContent.startsWith('wp:') || commentContent.startsWith('/wp:');
+        
+        if (!isWordPressComment) {
+          fileErrors.push({
+            lineNumber: i + 1,
+            blockType: 'invalid-comment',
+            blockComment: line,
+            htmlTag: '',
+            missingClasses: [],
+            missingStyles: [],
+            warnings: [{
+              type: 'non-wordpress-comment',
+              message: `Invalid comment: Only WordPress block comments are allowed`,
+              current: htmlCommentMatch[0],
+              fix: 'Remove this comment. WordPress block templates should only contain block comments (<!-- wp:blocktype --> or <!-- /wp:blocktype -->)',
+            }],
+            expectedClasses: [],
+            expectedStyles: '',
+            currentClasses: [],
+            currentStyles: '',
+          });
+        }
+      }
+      
       // Check if this is a WordPress block comment
       if (line.includes('<!-- wp:')) {
         // Get the next non-empty line
@@ -378,6 +440,23 @@ class WordPressBlockValidator {
           console.log(`   Block: ${error.blockType} (Line ${error.lineNumber})`);
           console.log(`   HTML Tag: Line ${error.htmlLineNumber}`);
 
+          // Show warnings first (these are critical issues causing validation errors)
+          if (error.warnings && error.warnings.length > 0) {
+            error.warnings.forEach(warning => {
+              if (warning.type === 'non-wordpress-comment') {
+                console.log(`   ⚠️  ERROR: ${warning.message}`);
+                console.log(`   Comment: ${warning.current}`);
+                console.log(`   Fix: ${warning.fix}`);
+              } else if (warning.type === 'malformed-font-size-class') {
+                console.log(`   ⚠️  CRITICAL: ${warning.message}`);
+                console.log(`   Fix: ${warning.fix}`);
+              } else if (warning.type === 'redundant-font-family') {
+                console.log(`   ⚠️  WARNING: ${warning.message}`);
+                console.log(`   Fix: ${warning.fix}`);
+              }
+            });
+          }
+          
           if (error.missingClasses.length > 0) {
             console.log(`   Missing classes: ${error.missingClasses.join(', ')}`);
           }