feat(skill): enhance WordPress Block Pattern Validator with background image attribute handling and validation rules

krugazul · krugazul · commit 1cb42e56bb88 · 2026-02-25T22:21:47.000+02:00
diff --git a/.github/skills/wordpress-block-pattern-generator/SKILL.md b/.github/skills/wordpress-block-pattern-generator/SKILL.md
@@ -176,6 +176,214 @@ All generated patterns must pass these validation checks:
 | Incorrect block type | Content doesn't match | Use correct block (paragraph vs heading) |
 | Missing escaping | Security warning | Wrap translations in `esc_html__()` |
 
+## Background Image Conversion (TSX/React to WordPress Blocks)
+
+When converting React/TSX components with background images to WordPress blocks, follow this pattern:
+
+### React/TSX Background Image Pattern
+
+```tsx
+// React component with background image
+<div 
+  className="header-section"
+  style={{
+    backgroundImage: `url(${headerTexture})`,
+    backgroundRepeat: 'no-repeat',
+    backgroundSize: 'cover',
+    backgroundPosition: 'center'
+  }}
+>
+  {/* Content */}
+</div>
+```
+
+### WordPress Block Attributes Pattern
+
+Convert the above to WordPress block attributes like this:
+
+  **Pattern 1: Standard Background (Simple, No Advanced Effects)**
+```html
+<!-- wp:group {"style":{"background":{"backgroundImage":{"url":"/wp-content/themes/theme-name/assets/images/header-texture.png","source":"file","title":"header-texture"},"backgroundSize":"cover","backgroundPosition":"center","backgroundRepeat":"no-repeat"}},"layout":{"type":"constrained"}} -->
+<div class="wp-block-group" style="background-image:url('/wp-content/themes/theme-name/assets/images/header-texture.png');background-size:cover;background-position:center;background-repeat:no-repeat">
+  <!-- Content blocks here -->
+</div>
+<!-- /wp:group -->
+```
+
+**Pattern 2: Advanced Background (With Blend Modes, Opacity, Filters)**
+```html
+<!-- wp:group {"style":{"background":{"backgroundImage":{"url":"/wp-content/themes/theme-name/assets/images/header-texture.png","source":"file","title":"header-texture"},"backgroundSize":"cover","backgroundPosition":"center","backgroundRepeat":"no-repeat"}},"className":"header-main","layout":{"type":"constrained"}} -->
+<div class="wp-block-group header-main">
+  <!-- Empty div for SCSS to target -->
+  <!-- wp:html -->
+  <div></div>
+  <!-- /wp:html -->
+  
+  <!-- Content blocks here -->
+</div>
+<!-- /wp:group -->
+```
+
+**When to use each pattern:**
+- **Pattern 1**: Simple backgrounds without blend modes, opacity, or filters
+  - Background appears in BOTH block attributes AND HTML inline styles
+  - Browser renders directly from inline styles
+- **Pattern 2**: Advanced effects requiring CSS properties not supported by block attributes
+  - Background appears ONLY in block attributes (for editor preview)
+  - NO inline styles in HTML
+  - SCSS handles all rendering using the empty HTML div
+
+**CRITICAL for Pattern 1:** Background images must be defined in BOTH places:
+1. **Block comment attributes** - WordPress editor reads these
+2. **HTML inline styles** - Browsers render these
+
+**CRITICAL for Pattern 2:** Background images defined ONLY in block attributes:
+1. **Block comment attributes** - WordPress editor reads these for preview
+2. **NO HTML inline styles** - SCSS module handles all rendering
+3. **Empty HTML div** - SCSS targets this for background + advanced effects
+
+**Why both patterns exist:**
+- Pattern 1: Block attributes allow the WordPress editor to display and edit the background, inline styles ensure frontend rendering
+- Pattern 2: Block attributes provide editor preview, SCSS provides full control for advanced effects not supported by WordPress
+- The validator checks Pattern 1 for matching attributes/styles; Pattern 2 requires manual SCSS setup
+
+**IMPORTANT CONSTRAINT:** Blocks with background images CANNOT have background colors or gradients:
+- ❌ **WRONG:** `"gradient":"brand-red"` + background image = gradient will be overridden
+- ❌ **WRONG:** `"backgroundColor":"primary"` + background image = color will be overridden
+- ✅ **CORRECT:** Use ONLY the background image attribute, no gradient or backgroundColor
+- ✅ **CORRECT:** If you need color underneath, use CSS in the theme's SCSS files
+
+**Example of WRONG pattern (conflicting background properties):**
+```html
+<!-- WRONG: Has both gradient and background image -->
+<!-- wp:group {"gradient":"brand-red","style":{"background":{"backgroundImage":{...}}}} -->
+<div class="wp-block-group has-brand-red-gradient-background has-background">
+```
+
+**Example of CORRECT pattern:**
+```html
+<!-- CORRECT: Only background image, no gradient -->
+<!-- wp:group {"style":{"background":{"backgroundImage":{...}}}} -->
+<div class="wp-block-group has-background">
+```
+
+### Required Background Attribute Structure
+
+```json
+{
+  "style": {
+    "background": {
+      "backgroundImage": {
+        "url": "/wp-content/themes/theme-name/assets/images/image.png",
+        "source": "file",
+        "title": "image-name"
+      },
+      "backgroundSize": "cover|contain|auto",
+      "backgroundPosition": "center|top|bottom|left|right",
+      "backgroundRepeat": "no-repeat|repeat|repeat-x|repeat-y"
+    }
+  }
+}
+```
+
+### Properties NOT Supported by Block Attributes
+
+The following CSS properties cannot be set via WordPress block attributes and must be handled in CSS/SCSS:
+
+- **mix-blend-mode** - Blend mode effects (multiply, screen, overlay, etc.)
+- **opacity** - Transparency levels (use CSS)
+- **filter** - Visual filters (blur, brightness, contrast, etc.)
+- **transform** - Transformations (scale, rotate, translate, etc.)
+
+### Recommended Pattern for Advanced Effects
+
+When you need CSS properties not supported by block attributes (blend modes, opacity, filters), use **Pattern 2** from above:
+
+**WordPress Pattern (Pattern 2 - Advanced):**
+```html
+<!-- wp:group {"style":{"background":{"backgroundImage":{"url":"/wp-content/themes/theme-name/assets/images/texture.png","source":"file","title":"texture"},"backgroundSize":"cover"}},"className":"header-main"} -->
+<div class="wp-block-group header-main">
+  
+  <!-- wp:html -->
+  <div></div>
+  <!-- /wp:html -->
+  
+  <!-- Content blocks -->
+  
+</div>
+<!-- /wp:group -->
+```
+
+**Key differences from Pattern 1:**
+1. NO background inline styles in the HTML div
+2. Empty HTML div for SCSS to target
+3. Background appears ONLY in block attributes (for editor preview)
+
+**SCSS Module (_header.scss):**
+```scss
+.header-main {
+  position: relative;
+  overflow: hidden;
+  
+  // Target the empty HTML block div for overlay effects
+  > div:not(.wp-block-group):first-child {
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    z-index: 0;
+    pointer-events: none;
+    mix-blend-mode: multiply;
+    opacity: 1;
+  }
+}
+```
+
+### Asset Management
+
+1. **Copy assets to theme**: Ensure images referenced in block attributes exist in the theme
+   ```bash
+   cp source-image.png /wp-content/themes/theme-name/assets/images/
+   ```
+
+2. **Use theme-relative paths**: Always use paths relative to theme root
+   ```
+   ✓ /wp-content/themes/theme-name/assets/images/image.png
+   ✗ http://example.com/wp-content/uploads/image.png (media library)
+   ```
+
+3. **Name assets descriptively**: Use kebab-case for image filenames
+   ```
+   ✓ header-texture.png
+   ✓ hero-background.jpg
+   ✗ image1.png
+   ✗ 59f5f21fc3ab664ddea62e2cde218d15718c0a5b.png
+   ```
+
+### Conversion Checklist
+
+**For Pattern 1 (Simple backgrounds):**
+- [ ] Background image copied to theme assets directory
+- [ ] Background properties added to block comment attributes
+- [ ] Background properties added to HTML div inline styles
+- [ ] Image URL uses theme-relative path
+- [ ] backgroundSize, backgroundPosition, backgroundRepeat set correctly
+- [ ] No backgroundColor or gradient attributes present with background image
+
+**For Pattern 2 (Advanced effects with SCSS):**
+- [ ] Background image copied to theme assets directory
+- [ ] Background properties added to block comment attributes ONLY
+- [ ] NO background properties in HTML div inline styles
+- [ ] Empty HTML div added for SCSS to target
+- [ ] SCSS module created with background + advanced effects
+- [ ] Image URL uses theme-relative path
+- [ ] No backgroundColor or gradient attributes present with background image
+- [ ] Advanced effects (blend modes, opacity) handled in SCSS
+- [ ] Empty HTML div added if overlay effects needed
+- [ ] SCSS module targets overlay div correctly
+- [ ] Theme rebuilt after SCSS changes
+
 ## Related Skills
 
 - `block-theme-development` - Overall theme development standards
@@ -184,8 +392,33 @@ All generated patterns must pass these validation checks:
 
 ## Version
 
-1.2.0
+1.5.0
 
 ## Last Updated
 
-2026-02-03
+2026-02-25
+
+## Changelog
+
+### 1.5.0 (2026-02-25)
+- **MAJOR UPDATE**: Documented two distinct patterns for background images
+  - Pattern 1: Simple backgrounds (attributes + HTML inline styles)
+  - Pattern 2: Advanced backgrounds with SCSS (attributes only, NO inline styles)
+- Added clear guidance on when to use each pattern
+- Updated conversion checklist for both patterns
+- Clarified that Pattern 2 uses block attributes for editor preview, SCSS for rendering
+- Added constraint: Cannot mix background images with backgroundColor or gradient attributes
+
+### 1.4.0 (2026-02-25)
+- **CRITICAL UPDATE**: Clarified that background images must be defined in BOTH block attributes AND HTML inline styles
+- Added explanation of why both are needed (editor vs. frontend rendering)
+- Updated all background image examples to show inline styles
+- Updated conversion checklist to include HTML inline styles requirement
+- Updated validator to check background image inline styles
+
+### 1.3.0 (2026-02-25)
+- Added "Background Image Conversion (TSX/React to WordPress Blocks)" section
+- Documented WordPress block attribute structure for background images
+- Added guidance on handling advanced CSS effects (blend modes, opacity) in SCSS
+- Included asset management best practices
+- Added conversion checklist for TSX to WordPress block background images
diff --git a/.github/skills/wordpress-block-pattern-validator/SKILL.md b/.github/skills/wordpress-block-pattern-validator/SKILL.md
@@ -191,6 +191,45 @@ Note: The validator checks for any HTML comment that doesn't start with `wp:` or
 - **Attribute**: `"style":{"border":{"width":"2px","color":"#000"}}`
 - **Inline Style**: `border-width:2px;border-color:#000`
 
+### Background Image Attributes
+
+#### Background Image with Properties
+- **Attribute**: `"style":{"background":{"backgroundImage":{"url":"/path/to/image.png","source":"file","title":"image"},"backgroundSize":"cover","backgroundPosition":"center","backgroundRepeat":"no-repeat"}}`
+- **Inline Style**: `background-image:url('/path/to/image.png');background-size:cover;background-position:center;background-repeat:no-repeat`
+- **CRITICAL**: Background images must appear in BOTH block attributes AND HTML inline styles
+- **Why**: Block attributes are for the editor, inline styles are for frontend rendering
+
+**IMPORTANT CONSTRAINT:** Blocks with background images CANNOT have background colors or gradients:
+- Background images will override any `backgroundColor` or `gradient` attributes
+- The validator should flag blocks that have both a background image AND a backgroundColor/gradient attribute
+- ❌ **ERROR:** `"gradient":"brand-red"` + background image
+- ❌ **ERROR:** `"backgroundColor":"primary"` + background image
+- ✅ **VALID:** Only background image attribute present
+
+**Example:**
+```html
+<!-- Block comment with background attributes -->
+<!-- wp:group {"style":{"background":{"backgroundImage":{"url":"/wp-content/themes/theme/assets/images/texture.png","source":"file","title":"texture"},"backgroundSize":"cover"}}} -->
+<!-- HTML must have inline styles -->
+<div class="wp-block-group has-background" style="background-image:url('/wp-content/themes/theme/assets/images/texture.png');background-size:cover">
+```
+
+**Invalid Example (conflicting backgrounds):**
+```html
+<!-- INVALID: Has both gradient and background image -->
+<!-- wp:group {"gradient":"brand-red","style":{"background":{"backgroundImage":{...}}}} -->
+<div class="wp-block-group has-brand-red-gradient-background has-background">
+<!-- This will fail validation - remove "gradient" attribute -->
+```
+
+#### Background Image Properties
+- **backgroundImage.url**: Required - Full path to image
+- **backgroundImage.source**: Typically `"file"` for theme assets
+- **backgroundImage.title**: Optional - Image title/alt description
+- **backgroundSize**: `cover`, `contain`, `auto`, or custom value
+- **backgroundPosition**: `center`, `top`, `bottom`, `left`, `right`, or custom
+- **backgroundRepeat**: `no-repeat`, `repeat`, `repeat-x`, `repeat-y`
+
 ### Typography Attributes
 
 #### Font Size
diff --git a/.github/skills/wordpress-block-pattern-validator/validate-patterns.cjs b/.github/skills/wordpress-block-pattern-validator/validate-patterns.cjs
@@ -186,6 +186,23 @@ class WordPressBlockValidator {
       styles.push(`color:${this.convertPresetNotation(styleObj.color.text)}`);
     }
 
+    // Background Image
+    if (styleObj.background?.backgroundImage) {
+      const bgImage = styleObj.background.backgroundImage;
+      if (bgImage.url) {
+        styles.push(`background-image:url('${bgImage.url}')`);
+      }
+    }
+    if (styleObj.background?.backgroundSize) {
+      styles.push(`background-size:${styleObj.background.backgroundSize}`);
+    }
+    if (styleObj.background?.backgroundPosition) {
+      styles.push(`background-position:${styleObj.background.backgroundPosition}`);
+    }
+    if (styleObj.background?.backgroundRepeat) {
+      styles.push(`background-repeat:${styleObj.background.backgroundRepeat}`);
+    }
+
     // Typography
     if (styleObj.typography?.fontSize) {
       styles.push(`font-size:${this.convertPresetNotation(styleObj.typography.fontSize)}`);
