@times-design-system/components-wordpress 1.2.2-alpha.1 → 1.2.2-alpha.4

package/BLOCK_CREATION_CHECKLIST.md

@@ -68,13 +68,63 @@ Use this checklist when creating each new WordPress block from a React component
 - [ ] Confirmed HTML output in pattern matches `render.php` structure
 - [ ] Included proper ARIA attributes
 
-## 6. Styling
+## 6. Styling — Full Parity with React Components
+
+### 6a. Copy Styles from React Component
+
+- [ ] Located React component styles in `packages/components-react/src/<ComponentName>/<ComponentName>.scss` or `.css`
+- [ ] Identified all style segments: base styles, variant modifiers, state handlers (hover, focus, active, disabled)
+- [ ] Copied complete CSS from React component to WordPress `style.css`
+- [ ] **CRITICAL**: All CSS custom properties (design tokens) are preserved — NO hardcoded values
+- [ ] Followed BEM naming: `.tds-<component>`, `.tds-<component>--modifier` (intent variants, size variants, behaviour variants)
+- [ ] Ensured state handlers (hover, focus, active, disabled) are included
+- [ ] Verified transitions and animations are preserved
+
+### 6b. Resolved Design Token Values
+
+WordPress blocks use **resolved design token values** — actual hex colors, pixel sizes, and font definitions compiled directly into CSS. This makes blocks completely self-contained.
+
+**Conversion Process**:
+
+For each CSS property in the React component:
+
+1. Identify the design token it references (e.g., `--spacing-05`, `--interactive-primary-fill-default`)
+2. Look up the resolved value in [SCSS_VARIABLES_REFERENCE.md](./SCSS_VARIABLES_REFERENCE.md)
+3. Replace the variable with the actual value:
+   - `gap: var(--spacing-03)` → `gap: 4px`
+   - `background: var(--interactive-primary-fill-default)` → `background: #005c8a`
+   - `font-family: var(--fontFamily040)` → `font-family: Roboto`
+
+**Checklist**:
+
+- [ ] All hex color values are used directly (e.g., `#005c8a`, never `var(--color-*)`)
+- [ ] All spacing uses pixel values (e.g., `8px`, never `var(--spacing-05)`)
+- [ ] All typography uses concrete values (font-family, font-weight, font-size all explicit)
+- [ ] Border radius values are hardcoded (e.g., `4px`, `9999px`)
+- [ ] No CSS custom property fallbacks (e.g., no `var(--spacing-05, 8px)`)
+- [ ] Blocks work in any WordPress theme (no theme-scss dependency needed)
+- [ ] All color values from design tokens are accurate
+
+**Reference**: See `SCSS_VARIABLES_REFERENCE.md` for the complete value mapping
+
+### 6c. Variant Coverage
+
+- [ ] **Intent variants**: primary, secondary, negative (if applicable) with unique color tokens
+- [ ] **Size variants**: small, medium, large (if applicable) with appropriate padding/font-size
+- [ ] **Behaviour variants**: full width, hug content, etc.
+- [ ] **State handlers**: hover, active, focus-visible with box-shadow rings, disabled with opacity/color changes
+- [ ] **Channel/toggle states**: for components like Chip (on/off states with different colors)
+
+### 6d. Testing & Validation
 
-- [ ] Updated `style.css` with component styles
-- [ ] Used CSS custom properties for design tokens
-- [ ] Followed BEM naming: `.tds-<component>`, `.tds-<component>--modifier`
 - [ ] Tested styles on editor and frontend
-- [ ] Added `style-editor.css` for editor-specific overrides (if needed)
+- [ ] Verified all variant combinations render correctly with proper colors/sizing
+- [ ] Checked focus/hover/active states work as expected
+- [ ] Tested disabled state (proper cursor, opacity, color changes)
+- [ ] Tested responsive breakpoints if applicable
+- [ ] Added `style-editor.css` for editor-specific overrides (only if needed)
+- [ ] Confirmed line count of `style.css` is comparable to React component (similar complexity = similar coverage)
+- [ ] Visual comparison: side-by-side React vs WordPress block in patterns/editor to confirm parity
 
 ## 7. Utilities
 
@@ -160,10 +210,49 @@ Event handler → Not supported (use editor preview only)
 
 **Solution**: Verify CSS paths in `block.json` and ensure theme-scss is in dependencies
 
+### Issue: Styles incomplete or missing variants
+
+**Solution**: Compare `style.css` line count to React component to identify gaps
+```bash
+# Check line count
+wc -l src/blocks/<component>/style.css
+wc -l packages/components-react/src/<ComponentName>/<ComponentName>.scss
+
+# If WordPress component is <50% of React component, styles are incomplete
+# Copy missing variant modifiers from React component:
+grep 'tds-<component>--' packages/components-react/src/<ComponentName>/<ComponentName>.scss
+# Ensure all variants are in WordPress style.css
+```
+
+**Typical missing patterns**:
+- Intent variant modifiers (primary, secondary, negative)
+- Size variant modifiers (small, medium, large)
+- State handlers (hover, focus-visible, active, disabled)
+- Focus ring styling with ::after pseudo-element
+- Behaviour modifiers (full, hug)
+
+### Issue: Block styles differ from React component
+
+**Solution**: Use visual regression testing
+1. Open React component in Storybook
+2. Render WordPress block in editor side-by-side
+3. Compare colors, spacing, typography for each variant
+4. Verify all CSS custom properties use `var(--token-name)` format
+5. Copy any missing styles from React component
+
 ### Issue: Inspector controls not working
 
 **Solution**: Verify `setAttributes()` is called with correct attribute name and value
 
+### Issue: Block renders in editor but not in patterns
+
+**Solution**: Verify server-side render callback is properly configured
+1. Check `render.php` exists in block directory
+2. Verify `block.json` contains `"render": "file:./render.php"`
+3. Rebuild: `npm run build` (copies render.php to dist/)
+4. Verify render.php HTML structure matches save.js exactly
+5. Test render.php independently in WordPress patterns
+
 ---
 
 ## Helpful Commands

package/README.md

@@ -929,12 +929,15 @@ npm run build && npm run build:plugin  # Build for plugin distrib
 ### Get Help
 
 1. **Check Documentation**:
-   - [TRANSFORMATION_GUIDE.md](./TRANSFORMATION_GUIDE.md) — Technical details
-   - [BLOCK_CREATION_CHECKLIST.md](./BLOCK_CREATION_CHECKLIST.md) — Verify setup
+   - [TRANSFORMATION_GUIDE.md](./TRANSFORMATION_GUIDE.md) — Complete transformation process and testing
+   - [BLOCK_CREATION_CHECKLIST.md](./BLOCK_CREATION_CHECKLIST.md) — Step-by-step implementation verification
+   - [SCSS_VARIABLES_REFERENCE.md](./SCSS_VARIABLES_REFERENCE.md) — Design token CSS custom properties guide
+   - [STYLING_SYNC_GUIDE.md](./STYLING_SYNC_GUIDE.md) — Ensure CSS feature parity with React components
 
 2. **Common Issues**:
    - See "Troubleshooting Integration" section above
    - Check plugin debug log: `/wp-content/debug.log`
+   - **Styling gaps**: Use [STYLING_SYNC_GUIDE.md](./STYLING_SYNC_GUIDE.md) and [SCSS_VARIABLES_REFERENCE.md](./SCSS_VARIABLES_REFERENCE.md) to validate style completeness
 
 3. **Report Issues**:
    - GitHub: [times-design-system/issues](https://github.com/newsuk/times-design-system/issues)
@@ -946,8 +949,11 @@ To add new blocks or improve existing ones:
 
 1. Review [TRANSFORMATION_GUIDE.md](./TRANSFORMATION_GUIDE.md)
 2. Follow [BLOCK_CREATION_CHECKLIST.md](./BLOCK_CREATION_CHECKLIST.md)
-3. Test thoroughly before submitting
-4. Submit PR with detailed description
+3. **Style using design tokens**: Reference [SCSS_VARIABLES_REFERENCE.md](./SCSS_VARIABLES_REFERENCE.md) for CSS custom properties
+4. **Synchronize styling** using [STYLING_SYNC_GUIDE.md](./STYLING_SYNC_GUIDE.md) — critical for feature parity
+5. Run testing workflow from TRANSFORMATION_GUIDE.md
+6. Test thoroughly before submitting
+7. Submit PR with detailed description
 
 ## License
 

package/SCSS_VARIABLES_REFERENCE.md

@@ -0,0 +1,314 @@
+# Design Token Values Reference for WordPress Blocks
+
+This document provides resolved design token values (actual hex colors, pixel sizes, and font definitions) used directly in WordPress block styles.
+
+## Important: Resolved Values Architecture
+
+WordPress blocks use **resolved design token values** directly in CSS rather than CSS custom properties. This approach:
+
+- ✅ Makes blocks **self-contained** and independent of theme-scss loading
+- ✅ Ensures **consistent appearance** across different WordPress installations
+- ✅ Eliminates dependency on CSS variables being defined
+- ✅ Makes blocks work reliably in any WordPress theme context
+
+**No CSS custom properties are required at runtime** — all values are baked directly into the compiled block CSS.
+
+---
+
+## Available SCSS Variables
+
+All variables from `packages/theme-scss/src/tds-layout.scss` are compiled to CSS custom properties and available in block styles.
+
+### Spacing Variables
+
+| SCSS Variable | CSS Property   | Value | Usage                        |
+| ------------- | -------------- | ----- | ---------------------------- |
+| `$spacing-01` | `--spacing-01` | 2px   | Borders, minimal gaps        |
+| `$spacing-02` | `--spacing-02` | 3px   | Fine-tuning                  |
+| `$spacing-03` | `--spacing-03` | 4px   | Tight spacing in components  |
+| `$spacing-04` | `--spacing-04` | 6px   | Small gaps, padding          |
+| `$spacing-05` | `--spacing-05` | 8px   | Common padding               |
+| `$spacing-06` | `--spacing-06` | 10px  | Medium gaps                  |
+| `$spacing-07` | `--spacing-07` | 12px  | Medium-large gaps            |
+| `$spacing-08` | `--spacing-08` | 14px  | Standard gap                 |
+| `$spacing-09` | `--spacing-09` | 16px  | Common gap (1rem equivalent) |
+| `$spacing-10` | `--spacing-10` | 18px  | Large gap                    |
+| `$spacing-11` | `--spacing-11` | 20px  | Larger spacing               |
+| `$spacing-12` | `--spacing-12` | 23px  | Component sizing             |
+| `$spacing-13` | `--spacing-13` | 24px  | Section divider spacing      |
+| `$spacing-14` | `--spacing-14` | 28px  | Block separator              |
+| `$spacing-15` | `--spacing-15` | 32px  | Small component height       |
+| `$spacing-16` | `--spacing-16` | 36px  | Medium component height      |
+| `$spacing-17` | `--spacing-17` | 40px  | Large component height       |
+| `$spacing-18` | `--spacing-18` | 48px  | XL component height          |
+| `$spacing-19` | `--spacing-19` | 56px  | Block spacing                |
+| `$spacing-20` | `--spacing-20` | 64px  | Large section spacing        |
+| `$spacing-21` | `--spacing-21` | 80px  | XL section spacing           |
+
+### Border Radius Variables
+
+| SCSS Variable         | CSS Property           | Value  | Usage                          |
+| --------------------- | ---------------------- | ------ | ------------------------------ |
+| `$border-radius-50`   | `--border-radius-50`   | 2px    | Minimal rounding               |
+| `$border-radius-100`  | `--border-radius-100`  | 4px    | Subtle rounding                |
+| `$border-radius-150`  | `--border-radius-150`  | 6px    | Standard rounding              |
+| `$border-radius-200`  | `--border-radius-200`  | 8px    | Medium rounding                |
+| `$border-radius-300`  | `--border-radius-300`  | 12px   | Larger rounding                |
+| `$border-radius-400`  | `--border-radius-400`  | 16px   | XL rounding                    |
+| `$border-radius-full` | `--border-radius-full` | 9999px | Fully rounded (pills, circles) |
+
+### Shadow Variables
+
+| SCSS Variable                    | CSS Property                      | Usage                   |
+| -------------------------------- | --------------------------------- | ----------------------- |
+| `$shadow-elevation-down-level-2` | `--shadow-elevation-down-level-2` | Subtle elevation shadow |
+| `$shadow-elevation-down-level-3` | `--shadow-elevation-down-level-3` | Medium elevation shadow |
+| `$shadow-elevation-down-level-4` | `--shadow-elevation-down-level-4` | Strong elevation shadow |
+| `$shadow-elevation-up-level-2`   | `--shadow-elevation-up-level-2`   | Upward subtle shadow    |
+| `$shadow-elevation-up-level-3`   | `--shadow-elevation-up-level-3`   | Upward medium shadow    |
+| `$shadow-elevation-up-level-4`   | `--shadow-elevation-up-level-4`   | Upward strong shadow    |
+
+**Example Shadow Usage**:
+
+```css
+.tds-toast {
+  box-shadow: var(--shadow-elevation-down-level-3);
+}
+```
+
+### Breakpoint Variables
+
+| SCSS Variable        | CSS Property          | Value  | Usage            |
+| -------------------- | --------------------- | ------ | ---------------- |
+| `$breakpoint-small`  | `--breakpoint-small`  | 0px    | Mobile (base)    |
+| `$breakpoint-medium` | `--breakpoint-medium` | 440px  | Tablet portrait  |
+| `$breakpoint-large`  | `--breakpoint-large`  | 1024px | Tablet landscape |
+| `$breakpoint-xLarge` | `--breakpoint-xLarge` | 1440px | Desktop          |
+
+**Example Media Query Usage**:
+
+```css
+@media (min-width: var(--breakpoint-large)) {
+  .tds-ad-container {
+    min-height: 400px;
+  }
+}
+```
+
+---
+
+## Design Token Variables (from tokens package)
+
+These CSS custom properties are compiled from the design tokens package and available in client WordPress installations through the imported theme.
+
+### Typography Variables
+
+| CSS Property          | Purpose          | Example Value     |
+| --------------------- | ---------------- | ----------------- |
+| `--fontFamily010`     | Brand serif font | Times Modern      |
+| `--fontFamily020`     | Brand font       | Times Digital W04 |
+| `--fontFamily040`     | Standard font    | Roboto            |
+| `--fontWeight040`     | Regular weight   | 400               |
+| `--fontWeight050`     | Medium weight    | 500               |
+| `--fontWeight070`     | Bold weight      | 700               |
+| `--fontSize010`       | XS text          | 12px              |
+| `--fontSize020`       | S text           | 14px              |
+| `--fontSize030`       | M text           | 16px              |
+| `--fontSize040`       | L text           | 18px/1.125rem     |
+| `--fontLineHeight010` | Tight leading    | 1                 |
+| `--fontLineHeight020` | Compact leading  | 1.125             |
+| `--fontLineHeight040` | Normal leading   | 1.5               |
+
+### Interactive State Colors
+
+| CSS Property Group                 | Variants                                     | Usage              |
+| ---------------------------------- | -------------------------------------------- | ------------------ |
+| `--interactive-primary-*`          | fill, text, border (default, hover, pressed) | Primary actions    |
+| `--interactive-secondary-*`        | fill, text, border (default, hover, pressed) | Secondary actions  |
+| `--interactive-negative-*`         | fill, text, border (default, hover, pressed) | Destructive action |
+| `--interactive-chip-primary-on-*`  | fill, text, icon (default, hover, pressed)   | Selected chip      |
+| `--interactive-chip-primary-off-*` | fill, text, icon (default, hover, pressed)   | Unselected chip    |
+| `--interactive-disabled-*`         | Colors for disabled states                   | Disabled UI        |
+| `--interactive-link-primary-*`     | text, underline (default, hover, visited)    | Primary links      |
+| `--interactive-link-secondary-*`   | text, underline (default, hover, visited)    | Secondary links    |
+
+### Messaging Colors
+
+| CSS Property           | Value | Usage         |
+| ---------------------- | ----- | ------------- |
+| `--toast-fill-success` | Green | Success toast |
+| `--toast-text-success` | White | Success text  |
+| `--toast-fill-error`   | Red   | Error toast   |
+| `--toast-text-error`   | White | Error text    |
+| `--toast-fill-warning` | Gold  | Warning toast |
+| `--toast-text-warning` | Black | Warning text  |
+| `--toast-fill-info`    | Blue  | Info toast    |
+| `--toast-text-info`    | White | Info text     |
+
+### Border Colors
+
+| CSS Property        | Usage                    |
+| ------------------- | ------------------------ |
+| `--border-primary`  | Standard borders         |
+| `--border-disabled` | Disabled element borders |
+| `--focus-border`    | Focus ring color         |
+
+### Text Colors
+
+| CSS Property                 | Usage          |
+| ---------------------------- | -------------- |
+| `--text-primary`             | Body text      |
+| `--text-secondary`           | Secondary text |
+| `--text-disabled`            | Disabled text  |
+| `--text-interactive-primary` | Link text      |
+
+---
+
+## Common CSS Variable Patterns
+
+### Button Component
+
+```css
+.tds-button {
+  /* Color tokens from interactive palette */
+  --tds-button-bg: var(--interactive-primary-fill-default);
+  --tds-button-fg: var(--interactive-primary-text-default);
+  --tds-button-border: var(--interactive-primary-border-default);
+
+  /* Spacing tokens from layout */
+  gap: var(--spacing-03);
+  padding: 0 var(--spacing-09);
+
+  /* Typography tokens */
+  font-family: var(--fontFamily040);
+  font-weight: var(--fontWeight050);
+  font-size: var(--fontSize030);
+}
+
+.tds-button--size-small {
+  min-height: var(--spacing-15);
+  padding: 0 var(--spacing-07);
+}
+
+.tds-button--intent-secondary {
+  --tds-button-bg: var(--interactive-secondary-fill-default);
+  --tds-button-fg: var(--interactive-secondary-text-default);
+}
+```
+
+### Toast Component
+
+```css
+.tds-toast {
+  /* Elevation shadow */
+  box-shadow: var(--shadow-elevation-down-level-3);
+
+  /* Spacing */
+  padding: var(--spacing-07) var(--spacing-09);
+  gap: var(--spacing-07);
+
+  /* Intent colors */
+  background: var(--toast-fill-success);
+  color: var(--toast-text-success);
+}
+
+.tds-toast--intent-error {
+  background: var(--toast-fill-error);
+  color: var(--toast-text-error);
+}
+```
+
+### Chip Component
+
+```css
+.tds-chip {
+  /* Custom properties for state variations */
+  --tds-chip-bg: var(--interactive-chip-primary-on-fill-default);
+  --tds-chip-fg: var(--interactive-chip-primary-on-text-default);
+
+  /* Rounding */
+  border-radius: calc(var(--border-radius-full) * 1px);
+
+  /* Sizing */
+  min-height: var(--spacing-16);
+  padding: 0 var(--spacing-07);
+}
+
+.tds-chip--size-large {
+  min-height: var(--spacing-18);
+  padding: 0 var(--spacing-09);
+}
+```
+
+---
+
+## Best Practices for Block Styling
+
+### ✅ DO:
+
+- ✅ Always use CSS custom properties for colors, spacing, typography
+- ✅ Define component-specific custom properties (e.g., `--tds-button-bg`) that reference design tokens
+- ✅ Use tokens for ALL hardcoded values (no hex colors, no pixel dimensions)
+- ✅ Reference `--spacing-*` for all gaps, margins, and padding
+- ✅ Reference `--border-radius-*` for all rounding
+- ✅ Use `--fontFamily*` and `--fontWeight*` for typography
+
+### ❌ DON'T:
+
+- ❌ Hardcode hex colors: `color: #000000;` → Use `color: var(--text-primary);`
+- ❌ Hardcode pixel values: `padding: 16px;` → Use `padding: var(--spacing-09);`
+- ❌ Create custom color/spacing values not in the token system
+- ❌ Skip typography customization: Always specify font, weight, and size via tokens
+- ❌ Duplicate token definitions across files
+
+---
+
+## Testing CSS Variables
+
+To verify CSS variables are resolving correctly:
+
+1. **In browser DevTools**: Inspect a rendered block element
+2. **Check computed styles**: Look for `--spacing-*`, `--interactive-*` properties
+3. **Verify colors**: Hover over color properties to see actual hex values
+4. **Check fallback values**: If variable is undefined, CSS fallback is used
+
+```css
+/* Safe fallback pattern (if variable not available) */
+color: var(--text-primary, #1a1a1a);
+border-color: var(--border-primary, #999999);
+gap: var(--spacing-03, 4px);
+```
+
+---
+
+## For New Block Developers
+
+When creating a new WordPress block:
+
+1. **Copy styles from React component**: Start with the React component's CSS
+2. **Replace hardcoded values with variables**: Every color → `var(--...)`, every space → `var(--spacing-...)`
+3. **Reference this guide**: Use the variable mappings above
+4. **Test in WordPress**: Ensure CSS custom properties resolve in both editor and frontend
+5. **Compare with existing blocks**: Use Button or Input as a reference model
+
+---
+
+## Troubleshooting
+
+**Problem**: CSS variables not resolving (seeing empty/default values)  
+**Solution**: Verify `theme-scss` is installed and theme files are enqueued. Check browser DevTools computed styles.
+
+**Problem**: Colors looking different than expected  
+**Solution**: Design token hex values may vary. Check actual hex in design tokens or use DevTools color picker.
+
+**Problem**: Spacing values too large/small  
+**Solution**: Verify you're using the correct `--spacing-*` variable. Reference the table above.
+
+---
+
+## Reference Files
+
+- SCSS Source: `packages/theme-scss/src/tds-layout.scss`
+- CSS Output: `build/css/variables.css`
+- Token Definitions: `packages/tokens/src/tokens.json`
+- Example Block Styles: `packages/components-wordpress/src/blocks/button/style.css`