@times-design-system/components-wordpress 1.5.3 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/dist/blocks/ad-container/block.json +10 -0
  2. package/dist/blocks/ad-container/edit.js +17 -1
  3. package/dist/blocks/ad-container/render.php +14 -0
  4. package/dist/blocks/button/block.json +19 -5
  5. package/dist/blocks/button/edit.js +33 -15
  6. package/dist/blocks/button/render.php +38 -2
  7. package/dist/blocks/button/style.css +63 -0
  8. package/dist/blocks/chip/block.json +12 -7
  9. package/dist/blocks/chip/edit.js +20 -17
  10. package/dist/blocks/chip/render.php +25 -3
  11. package/dist/blocks/dialog-box/block.json +10 -0
  12. package/dist/blocks/dialog-box/edit.js +17 -0
  13. package/dist/blocks/dialog-box/render.php +18 -7
  14. package/dist/blocks/divider/block.json +10 -0
  15. package/dist/blocks/divider/edit.js +18 -2
  16. package/dist/blocks/divider/render.php +14 -1
  17. package/dist/blocks/flag/block.json +10 -0
  18. package/dist/blocks/flag/edit.js +27 -2
  19. package/dist/blocks/flag/render.php +25 -1
  20. package/dist/blocks/icon/block.json +10 -0
  21. package/dist/blocks/icon/edit.js +17 -0
  22. package/dist/blocks/icon/render.php +19 -8
  23. package/dist/blocks/icon-button/block.json +15 -0
  24. package/dist/blocks/icon-button/edit.js +33 -1
  25. package/dist/blocks/icon-button/render.php +19 -0
  26. package/dist/blocks/icon-button/style.css +37 -3
  27. package/dist/blocks/input/block.json +10 -0
  28. package/dist/blocks/input/edit.js +27 -1
  29. package/dist/blocks/input/render.php +17 -1
  30. package/dist/blocks/input-helper-message/block.json +10 -0
  31. package/dist/blocks/input-helper-message/edit.js +17 -0
  32. package/dist/blocks/input-helper-message/render.php +18 -7
  33. package/dist/blocks/link/block.json +12 -7
  34. package/dist/blocks/link/edit.js +21 -18
  35. package/dist/blocks/link/render.php +25 -3
  36. package/dist/blocks/tab/block.json +10 -0
  37. package/dist/blocks/tab/edit.js +17 -0
  38. package/dist/blocks/tab/render.php +18 -7
  39. package/dist/blocks/tab-group/block.json +10 -0
  40. package/dist/blocks/tab-group/edit.js +17 -0
  41. package/dist/blocks/tab-group/render.php +18 -7
  42. package/dist/blocks/text/block.json +10 -0
  43. package/dist/blocks/text/edit.js +18 -2
  44. package/dist/blocks/text/render.php +14 -1
  45. package/dist/blocks/toast/block.json +10 -0
  46. package/dist/blocks/toast/edit.js +18 -1
  47. package/dist/blocks/toast/render.php +14 -0
  48. package/dist/index.cjs +389 -148
  49. package/dist/index.cjs.map +1 -1
  50. package/dist/index.js +389 -148
  51. package/dist/index.js.map +1 -1
  52. package/dist/utils/DATA_ATTRIBUTES_USAGE.md +377 -0
  53. package/dist/utils/sanitize-data-attributes.php +109 -0
  54. package/package.json +9 -3
  55. package/BLOCK_CREATION_CHECKLIST.md +0 -385
  56. package/BUILD.md +0 -411
  57. package/CHANGELOG.md +0 -85
  58. package/SCSS_VARIABLES_REFERENCE.md +0 -316
  59. package/STYLING_SYNC_GUIDE.md +0 -306
  60. package/TESTING.md +0 -152
  61. package/TRANSFORMATION_GUIDE.md +0 -908
  62. package/dist/blocks/button/style-resolved.css +0 -153
  63. package/lib/wordpress.js +0 -7
  64. package/rollup.config.js +0 -75
  65. package/scripts/build-plugin.cjs +0 -121
  66. package/scripts/create-block.sh +0 -141
  67. package/scripts/create-wordpress-block-tests.cjs +0 -438
  68. package/scripts/create-wordpress-block.cjs +0 -681
  69. package/src/blocks/ad-container/block.json +0 -29
  70. package/src/blocks/ad-container/edit.js +0 -42
  71. package/src/blocks/ad-container/index.js +0 -10
  72. package/src/blocks/ad-container/render.php +0 -27
  73. package/src/blocks/ad-container/save.js +0 -16
  74. package/src/blocks/ad-container/style-editor.css +0 -4
  75. package/src/blocks/ad-container/style.css +0 -30
  76. package/src/blocks/button/block.json +0 -90
  77. package/src/blocks/button/edit.js +0 -187
  78. package/src/blocks/button/index.js +0 -11
  79. package/src/blocks/button/render.php +0 -71
  80. package/src/blocks/button/save.js +0 -52
  81. package/src/blocks/button/style-editor.css +0 -15
  82. package/src/blocks/button/style-resolved.css +0 -153
  83. package/src/blocks/button/style.css +0 -157
  84. package/src/blocks/chip/block.json +0 -58
  85. package/src/blocks/chip/edit.js +0 -113
  86. package/src/blocks/chip/index.js +0 -10
  87. package/src/blocks/chip/render.php +0 -40
  88. package/src/blocks/chip/save.js +0 -36
  89. package/src/blocks/chip/style-editor.css +0 -5
  90. package/src/blocks/chip/style.css +0 -87
  91. package/src/blocks/dialog-box/block.json +0 -24
  92. package/src/blocks/dialog-box/edit.js +0 -41
  93. package/src/blocks/dialog-box/index.js +0 -17
  94. package/src/blocks/dialog-box/render.php +0 -24
  95. package/src/blocks/dialog-box/save.js +0 -23
  96. package/src/blocks/dialog-box/style.css +0 -23
  97. package/src/blocks/divider/block.json +0 -32
  98. package/src/blocks/divider/edit.js +0 -42
  99. package/src/blocks/divider/index.js +0 -10
  100. package/src/blocks/divider/render.php +0 -31
  101. package/src/blocks/divider/save.js +0 -18
  102. package/src/blocks/divider/style-editor.css +0 -4
  103. package/src/blocks/divider/style.css +0 -37
  104. package/src/blocks/flag/block.json +0 -49
  105. package/src/blocks/flag/edit.js +0 -82
  106. package/src/blocks/flag/index.js +0 -10
  107. package/src/blocks/flag/render.php +0 -34
  108. package/src/blocks/flag/save.js +0 -25
  109. package/src/blocks/flag/style-editor.css +0 -5
  110. package/src/blocks/flag/style.css +0 -54
  111. package/src/blocks/icon/block.json +0 -24
  112. package/src/blocks/icon/edit.js +0 -41
  113. package/src/blocks/icon/index.js +0 -17
  114. package/src/blocks/icon/render.php +0 -24
  115. package/src/blocks/icon/save.js +0 -23
  116. package/src/blocks/icon/style.css +0 -23
  117. package/src/blocks/icon-button/block.json +0 -44
  118. package/src/blocks/icon-button/edit.js +0 -82
  119. package/src/blocks/icon-button/index.js +0 -10
  120. package/src/blocks/icon-button/render.php +0 -46
  121. package/src/blocks/icon-button/save.js +0 -29
  122. package/src/blocks/icon-button/style-editor.css +0 -5
  123. package/src/blocks/icon-button/style.css +0 -31
  124. package/src/blocks/input/block.json +0 -48
  125. package/src/blocks/input/edit.js +0 -78
  126. package/src/blocks/input/index.js +0 -10
  127. package/src/blocks/input/render.php +0 -39
  128. package/src/blocks/input/save.js +0 -27
  129. package/src/blocks/input/style-editor.css +0 -8
  130. package/src/blocks/input/style.css +0 -53
  131. package/src/blocks/input-helper-message/block.json +0 -24
  132. package/src/blocks/input-helper-message/edit.js +0 -42
  133. package/src/blocks/input-helper-message/index.js +0 -17
  134. package/src/blocks/input-helper-message/render.php +0 -24
  135. package/src/blocks/input-helper-message/save.js +0 -23
  136. package/src/blocks/input-helper-message/style.css +0 -23
  137. package/src/blocks/link/block.json +0 -72
  138. package/src/blocks/link/edit.js +0 -151
  139. package/src/blocks/link/index.js +0 -10
  140. package/src/blocks/link/render.php +0 -44
  141. package/src/blocks/link/save.js +0 -46
  142. package/src/blocks/link/style-editor.css +0 -5
  143. package/src/blocks/link/style.css +0 -119
  144. package/src/blocks/tab/block.json +0 -24
  145. package/src/blocks/tab/edit.js +0 -41
  146. package/src/blocks/tab/index.js +0 -17
  147. package/src/blocks/tab/render.php +0 -24
  148. package/src/blocks/tab/save.js +0 -23
  149. package/src/blocks/tab/style.css +0 -23
  150. package/src/blocks/tab-group/block.json +0 -24
  151. package/src/blocks/tab-group/edit.js +0 -41
  152. package/src/blocks/tab-group/index.js +0 -17
  153. package/src/blocks/tab-group/render.php +0 -24
  154. package/src/blocks/tab-group/save.js +0 -23
  155. package/src/blocks/tab-group/style.css +0 -23
  156. package/src/blocks/text/block.json +0 -33
  157. package/src/blocks/text/edit.js +0 -56
  158. package/src/blocks/text/index.js +0 -10
  159. package/src/blocks/text/render.php +0 -26
  160. package/src/blocks/text/save.js +0 -18
  161. package/src/blocks/text/style-editor.css +0 -4
  162. package/src/blocks/text/style.css +0 -7
  163. package/src/blocks/toast/block.json +0 -40
  164. package/src/blocks/toast/edit.js +0 -85
  165. package/src/blocks/toast/index.js +0 -10
  166. package/src/blocks/toast/render.php +0 -37
  167. package/src/blocks/toast/save.js +0 -29
  168. package/src/blocks/toast/style-editor.css +0 -4
  169. package/src/blocks/toast/style.css +0 -67
  170. package/src/index.js +0 -16
  171. package/src/utils/classBuilder.js +0 -53
  172. package/tsconfig.json +0 -116
  173. package/vitest.config.js +0 -28
  174. package/vitest.config.ts +0 -28
  175. package/vitest.setup.ts +0 -129
@@ -1,316 +0,0 @@
1
- # Design Token Values Reference for WordPress Blocks
2
-
3
- This document provides resolved design token values (actual hex colors, pixel sizes, and font definitions) used directly in WordPress block styles.
4
-
5
- ## Important: Resolved Values Architecture
6
-
7
- WordPress blocks use **resolved design token values** directly in CSS rather than CSS custom properties. This approach:
8
-
9
- - ✅ Makes blocks **self-contained** and independent of theme-scss loading
10
- - ✅ Ensures **consistent appearance** across different WordPress installations
11
- - ✅ Eliminates dependency on CSS variables being defined
12
- - ✅ Makes blocks work reliably in any WordPress theme context
13
-
14
- **No CSS custom properties are required at runtime** — all values are baked directly into the compiled block CSS.
15
-
16
- ---
17
-
18
- ## Available SCSS Variables
19
-
20
- All variables from `packages/theme-scss/src/tds-layout.scss` are compiled to CSS custom properties and available in block styles.
21
-
22
- ### Spacing Variables
23
-
24
- | SCSS Variable | CSS Property | Value | Usage |
25
- | ------------- | -------------- | ----- | ---------------------------- |
26
- | `$spacing-01` | `--spacing-01` | 2px | Borders, minimal gaps |
27
- | `$spacing-02` | `--spacing-02` | 3px | Fine-tuning |
28
- | `$spacing-03` | `--spacing-03` | 4px | Tight spacing in components |
29
- | `$spacing-04` | `--spacing-04` | 6px | Small gaps, padding |
30
- | `$spacing-05` | `--spacing-05` | 8px | Common padding |
31
- | `$spacing-06` | `--spacing-06` | 10px | Medium gaps |
32
- | `$spacing-07` | `--spacing-07` | 12px | Medium-large gaps |
33
- | `$spacing-08` | `--spacing-08` | 14px | Standard gap |
34
- | `$spacing-09` | `--spacing-09` | 16px | Common gap (1rem equivalent) |
35
- | `$spacing-10` | `--spacing-10` | 18px | Large gap |
36
- | `$spacing-11` | `--spacing-11` | 20px | Larger spacing |
37
- | `$spacing-12` | `--spacing-12` | 23px | Component sizing |
38
- | `$spacing-13` | `--spacing-13` | 24px | Section divider spacing |
39
- | `$spacing-14` | `--spacing-14` | 28px | Block separator |
40
- | `$spacing-15` | `--spacing-15` | 32px | Small component height |
41
- | `$spacing-16` | `--spacing-16` | 36px | Medium component height |
42
- | `$spacing-17` | `--spacing-17` | 40px | Large component height |
43
- | `$spacing-18` | `--spacing-18` | 48px | XL component height |
44
- | `$spacing-19` | `--spacing-19` | 56px | Block spacing |
45
- | `$spacing-20` | `--spacing-20` | 64px | Large section spacing |
46
- | `$spacing-21` | `--spacing-21` | 80px | XL section spacing |
47
-
48
- ### Border Radius Variables
49
-
50
- | SCSS Variable | CSS Property | Value | Usage |
51
- | --------------------- | ---------------------- | ------ | ------------------------------ |
52
- | `$border-radius-50` | `--border-radius-50` | 2px | Minimal rounding |
53
- | `$border-radius-100` | `--border-radius-100` | 4px | Subtle rounding |
54
- | `$border-radius-150` | `--border-radius-150` | 6px | Standard rounding |
55
- | `$border-radius-200` | `--border-radius-200` | 8px | Medium rounding |
56
- | `$border-radius-300` | `--border-radius-300` | 12px | Larger rounding |
57
- | `$border-radius-400` | `--border-radius-400` | 16px | XL rounding |
58
- | `$border-radius-full` | `--border-radius-full` | 9999px | Fully rounded (pills, circles) |
59
-
60
- ### Shadow Variables
61
-
62
- | SCSS Variable | CSS Property | Usage |
63
- | -------------------------------- | --------------------------------- | ----------------------- |
64
- | `$shadow-elevation-down-level-2` | `--shadow-elevation-down-level-2` | Subtle elevation shadow |
65
- | `$shadow-elevation-down-level-3` | `--shadow-elevation-down-level-3` | Medium elevation shadow |
66
- | `$shadow-elevation-down-level-4` | `--shadow-elevation-down-level-4` | Strong elevation shadow |
67
- | `$shadow-elevation-up-level-2` | `--shadow-elevation-up-level-2` | Upward subtle shadow |
68
- | `$shadow-elevation-up-level-3` | `--shadow-elevation-up-level-3` | Upward medium shadow |
69
- | `$shadow-elevation-up-level-4` | `--shadow-elevation-up-level-4` | Upward strong shadow |
70
-
71
- **Example Shadow Usage**:
72
-
73
- ```css
74
- .tds-toast {
75
- box-shadow: var(--shadow-elevation-down-level-3);
76
- }
77
- ```
78
-
79
- **Note**: While this example shows CSS variables for illustration, WordPress blocks use **resolved values** (actual hex, pixel sizes, and font names) compiled directly into CSS, not CSS variables.
80
-
81
- ### Breakpoint Variables
82
-
83
- | SCSS Variable | CSS Property | Value | Usage |
84
- | -------------------- | --------------------- | ------ | ---------------- |
85
- | `$breakpoint-small` | `--breakpoint-small` | 0px | Mobile (base) |
86
- | `$breakpoint-medium` | `--breakpoint-medium` | 440px | Tablet portrait |
87
- | `$breakpoint-large` | `--breakpoint-large` | 1024px | Tablet landscape |
88
- | `$breakpoint-xLarge` | `--breakpoint-xLarge` | 1440px | Desktop |
89
-
90
- **Example Media Query Usage**:
91
-
92
- ```css
93
- @media (min-width: var(--breakpoint-large)) {
94
- .tds-ad-container {
95
- min-height: 400px;
96
- }
97
- }
98
- ```
99
-
100
- ---
101
-
102
- ## Design Token Variables (from tokens package)
103
-
104
- These CSS custom properties are compiled from the design tokens package and available in client WordPress installations through the imported theme.
105
-
106
- ### Typography Variables
107
-
108
- | CSS Property | Purpose | Example Value |
109
- | --------------------- | ---------------- | ----------------- |
110
- | `--fontFamily010` | Brand serif font | Times Modern |
111
- | `--fontFamily020` | Brand font | Times Digital W04 |
112
- | `--fontFamily040` | Standard font | Roboto |
113
- | `--fontWeight040` | Regular weight | 400 |
114
- | `--fontWeight050` | Medium weight | 500 |
115
- | `--fontWeight070` | Bold weight | 700 |
116
- | `--fontSize010` | XS text | 1.2rem |
117
- | `--fontSize020` | S text | 1.4rem |
118
- | `--fontSize030` | M text | 1.6rem |
119
- | `--fontSize040` | L text | 1.8rem |
120
- | `--fontLineHeight010` | Tight leading | 1 |
121
- | `--fontLineHeight020` | Compact leading | 1.125 |
122
- | `--fontLineHeight040` | Normal leading | 1.5 |
123
-
124
- ### Interactive State Colors
125
-
126
- | CSS Property Group | Variants | Usage |
127
- | ---------------------------------- | -------------------------------------------- | ------------------ |
128
- | `--interactive-primary-*` | fill, text, border (default, hover, pressed) | Primary actions |
129
- | `--interactive-secondary-*` | fill, text, border (default, hover, pressed) | Secondary actions |
130
- | `--interactive-negative-*` | fill, text, border (default, hover, pressed) | Destructive action |
131
- | `--interactive-chip-primary-on-*` | fill, text, icon (default, hover, pressed) | Selected chip |
132
- | `--interactive-chip-primary-off-*` | fill, text, icon (default, hover, pressed) | Unselected chip |
133
- | `--interactive-disabled-*` | Colors for disabled states | Disabled UI |
134
- | `--interactive-link-primary-*` | text, underline (default, hover, visited) | Primary links |
135
- | `--interactive-link-secondary-*` | text, underline (default, hover, visited) | Secondary links |
136
-
137
- ### Messaging Colors
138
-
139
- | CSS Property | Value | Usage |
140
- | ---------------------- | ----- | ------------- |
141
- | `--toast-fill-success` | Green | Success toast |
142
- | `--toast-text-success` | White | Success text |
143
- | `--toast-fill-error` | Red | Error toast |
144
- | `--toast-text-error` | White | Error text |
145
- | `--toast-fill-warning` | Gold | Warning toast |
146
- | `--toast-text-warning` | Black | Warning text |
147
- | `--toast-fill-info` | Blue | Info toast |
148
- | `--toast-text-info` | White | Info text |
149
-
150
- ### Border Colors
151
-
152
- | CSS Property | Usage |
153
- | ------------------- | ------------------------ |
154
- | `--border-primary` | Standard borders |
155
- | `--border-disabled` | Disabled element borders |
156
- | `--focus-border` | Focus ring color |
157
-
158
- ### Text Colors
159
-
160
- | CSS Property | Usage |
161
- | ---------------------------- | -------------- |
162
- | `--text-primary` | Body text |
163
- | `--text-secondary` | Secondary text |
164
- | `--text-disabled` | Disabled text |
165
- | `--text-interactive-primary` | Link text |
166
-
167
- ---
168
-
169
- ## Common CSS Variable Patterns
170
-
171
- ### Button Component
172
-
173
- ```css
174
- .tds-button {
175
- /* Color tokens from interactive palette */
176
- --tds-button-bg: var(--interactive-primary-fill-default);
177
- --tds-button-fg: var(--interactive-primary-text-default);
178
- --tds-button-border: var(--interactive-primary-border-default);
179
-
180
- /* Spacing tokens from layout */
181
- gap: var(--spacing-03);
182
- padding: 0 var(--spacing-09);
183
-
184
- /* Typography tokens */
185
- font-family: var(--fontFamily040);
186
- font-weight: var(--fontWeight050);
187
- font-size: var(--fontSize030);
188
- }
189
-
190
- .tds-button--size-small {
191
- min-height: var(--spacing-15);
192
- padding: 0 var(--spacing-07);
193
- }
194
-
195
- .tds-button--intent-secondary {
196
- --tds-button-bg: var(--interactive-secondary-fill-default);
197
- --tds-button-fg: var(--interactive-secondary-text-default);
198
- }
199
- ```
200
-
201
- ### Toast Component
202
-
203
- ```css
204
- .tds-toast {
205
- /* Elevation shadow */
206
- box-shadow: var(--shadow-elevation-down-level-3);
207
-
208
- /* Spacing */
209
- padding: var(--spacing-07) var(--spacing-09);
210
- gap: var(--spacing-07);
211
-
212
- /* Intent colors */
213
- background: var(--toast-fill-success);
214
- color: var(--toast-text-success);
215
- }
216
-
217
- .tds-toast--intent-error {
218
- background: var(--toast-fill-error);
219
- color: var(--toast-text-error);
220
- }
221
- ```
222
-
223
- ### Chip Component
224
-
225
- ```css
226
- .tds-chip {
227
- /* Custom properties for state variations */
228
- --tds-chip-bg: var(--interactive-chip-primary-on-fill-default);
229
- --tds-chip-fg: var(--interactive-chip-primary-on-text-default);
230
-
231
- /* Rounding */
232
- border-radius: calc(var(--border-radius-full) * 1px);
233
-
234
- /* Sizing */
235
- min-height: var(--spacing-16);
236
- padding: 0 var(--spacing-07);
237
- }
238
-
239
- .tds-chip--size-large {
240
- min-height: var(--spacing-18);
241
- padding: 0 var(--spacing-09);
242
- }
243
- ```
244
-
245
- ---
246
-
247
- ## Best Practices for Block Styling
248
-
249
- ### ✅ DO:
250
-
251
- - ✅ Always use CSS custom properties for colors, spacing, typography
252
- - ✅ Define component-specific custom properties (e.g., `--tds-button-bg`) that reference design tokens
253
- - ✅ Use tokens for ALL hardcoded values (no hex colors, no pixel dimensions)
254
- - ✅ Reference `--spacing-*` for all gaps, margins, and padding
255
- - ✅ Reference `--border-radius-*` for all rounding
256
- - ✅ Use `--fontFamily*` and `--fontWeight*` for typography
257
-
258
- ### ❌ DON'T:
259
-
260
- - ❌ Hardcode hex colors: `color: #000000;` → Use `color: var(--text-primary);`
261
- - ❌ Hardcode pixel values: `padding: 16px;` → Use `padding: var(--spacing-09);`
262
- - ❌ Create custom color/spacing values not in the token system
263
- - ❌ Skip typography customization: Always specify font, weight, and size via tokens
264
- - ❌ Duplicate token definitions across files
265
-
266
- ---
267
-
268
- ## Testing CSS Variables
269
-
270
- To verify CSS variables are resolving correctly:
271
-
272
- 1. **In browser DevTools**: Inspect a rendered block element
273
- 2. **Check computed styles**: Look for `--spacing-*`, `--interactive-*` properties
274
- 3. **Verify colors**: Hover over color properties to see actual hex values
275
- 4. **Check fallback values**: If variable is undefined, CSS fallback is used
276
-
277
- ```css
278
- /* Safe fallback pattern (if variable not available) */
279
- color: var(--text-primary, #1a1a1a);
280
- border-color: var(--border-primary, #999999);
281
- gap: var(--spacing-03, 4px);
282
- ```
283
-
284
- ---
285
-
286
- ## For New Block Developers
287
-
288
- When creating a new WordPress block:
289
-
290
- 1. **Copy styles from React component**: Start with the React component's CSS
291
- 2. **Replace hardcoded values with variables**: Every color → `var(--...)`, every space → `var(--spacing-...)`
292
- 3. **Reference this guide**: Use the variable mappings above
293
- 4. **Test in WordPress**: Ensure CSS custom properties resolve in both editor and frontend
294
- 5. **Compare with existing blocks**: Use Button or Input as a reference model
295
-
296
- ---
297
-
298
- ## Troubleshooting
299
-
300
- **Problem**: CSS variables not resolving (seeing empty/default values)
301
- **Solution**: Verify `theme-scss` is installed and theme files are enqueued. Check browser DevTools computed styles.
302
-
303
- **Problem**: Colors looking different than expected
304
- **Solution**: Design token hex values may vary. Check actual hex in design tokens or use DevTools color picker.
305
-
306
- **Problem**: Spacing values too large/small
307
- **Solution**: Verify you're using the correct `--spacing-*` variable. Reference the table above.
308
-
309
- ---
310
-
311
- ## Reference Files
312
-
313
- - SCSS Source: `packages/theme-scss/src/tds-layout.scss`
314
- - CSS Output: `build/css/variables.css`
315
- - Token Definitions: `packages/tokens/src/tokens.json`
316
- - Example Block Styles: `packages/components-wordpress/src/blocks/button/style.css`
@@ -1,306 +0,0 @@
1
- # WordPress Block Styling Synchronization Guide
2
-
3
- This guide ensures that WordPress block styles remain synchronized with React component styles, maintaining feature parity across implementations.
4
-
5
- ## Overview
6
-
7
- All WordPress blocks must have equivalent CSS to their React counterparts. This includes:
8
-
9
- - All variant combinations (intent, size, behaviour)
10
- - All state handlers (hover, focus, active, disabled)
11
- - All design token references
12
- - Identical visual appearance in patterns and editor
13
-
14
- ## Process: React to WordPress Style Synchronization
15
-
16
- ### Step 1: Identify React Component Styles
17
-
18
- ```bash
19
- # Locate React component styles
20
- ls packages/components-react/src/<ComponentName>/
21
- # Look for: <ComponentName>.scss or <ComponentName>.css
22
-
23
- # Count lines to understand complexity
24
- wc -l packages/components-react/src/<ComponentName>/<ComponentName>.scss
25
- ```
26
-
27
- ### Step 2: Extract Style Segments
28
-
29
- Read the React component stylesheet and identify:
30
-
31
- 1. **Base styles** (`.tds-<component>` class)
32
- - Display, flex properties, gaps
33
- - Basic colors, borders, padding
34
- - Font properties (family, weight, size, line-height)
35
- - Transitions and animations
36
-
37
- 2. **Variant modifiers** (`.tds-<component>--<variant>`)
38
- - Intent: primary, secondary, negative
39
- - Size: small, medium, large
40
- - Behaviour: full, hug
41
- - Channel: on, off
42
- - Toggle: on, off
43
-
44
- 3. **State handlers** (pseudo-classes)
45
- - `:hover` - hover states
46
- - `:focus-visible` - focus states with focus ring
47
- - `:active` - pressed states
48
- - `:disabled` - disabled states
49
- - `:visited` - visited states (for links)
50
-
51
- 4. **Nested selectors** (children and pseudo-elements)
52
- - `.tds-<component>__<child>` - nested elements
53
- - `::after` - focus rings, decorative elements
54
- - `::before` - pseudo-elements
55
-
56
- ### Step 3: Copy and Adapt to WordPress
57
-
58
- Create `style.css` in the block directory:
59
-
60
- ```bash
61
- cp packages/components-react/src/<ComponentName>/<ComponentName>.scss \
62
- packages/components-wordpress/src/blocks/<component>/style-temp.css
63
- ```
64
-
65
- Then:
66
-
67
- 1. Convert SCSS to CSS (remove variables, nesting, mixins)
68
- 2. Replace any SCSS variables with CSS custom properties
69
- 3. Ensure all color/spacing/typography use design tokens
70
- 4. Verify BEM naming convention (hyphens, no underscores)
71
- 5. Save as `style.css`
72
-
73
- ### Step 4: Design Token Mapping
74
-
75
- All style values must use CSS custom properties from `@times-design-system/theme-scss`.
76
-
77
- **Common Design Token Categories**:
78
-
79
- | Category | Tokens | Example |
80
- | -------------- | -------------------------------------------------------------------- | -------------------------------------------- |
81
- | **Colors** | `--interactive-*`, `--text-*`, `--border-*`, `--flag-*`, `--toast-*` | `var(--interactive-primary-fill-default)` |
82
- | **Spacing** | `--spacing-01` through `--spacing-20` | `var(--spacing-03)` |
83
- | **Typography** | `--fontFamily*`, `--fontWeight*`, `--fontSize*`, `--fontLineHeight*` | `var(--fontFamily040)`, `var(--fontSize030)` |
84
- | **Borders** | `--border-radius-*` | `var(--border-radius-full)` |
85
- | **Effects** | `--focus-border`, `--shadow-*` | `var(--focus-border)` |
86
-
87
- **Validation**:
88
-
89
- ```bash
90
- # Check for hardcoded hex colors (should be 0 results)
91
- grep -E '#[0-9a-fA-F]{6}' packages/components-wordpress/src/blocks/<component>/style.css
92
-
93
- # Check for hardcoded values (should use variables)
94
- grep -E '[0-9]+px|[0-9]+rem' packages/components-wordpress/src/blocks/<component>/style.css | grep -v 'var('
95
- ```
96
-
97
- ### Step 5: Variant Coverage
98
-
99
- Ensure **all** variant combinations are styled:
100
-
101
- **Button Example**:
102
-
103
- ```
104
- Intents: --intent-primary ✓, --intent-secondary ✓, --intent-negative ✓
105
- Sizes: --size-small ✓, --size-medium ✓, --size-large ✓
106
- Behaviour: --behaviour-full ✓, --behaviour-hug ✓
107
- States: :hover ✓, :focus-visible ✓, :active ✓, :disabled ✓
108
- Focus rings: ::after with --focus-border ✓
109
- ```
110
-
111
- **Link Example**:
112
-
113
- ```
114
- Intents: --intent-primary ✓, --intent-secondary ✓
115
- Sentiments: --sentiment-brand ✓, --sentiment-utility ✓
116
- Sizes: --size-xsmall ✓, --size-small ✓, --size-medium ✓, --size-large ✓
117
- States: :hover ✓, :focus-visible ✓, :active ✓, :visited ✓, :disabled ✓
118
- ```
119
-
120
- **Chip Example**:
121
-
122
- ```
123
- Intents: --intent-primary ✓ (on/off variants)
124
- Channels: --channel-on ✓, --channel-off ✓
125
- Sizes: --size-small ✓, --size-large ✓
126
- States: :hover ✓, :focus ✓, :active ✓, :disabled ✓
127
- Toggle: on state (bg-dark) ✓, off state (bg-light) ✓
128
- ```
129
-
130
- ### Step 6: Test for Feature Parity
131
-
132
- ```bash
133
- # 1. Line count comparison
134
- echo "React component:"
135
- wc -l packages/components-react/src/<ComponentName>/<ComponentName>.scss
136
- echo "WordPress block:"
137
- wc -l packages/components-wordpress/src/blocks/<component>/style.css
138
-
139
- # Acceptable difference: ±20% (accounting for SCSS nesting/mixins vs flat CSS)
140
- # If WordPress is <50% of React, styles are likely incomplete
141
-
142
- # 2. Variant count comparison
143
- echo "React variants:"
144
- grep -o '\.[a-z-]*--[a-z-]*' packages/components-react/src/<ComponentName>/<ComponentName>.scss | sort -u | wc -l
145
- echo "WordPress variants:"
146
- grep -o '\.[a-z-]*--[a-z-]*' packages/components-wordpress/src/blocks/<component>/style.css | sort -u | wc -l
147
-
148
- # 3. Visual comparison
149
- # - Open React Storybook: packages/components-react (npm run storybook)
150
- # - Open WordPress block in editor: packages/components-wordpress
151
- # - Compare side-by-side for each variant
152
- # - Verify colors match exactly (CSS custom properties should be identical)
153
- ```
154
-
155
- ## Style Structure Template
156
-
157
- Use this template as a reference for comprehensive block styling:
158
-
159
- ```css
160
- /* Base component styles */
161
- .tds-<component > {
162
- --tds-<component>-bg: var(--interactive-primary-fill-default);
163
- --tds-<component>-fg: var(--interactive-primary-text-default);
164
- --tds-<component>-border: var(--interactive-primary-border-default);
165
-
166
- display: flex; /* or block, grid, etc. */
167
- align-items: center;
168
- justify-content: center;
169
- gap: var(--spacing-03);
170
-
171
- border: 1px solid var(--tds-<component>-border);
172
- background-color: var(--tds-<component>-bg);
173
- color: var(--tds-<component>-fg);
174
-
175
- font-family: var(--fontFamily040);
176
- font-weight: var(--fontWeight050);
177
- font-size: var(--fontSize030);
178
- line-height: var(--fontLineHeight040);
179
-
180
- border-radius: 0;
181
- transition:
182
- background-color 0.15s ease,
183
- border-color 0.15s ease,
184
- color 0.15s ease;
185
- cursor: pointer;
186
- }
187
-
188
- /* Intent variants */
189
- .tds-<component > --intent-primary {
190
- --tds-<component>-bg: var(--interactive-primary-fill-default);
191
- --tds-<component>-fg: var(--interactive-primary-text-default);
192
- --tds-<component>-border: var(--interactive-primary-border-default);
193
- }
194
-
195
- .tds-<component > --intent-secondary {
196
- --tds-<component>-bg: var(--interactive-secondary-fill-default);
197
- --tds-<component>-fg: var(--interactive-secondary-text-default);
198
- --tds-<component>-border: var(--interactive-secondary-border-default);
199
- }
200
-
201
- /* Size variants */
202
- .tds-<component > --size-small {
203
- min-height: var(--spacing-15);
204
- padding: var(--spacing-03) var(--spacing-05);
205
- font-size: var(--fontSize020);
206
- }
207
-
208
- .tds-<component > --size-large {
209
- min-height: var(--spacing-20);
210
- padding: var(--spacing-07) var(--spacing-11);
211
- font-size: var(--fontSize040);
212
- }
213
-
214
- /* Behaviour variants */
215
- .tds-<component > --behaviour-full {
216
- width: 100%;
217
- }
218
-
219
- /* State handlers */
220
- .tds-<component > :hover:not(:disabled) {
221
- background-color: var(--interactive-primary-fill-hover);
222
- border-color: var(--interactive-primary-border-hover);
223
- color: var(--interactive-primary-text-hover);
224
- }
225
-
226
- .tds-<component > :active:not(:disabled) {
227
- background-color: var(--interactive-primary-fill-pressed);
228
- border-color: var(--interactive-primary-border-pressed);
229
- color: var(--interactive-primary-text-pressed);
230
- }
231
-
232
- .tds-<component > :focus-visible {
233
- outline: none;
234
- }
235
-
236
- .tds-<component > :focus-visible::after {
237
- content: '';
238
- position: absolute;
239
- inset: calc(var(--spacing-03) * -1);
240
- border: var(--spacing-01) solid var(--focus-border);
241
- border-radius: inherit;
242
- pointer-events: none;
243
- }
244
-
245
- .tds-<component > :disabled {
246
- background-color: var(--interactive-disabled-b);
247
- border-color: transparent;
248
- color: var(--text-disabled);
249
- cursor: not-allowed;
250
- opacity: 0.5;
251
- }
252
-
253
- /* Nested elements */
254
- .tds-<component > __label {
255
- display: inline-flex;
256
- align-items: center;
257
- gap: var(--spacing-03);
258
- }
259
- ```
260
-
261
- ## Build and Verification
262
-
263
- ```bash
264
- cd packages/components-wordpress
265
-
266
- # Build the package
267
- npm run build
268
-
269
- # Verify styles compiled correctly
270
- wc -l dist/blocks/<component>/style.css
271
-
272
- # Test in WordPress
273
- # 1. Copy dist/ to WordPress installation
274
- # 2. Activate plugin or install NPM package
275
- # 3. Add block to page
276
- # 4. Test each variant combination
277
- # 5. Test in patterns (server-side rendering)
278
- ```
279
-
280
- ## Maintenance
281
-
282
- When React component styles change:
283
-
284
- 1. **Identify the change**: What CSS properties, variants, or states changed?
285
- 2. **Update React component**: Make the change in `packages/components-react/src/<ComponentName>/<ComponentName>.scss`
286
- 3. **Sync to WordPress**: Update `packages/components-wordpress/src/blocks/<component>/style.css` with the same change
287
- 4. **Build and test**: `npm run build` in both packages and test in WordPress
288
- 5. **Document the change**: Update CHANGELOG.md in both packages
289
-
290
- ## Common Styling Issues
291
-
292
- | Issue | Cause | Solution |
293
- | -------------------------------- | -------------------------------------- | --------------------------------------------------------------- |
294
- | Block renders but styles missing | CSS not linked in `block.json` | Verify `"style": "file:./style.css"` in block.json |
295
- | Colors don't match React | Hardcoded hex colors or wrong token | Replace with `var(--design-token)` from design system |
296
- | Variants not styling | Modifier CSS not written | Compare to React, copy missing `.tds-<component>--*` selectors |
297
- | Focus ring not visible | Missing `::after` pseudo-element | Add focus-visible handler with border and `var(--focus-border)` |
298
- | Styles different in patterns | render.php classes don't match save.js | Verify class names exactly match between save.js and render.php |
299
- | Line count too low | Styles incomplete or too minimal | Compare to React line count, should be similar (±20%) |
300
-
301
- ## Related Documentation
302
-
303
- - [BLOCK_CREATION_CHECKLIST.md](./BLOCK_CREATION_CHECKLIST.md) - Step-by-step checklist for creating new blocks
304
- - [TRANSFORMATION_GUIDE.md](./TRANSFORMATION_GUIDE.md) - Complete transformation process documentation
305
- - Design tokens: `packages/tokens/README.md`
306
- - Component React source: `packages/components-react/src/`