@@ -193,11 +193,34 @@ Note: The validator checks for any HTML comment that doesn't start with `wp:` or
193193
194194### Background Image Attributes
195195
196- #### Background Image with Properties
196+ WordPress blocks support two valid patterns for implementing background images:
197+
198+ #### Pattern 1: Simple Backgrounds (Attributes + Inline Styles)
197199- ** Attribute** : ` "style":{"background":{"backgroundImage":{"url":"/path/to/image.png","source":"file","title":"image"},"backgroundSize":"cover","backgroundPosition":"center","backgroundRepeat":"no-repeat"}} `
198200- ** Inline Style** : ` background-image:url('/path/to/image.png');background-size:cover;background-position:center;background-repeat:no-repeat `
199- - ** CRITICAL** : Background images must appear in BOTH block attributes AND HTML inline styles
200- - ** Why** : Block attributes are for the editor, inline styles are for frontend rendering
201+ - ** Use Case** : Simple background images without advanced effects
202+ - ** Rendering** : Browser renders directly from inline styles
203+ - ** Validation** : Background must appear in BOTH attributes AND inline styles
204+
205+ #### Pattern 2: Advanced Backgrounds (Attributes Only + SCSS)
206+ - ** Attribute** : ` "style":{"background":{"backgroundImage":{"url":"/path/to/image.png","source":"file","title":"image"},"backgroundSize":"cover","backgroundPosition":"center","backgroundRepeat":"no-repeat"}} `
207+ - ** Inline Style** : NO background properties in HTML inline styles
208+ - ** Use Case** : Backgrounds with advanced effects (blend modes, opacity, positioning)
209+ - ** Rendering** : SCSS handles frontend rendering with advanced CSS properties
210+ - ** Validation** : Background ONLY in attributes, empty HTML div for SCSS targeting
211+ - ** ⚠️ NOTE** : Current validator will flag missing inline styles - this is expected for Pattern 2
212+
213+ ** Pattern 2 Implementation:**
214+ ``` html
215+ <!-- Background in attributes for editor preview -->
216+ <!-- wp:group {"style":{"background":{"backgroundImage":{"url":"/wp-content/themes/theme/assets/images/texture.png","source":"file","title":"texture"},"backgroundSize":"cover"}},"className":"header-main"} -->
217+ <!-- NO background in inline styles - SCSS handles rendering -->
218+ <div class =" wp-block-group header-main has-background" style =" border-bottom-color :var (--wp--preset--color--secondary )" >
219+ <!-- Empty div for SCSS targeting with .header-main > div:first-child -->
220+ <div ></div >
221+ <!-- Rest of content -->
222+ </div >
223+ ```
201224
202225** IMPORTANT CONSTRAINT:** Blocks with background images CANNOT have background colors or gradients:
203226- Background images will override any ` backgroundColor ` or ` gradient ` attributes
@@ -206,14 +229,6 @@ Note: The validator checks for any HTML comment that doesn't start with `wp:` or
206229- ❌ ** ERROR:** ` "backgroundColor":"primary" ` + background image
207230- ✅ ** VALID:** Only background image attribute present
208231
209- ** Example:**
210- ``` html
211- <!-- Block comment with background attributes -->
212- <!-- wp:group {"style":{"background":{"backgroundImage":{"url":"/wp-content/themes/theme/assets/images/texture.png","source":"file","title":"texture"},"backgroundSize":"cover"}}} -->
213- <!-- HTML must have inline styles -->
214- <div class =" wp-block-group has-background" style =" background-image :url (' /wp-content/themes/theme/assets/images/texture.png' );background-size :cover " >
215- ```
216-
217232** Invalid Example (conflicting backgrounds):**
218233``` html
219234<!-- INVALID: Has both gradient and background image -->
0 commit comments