@times-design-system/components-wordpress 1.2.2-alpha.0 → 1.2.2-alpha.10

package/STYLING_SYNC_GUIDE.md

@@ -0,0 +1,306 @@
+# WordPress Block Styling Synchronization Guide
+
+This guide ensures that WordPress block styles remain synchronized with React component styles, maintaining feature parity across implementations.
+
+## Overview
+
+All WordPress blocks must have equivalent CSS to their React counterparts. This includes:
+
+- All variant combinations (intent, size, behaviour)
+- All state handlers (hover, focus, active, disabled)
+- All design token references
+- Identical visual appearance in patterns and editor
+
+## Process: React to WordPress Style Synchronization
+
+### Step 1: Identify React Component Styles
+
+```bash
+# Locate React component styles
+ls packages/components-react/src/<ComponentName>/
+# Look for: <ComponentName>.scss or <ComponentName>.css
+
+# Count lines to understand complexity
+wc -l packages/components-react/src/<ComponentName>/<ComponentName>.scss
+```
+
+### Step 2: Extract Style Segments
+
+Read the React component stylesheet and identify:
+
+1. **Base styles** (`.tds-<component>` class)
+   - Display, flex properties, gaps
+   - Basic colors, borders, padding
+   - Font properties (family, weight, size, line-height)
+   - Transitions and animations
+
+2. **Variant modifiers** (`.tds-<component>--<variant>`)
+   - Intent: primary, secondary, negative
+   - Size: small, medium, large
+   - Behaviour: full, hug
+   - Channel: on, off
+   - Toggle: on, off
+
+3. **State handlers** (pseudo-classes)
+   - `:hover` - hover states
+   - `:focus-visible` - focus states with focus ring
+   - `:active` - pressed states
+   - `:disabled` - disabled states
+   - `:visited` - visited states (for links)
+
+4. **Nested selectors** (children and pseudo-elements)
+   - `.tds-<component>__<child>` - nested elements
+   - `::after` - focus rings, decorative elements
+   - `::before` - pseudo-elements
+
+### Step 3: Copy and Adapt to WordPress
+
+Create `style.css` in the block directory:
+
+```bash
+cp packages/components-react/src/<ComponentName>/<ComponentName>.scss \
+   packages/components-wordpress/src/blocks/<component>/style-temp.css
+```
+
+Then:
+
+1. Convert SCSS to CSS (remove variables, nesting, mixins)
+2. Replace any SCSS variables with CSS custom properties
+3. Ensure all color/spacing/typography use design tokens
+4. Verify BEM naming convention (hyphens, no underscores)
+5. Save as `style.css`
+
+### Step 4: Design Token Mapping
+
+All style values must use CSS custom properties from `@times-design-system/theme-scss`.
+
+**Common Design Token Categories**:
+
+| Category       | Tokens                                                               | Example                                      |
+| -------------- | -------------------------------------------------------------------- | -------------------------------------------- |
+| **Colors**     | `--interactive-*`, `--text-*`, `--border-*`, `--flag-*`, `--toast-*` | `var(--interactive-primary-fill-default)`    |
+| **Spacing**    | `--spacing-01` through `--spacing-20`                                | `var(--spacing-03)`                          |
+| **Typography** | `--fontFamily*`, `--fontWeight*`, `--fontSize*`, `--fontLineHeight*` | `var(--fontFamily040)`, `var(--fontSize030)` |
+| **Borders**    | `--border-radius-*`                                                  | `var(--border-radius-full)`                  |
+| **Effects**    | `--focus-border`, `--shadow-*`                                       | `var(--focus-border)`                        |
+
+**Validation**:
+
+```bash
+# Check for hardcoded hex colors (should be 0 results)
+grep -E '#[0-9a-fA-F]{6}' packages/components-wordpress/src/blocks/<component>/style.css
+
+# Check for hardcoded values (should use variables)
+grep -E '[0-9]+px|[0-9]+rem' packages/components-wordpress/src/blocks/<component>/style.css | grep -v 'var('
+```
+
+### Step 5: Variant Coverage
+
+Ensure **all** variant combinations are styled:
+
+**Button Example**:
+
+```
+Intents:     --intent-primary ✓, --intent-secondary ✓, --intent-negative ✓
+Sizes:       --size-small ✓, --size-medium ✓, --size-large ✓
+Behaviour:   --behaviour-full ✓, --behaviour-hug ✓
+States:      :hover ✓, :focus-visible ✓, :active ✓, :disabled ✓
+Focus rings: ::after with --focus-border ✓
+```
+
+**Link Example**:
+
+```
+Intents:     --intent-primary ✓, --intent-secondary ✓
+Sentiments:  --sentiment-brand ✓, --sentiment-utility ✓
+Sizes:       --size-xsmall ✓, --size-small ✓, --size-medium ✓, --size-large ✓
+States:      :hover ✓, :focus-visible ✓, :active ✓, :visited ✓, :disabled ✓
+```
+
+**Chip Example**:
+
+```
+Intents:     --intent-primary ✓ (on/off variants)
+Channels:    --channel-on ✓, --channel-off ✓
+Sizes:       --size-small ✓, --size-large ✓
+States:      :hover ✓, :focus ✓, :active ✓, :disabled ✓
+Toggle:      on state (bg-dark) ✓, off state (bg-light) ✓
+```
+
+### Step 6: Test for Feature Parity
+
+```bash
+# 1. Line count comparison
+echo "React component:"
+wc -l packages/components-react/src/<ComponentName>/<ComponentName>.scss
+echo "WordPress block:"
+wc -l packages/components-wordpress/src/blocks/<component>/style.css
+
+# Acceptable difference: ±20% (accounting for SCSS nesting/mixins vs flat CSS)
+# If WordPress is <50% of React, styles are likely incomplete
+
+# 2. Variant count comparison
+echo "React variants:"
+grep -o '\.[a-z-]*--[a-z-]*' packages/components-react/src/<ComponentName>/<ComponentName>.scss | sort -u | wc -l
+echo "WordPress variants:"
+grep -o '\.[a-z-]*--[a-z-]*' packages/components-wordpress/src/blocks/<component>/style.css | sort -u | wc -l
+
+# 3. Visual comparison
+# - Open React Storybook: packages/components-react (npm run storybook)
+# - Open WordPress block in editor: packages/components-wordpress
+# - Compare side-by-side for each variant
+# - Verify colors match exactly (CSS custom properties should be identical)
+```
+
+## Style Structure Template
+
+Use this template as a reference for comprehensive block styling:
+
+```css
+/* Base component styles */
+.tds-<component > {
+  --tds-<component>-bg: var(--interactive-primary-fill-default);
+  --tds-<component>-fg: var(--interactive-primary-text-default);
+  --tds-<component>-border: var(--interactive-primary-border-default);
+
+  display: flex; /* or block, grid, etc. */
+  align-items: center;
+  justify-content: center;
+  gap: var(--spacing-03);
+
+  border: 1px solid var(--tds-<component>-border);
+  background-color: var(--tds-<component>-bg);
+  color: var(--tds-<component>-fg);
+
+  font-family: var(--fontFamily040);
+  font-weight: var(--fontWeight050);
+  font-size: var(--fontSize030);
+  line-height: var(--fontLineHeight040);
+
+  border-radius: 0;
+  transition:
+    background-color 0.15s ease,
+    border-color 0.15s ease,
+    color 0.15s ease;
+  cursor: pointer;
+}
+
+/* Intent variants */
+.tds-<component > --intent-primary {
+  --tds-<component>-bg: var(--interactive-primary-fill-default);
+  --tds-<component>-fg: var(--interactive-primary-text-default);
+  --tds-<component>-border: var(--interactive-primary-border-default);
+}
+
+.tds-<component > --intent-secondary {
+  --tds-<component>-bg: var(--interactive-secondary-fill-default);
+  --tds-<component>-fg: var(--interactive-secondary-text-default);
+  --tds-<component>-border: var(--interactive-secondary-border-default);
+}
+
+/* Size variants */
+.tds-<component > --size-small {
+  min-height: var(--spacing-15);
+  padding: var(--spacing-03) var(--spacing-05);
+  font-size: var(--fontSize020);
+}
+
+.tds-<component > --size-large {
+  min-height: var(--spacing-20);
+  padding: var(--spacing-07) var(--spacing-11);
+  font-size: var(--fontSize040);
+}
+
+/* Behaviour variants */
+.tds-<component > --behaviour-full {
+  width: 100%;
+}
+
+/* State handlers */
+.tds-<component > :hover:not(:disabled) {
+  background-color: var(--interactive-primary-fill-hover);
+  border-color: var(--interactive-primary-border-hover);
+  color: var(--interactive-primary-text-hover);
+}
+
+.tds-<component > :active:not(:disabled) {
+  background-color: var(--interactive-primary-fill-pressed);
+  border-color: var(--interactive-primary-border-pressed);
+  color: var(--interactive-primary-text-pressed);
+}
+
+.tds-<component > :focus-visible {
+  outline: none;
+}
+
+.tds-<component > :focus-visible::after {
+  content: '';
+  position: absolute;
+  inset: calc(var(--spacing-03) * -1);
+  border: var(--spacing-01) solid var(--focus-border);
+  border-radius: inherit;
+  pointer-events: none;
+}
+
+.tds-<component > :disabled {
+  background-color: var(--interactive-disabled-b);
+  border-color: transparent;
+  color: var(--text-disabled);
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+/* Nested elements */
+.tds-<component > __label {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-03);
+}
+```
+
+## Build and Verification
+
+```bash
+cd packages/components-wordpress
+
+# Build the package
+npm run build
+
+# Verify styles compiled correctly
+wc -l dist/blocks/<component>/style.css
+
+# Test in WordPress
+# 1. Copy dist/ to WordPress installation
+# 2. Activate plugin or install NPM package
+# 3. Add block to page
+# 4. Test each variant combination
+# 5. Test in patterns (server-side rendering)
+```
+
+## Maintenance
+
+When React component styles change:
+
+1. **Identify the change**: What CSS properties, variants, or states changed?
+2. **Update React component**: Make the change in `packages/components-react/src/<ComponentName>/<ComponentName>.scss`
+3. **Sync to WordPress**: Update `packages/components-wordpress/src/blocks/<component>/style.css` with the same change
+4. **Build and test**: `npm run build` in both packages and test in WordPress
+5. **Document the change**: Update CHANGELOG.md in both packages
+
+## Common Styling Issues
+
+| Issue                            | Cause                                  | Solution                                                        |
+| -------------------------------- | -------------------------------------- | --------------------------------------------------------------- |
+| Block renders but styles missing | CSS not linked in `block.json`         | Verify `"style": "file:./style.css"` in block.json              |
+| Colors don't match React         | Hardcoded hex colors or wrong token    | Replace with `var(--design-token)` from design system           |
+| Variants not styling             | Modifier CSS not written               | Compare to React, copy missing `.tds-<component>--*` selectors  |
+| Focus ring not visible           | Missing `::after` pseudo-element       | Add focus-visible handler with border and `var(--focus-border)` |
+| Styles different in patterns     | render.php classes don't match save.js | Verify class names exactly match between save.js and render.php |
+| Line count too low               | Styles incomplete or too minimal       | Compare to React line count, should be similar (±20%)           |
+
+## Related Documentation
+
+- [BLOCK_CREATION_CHECKLIST.md](./BLOCK_CREATION_CHECKLIST.md) - Step-by-step checklist for creating new blocks
+- [TRANSFORMATION_GUIDE.md](./TRANSFORMATION_GUIDE.md) - Complete transformation process documentation
+- Design tokens: `packages/tokens/README.md`
+- Component React source: `packages/components-react/src/`

package/TRANSFORMATION_GUIDE.md

@@ -263,36 +263,180 @@ export default function Save({ attributes }) {
 - No event handlers or dynamic behavior (it's static HTML)
 - Can be PHP or JavaScript-rendered depending on config
 
-### 7. **Create CSS Files**
+### 7. **Create CSS Files — Full Parity with React**
 
-#### `style.css` (Frontend Styles)
+#### `style.css` (Frontend Styles) — Critical for Feature Parity
 
-- Imported on both editor and frontend
-- Contains production CSS for the component
-- References SCSS classes from `theme-scss` package
-- Use CSS variables for tokens
+The WordPress block's `style.css` **must mirror the React component's styles exactly**. This ensures visual and behavioral consistency across all implementations.
 
-**Template**:
+**Process**:
+
+1. **Copy React component styles** from `packages/components-react/src/<ComponentName>/<ComponentName>.scss`
+2. **Map all className modifiers** to CSS selectors (e.g., React `className="tds-button--size-small"` → CSS `.tds-button--size-small { ... }`)
+3. **Preserve all CSS custom properties** for design tokens
+4. **Include all state handlers**: hover, focus-visible, active, disabled
+5. **Include all variants**: intent (primary, secondary, negative), size (small, medium, large), behaviour (full, hug)
+
+**Key Principles**:
+
+- Use **resolved design token values** for ALL properties: actual hex colors (e.g., `#005c8a`), pixel sizes (e.g., `8px`), and font names (e.g., `Roboto`)
+- Follow BEM naming: `.tds-<component>`, `.tds-<component>--<modifier>`
+- Include transitions for smooth state changes (usually `0.15s ease`)
+- Focus rings should use concrete colors (e.g., `#737373`) with box-shadow pseudo-element
+- Disabled states need opacity reduction and cursor change
+- All pseudo-classes (`:hover`, `:focus-visible`, `:active`, `:disabled`) must match React behavior
+
+**Example Structure** (from Button component):
 
 ```css
-.tds-<component > -wrapper {
-  /* Component wrapper styles */
+.tds-button {
+  --tds-button-bg: var(--interactive-primary-fill-default);
+  --tds-button-fg: var(--interactive-primary-text-default);
+  --tds-button-border: var(--interactive-primary-border-default);
+
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-03);
+  border: 1px solid var(--tds-button-border);
+  background-color: var(--tds-button-bg);
+  color: var(--tds-button-fg);
+  font-family: Roboto;
+  font-weight: 500;
+  transition: 0.15s ease;
+  cursor: pointer;
+}
+
+/* Intent variants */
+.tds-button--intent-primary {
+  --tds-button-bg: var(--interactive-primary-fill-default);
+  --tds-button-fg: var(--interactive-primary-text-default);
+}
+
+.tds-button--intent-secondary {
+  --tds-button-bg: var(--interactive-secondary-fill-default);
+  --tds-button-fg: var(--interactive-secondary-text-default);
+}
+
+/* Size variants — RESOLVED values */
+.tds-button--size-small {
+  min-height: 40px;
+  padding: 4px 8px;
+  font-size: 1.4rem;
+}
+
+.tds-button--size-medium {
+  min-height: 48px;
+  padding: 8px 12px;
+  font-size: 1.6rem;
+}
+
+.tds-button--size-large {
+  min-height: 64px;
+  padding: 12px 20px;
+  font-size: 1.8rem;
+}
+
+/* State handlers */
+.tds-button:hover:not(:disabled) {
+  background-color: var(--interactive-primary-fill-hover);
+  border-color: var(--interactive-primary-border-hover);
+}
+
+.tds-button:focus-visible {
+  outline: none;
 }
 
-.tds-<component > {
-  /* Component styles - mostly inherited from theme-scss */
+.tds-button:focus-visible::after {
+  content: '';
+  position: absolute;
+  inset: calc(var(--spacing-03) * -1);
+  border: var(--spacing-01) solid var(--focus-border);
+  pointer-events: none;
 }
 
-.tds-<component > --full {
+.tds-button:disabled {
+  background-color: var(--interactive-disabled-b);
+  color: var(--text-disabled);
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+/* Behaviour variants */
+.tds-button--behaviour-full {
   width: 100%;
 }
 ```
 
-#### `style-editor.css` (Editor Styles)
+**Validation Checklist**:
+
+✓ All CSS custom properties match design tokens  
+✓ BEM naming is consistent (no underscores, only hyphens)  
+✓ All variant combinations present (intent × size × behaviour)  
+✓ State handlers for hover, focus, active, disabled  
+✓ Line count similar to React component (indicates parity)  
+✓ Transitions preserved  
+✓ No hardcoded hex colors (all use CSS variables)
+
+#### `style-editor.css` (Editor Styles) — Optional
 
 - Only loaded in WordPress editor
 - Can override styles for better editing experience
 - Optional — only add if editor preview differs significantly from frontend
+- Example: Adjust padding/margins for better visual feedback in editor
+- Example: Add borders to clarify block boundaries during editing
+
+#### CSS Variables and theme-scss Integration
+
+**IMPORTANT**: WordPress blocks use **resolved design token values** — actual hex colors, pixel measurements, and font definitions are compiled directly into the CSS. This means blocks are completely self-contained and do not depend on CSS custom properties from theme-scss.
+
+**Key Approach**:
+
+```
+Design Tokens (theme-scss)
+          ↓
+    Resolved to concrete values
+          ↓
+    Hardcoded into WordPress block CSS
+          ↓
+    No runtime CSS variable dependencies needed
+```
+
+**Why Resolved Values**:
+
+- Blocks work reliably in any WordPress theme context
+- No need for theme-scss CSS variables to be loaded
+- Consistent appearance across installations
+- Simpler debugging (actual colors/sizes visible in DevTools)
+
+**Value Reference**:
+
+| Value Type        | Examples                                        | Notes                                 |
+| ----------------- | ----------------------------------------------- | ------------------------------------- |
+| **Colors (hex)**  | `#005c8a`, `#ffffff`, `#737373`                 | All interactive colors use hex values |
+| **Spacing (px)**  | `4px`, `8px`, `12px`, `16px`, `24px`            | All spacing uses pixel units          |
+| **Typography**    | `-apple-system, BlinkMacSystemFont, "Segoe UI"` | System fonts specified directly       |
+| **Font weight**   | `400`, `500`, `700`                             | Numeric weight values                 |
+| **Font size**     | `0.75rem`, `1rem`, `1.125rem`                   | REMs for scalability                  |
+| **Border radius** | `0`, `2px`, `4px`, `9999px`                     | Explicit pixel or full values         |
+
+**Example Block CSS** (resolved values):
+
+```css
+.tds-button {
+  /* NO CSS variables — all values are concrete */
+  --tds-button-bg: #005c8a; /* Direct hex, not var(--color-*) */
+  --tds-button-fg: #ffffff; /* No fallbacks needed */
+
+  gap: 4px; /* Direct pixel, not var(--spacing-03) */
+  padding: 8px 12px; /* Resolved from design tokens */
+
+  font-family: Roboto;
+  font-weight: 500; /* Direct numeric value */
+  font-size: 1.6rem; /* Direct resolved size from theme-scss */
+}
+```
+
+**See Also**: [SCSS_VARIABLES_REFERENCE.md](./SCSS_VARIABLES_REFERENCE.md) for complete mapping of all resolved values used across all blocks.
 
 ### 8. **Create/Update Utility Functions**
 
@@ -343,6 +487,32 @@ import './blocks/button/index.js';
 import './blocks/<new-component>/index.js';
 ```
 
+### 10. **Build and Verify**
+
+**After completing all files**:
+
+```bash
+# Build the package
+cd packages/components-wordpress
+npm run build
+
+# Verify block appears in dist/ with all styles
+ls dist/blocks/<new-component>/
+# Expected: block.json, index.js, edit.js, save.js, render.php, style.css, style-editor.css
+
+# Check line count of compiled style.css (should be substantial)
+wc -l dist/blocks/<new-component>/style.css
+```
+
+**Build verification checklist**:
+
+✓ `dist/blocks/<new-component>/render.php` exists (server-side rendering)  
+✓ `dist/blocks/<new-component>/style.css` contains all styles (50+ lines for complex components)  
+✓ `block.json` has `"render": "file:./render.php"` reference  
+✓ No TypeScript/build errors  
+✓ Block registrations all successful  
+✓ CSS custom properties properly compiled
+
 ---
 
 ## Prop-to-Attribute Conversion Reference
@@ -593,6 +763,97 @@ Suggested order for consistent, dependency-aware transformation:
 
 ---
 
+## Testing & Validation Checklist
+
+### Pre-Build Testing
+
+- [ ] **Styling Parity**: Run visual comparison of React component vs WordPress block
+  - Open React component in Storybook: `packages/components-react/src/<ComponentName>`
+  - Compare all variants side-by-side (intent, size, behaviour)
+  - Verify colors match exactly (should be identical CSS custom properties)
+  - Check spacing and padding are correct
+  - Test state transitions (hover, focus, active, disabled)
+
+- [ ] **CSS Validation**:
+  - Line count check: `wc -l src/blocks/<component>/style.css` — should be substantial (50+ for complex components like Button/Link, 20+ for simple components)
+  - Compare to React component: `wc -l packages/components-react/src/<ComponentName>/<ComponentName>.scss`
+  - Should be similar complexity (±20% acceptable difference)
+  - No hardcoded hex colors: `grep -E '#[0-9a-fA-F]{6}' src/blocks/<component>/style.css` — should be zero results (all colors use CSS variables)
+  - Validate JSON: `npm run test`
+
+- [ ] **Render Callback Testing**:
+  - Verify `render.php` exists for server-side pattern rendering
+  - Test in WordPress patterns: create pattern with block variants
+  - Confirm HTML output matches `save.js` structure exactly
+  - Test with different attribute combinations in patterns
+
+### Post-Build Testing
+
+```bash
+# Navigate to packages/components-wordpress
+cd packages/components-wordpress
+
+# Run build
+npm run build
+
+# Verify compiled styles
+wc -l dist/blocks/<component>/style.css  # Check line count (should match src/)
+grep -c 'tds-<component>--' dist/blocks/<component>/style.css  # Count modifiers
+
+# Verify render.php exists
+ls dist/blocks/<component>/render.php
+```
+
+- [ ] **Compiled Output**:
+  - All variant CSS is present in `dist/blocks/<component>/style.css`
+  - `render.php` file exists and is copied to dist
+  - `block.json` contains `"render": "file:./render.php"`
+
+- [ ] **WordPress Installation Testing**:
+  1. Build package: `npm run build`
+  2. Copy `dist/` to WordPress installation
+  3. Activate plugin or install NPM package
+  4. Add block to page in editor
+  5. Test each variant combination:
+     - Different intents (primary, secondary, negative)
+     - Different sizes (small, medium, large)
+     - Different states (hover by mouse, focus by keyboard, active by click, disabled)
+  6. Test in patterns (server-side rendering):
+     - Create pattern with block variants
+     - Confirm HTML renders correctly before editor JS loads
+     - Verify CSS loads properly
+  7. Test responsive breakpoints (if applicable):
+     - Resize browser window
+     - Verify layout adapts correctly
+  8. Test accessibility:
+     - Keyboard navigation through interactive elements
+     - Screen reader announcements
+     - Focus ring visibility
+
+### Styling Feature Parity Validation
+
+For components with variants (Button, Link, Chip, etc.), verify complete coverage:
+
+```
+Component: Button
+Intents:     primary ✓, secondary ✓, negative ✓
+Sizes:       small ✓, medium ✓, large ✓
+Behaviour:   hug ✓, full ✓
+States:      base ✓, hover ✓, focus ✓, active ✓, disabled ✓
+CSS Classes: .tds-button--intent-primary ✓, .tds-button--size-small ✓, etc.
+```
+
+- [ ] All intent variants styled (must match React exactly)
+- [ ] All size variants styled (must match React exactly)
+- [ ] All behaviour variants styled (must match React exactly)
+- [ ] All state handlers present (hover, focus-visible, active, disabled)
+- [ ] CSS custom properties for all tokens (colors, spacing, typography)
+- [ ] Focus rings use consistent `var(--focus-border)`
+- [ ] Transitions preserved from React component
+- [ ] No visual regressions compared to React
+
+---
+
 ## Debugging & Troubleshooting
 
 ### Block not appearing in Gutenberg?
@@ -607,6 +868,10 @@ Suggested order for consistent, dependency-aware transformation:
 1. Verify CSS files in `block.json` point to correct paths
 2. Check class names match SCSS in `theme-scss`
 3. Ensure theme-scss is installed: `npm install @times-design-system/theme-scss`
+4. **Styling gap**: Compare `style.css` line count to React component — if significantly lower, styles may be incomplete
+   - Check for all variant modifiers: grep `.tds-<component>--` src/blocks/<component>/style.css
+   - Verify state handlers (hover, focus, active, disabled) are present
+   - Copy missing styles from React component
 
 ### Attributes not saving?
 
@@ -614,6 +879,14 @@ Suggested order for consistent, dependency-aware transformation:
 2. Ensure `setAttributes({ key: value })` is called correctly
 3. Check attribute types match intended use
 
+### Block doesn't render in patterns?
+
+1. Verify `render.php` exists in block directory
+2. Check `block.json` has `"render": "file:./render.php"` reference
+3. Rebuild with `npm run build` to copy render.php to dist/
+4. Verify render.php HTML structure matches save.js exactly
+5. Test in WordPress patterns (not just editor)
+
 ---
 
 ## References

package/dist/blocks/ad-container/block.json

@@ -13,6 +13,7 @@
       "padding": true
     }
   },
+  "render": "file:./render.php",
   "attributes": {
     "type": {
       "type": "string",

package/dist/blocks/ad-container/render.php

@@ -0,0 +1,27 @@
+<?php
+/**
+ * Ad Container Block Render Callback
+ * 
+ * Renders the Ad Container block on the frontend.
+ * 
+ * @package TimesDesignSystem\ComponentsWordPress
+ * @var array $attributes Block attributes
+ * @var string $content Block content
+ * @var WP_Block $block Block instance
+ */
+
+$type = isset($attributes['type']) ? sanitize_text_field($attributes['type']) : '';
+$slot_id = isset($attributes['slotID']) ? sanitize_text_field($attributes['slotID']) : '';
+
+$class_name = 'tds-ad-container';
+if ($type) {
+	$class_name .= ' tds-ad-container--' . sanitize_html_class($type);
+}
+
+$wrapper_attrs = get_block_wrapper_attributes(['class' => $class_name]);
+?>
+
+<div 
+	<?php echo wp_kses_post($wrapper_attrs); ?>
+	<?php echo $slot_id ? 'data-slot-id="' . esc_attr($slot_id) . '"' : ''; ?>
+></div>