@workday/canvas-kit-docs 14.0.0-alpha.1256-next.0 → 14.0.0-alpha.1258-next.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.
@@ -1,3 +1,6 @@
1
+ import {StorybookStatusIndicator, DownloadLLMFile} from '@workday/canvas-kit-docs';
2
+
3
+
1
4
  # Canvas Kit 14.0 Upgrade Guide
2
5
 
3
6
  This guide contains an overview of the changes in Canvas Kit v14. Please
@@ -9,13 +12,16 @@ any questions.
9
12
  v14.0 Introduces Workday's new brand direction which includes a new color palette and with it, some
10
13
  styling updates to our components.
11
14
 
12
- **Please consult our [v14 Visual Changes](/help/upgrade-guides/canvas-v14-upgrade-guide/#tab=visual-changes) page for a visual reference of what's changed.**
15
+ **Please consult our
16
+ [v14 Visual Changes](/help/upgrade-guides/canvas-v14-upgrade-guide/#tab=visual-changes) page for a
17
+ visual reference of what's changed.**
13
18
 
14
19
  > **Note:** While v14 does not require an upgrade to our v3 tokens, we strongly advise to upgrade to
15
20
  > the latest to ensure proper branding.
16
21
 
17
22
  ## Table of contents
18
23
 
24
+ - [LLM Assisted Migration](#llm-assisted-migration)
19
25
  - [Codemod](#codemod)
20
26
  - [Instructions](#instructions)
21
27
  - [Tokens](#tokens)
@@ -58,6 +64,30 @@ styling updates to our components.
58
64
  - [Preview](#preview)
59
65
  - [Labs](#labs)
60
66
 
67
+ ## LLM Assisted Migration <StorybookStatusIndicator type="ai" />
68
+
69
+ We provide a **LLM migration mapping file** (`llm-canvas-kit-upgrade-guide-v14.txt`) specifically
70
+ designed for use with LLM-based code assistants (such as [Cursor](https://www.cursor.so/) or similar
71
+ tools). This file is not intended for direct human reference or team documentation, but rather as
72
+ structured input for LLMs to automate and assist with your token migration process.
73
+
74
+ > **Important:** LLMs can make mistakes. Please review changes to be sure they are correct using our
75
+ > docs and upgrade guides.
76
+
77
+ This file contains a compiled LLM consumption version of this v14 Upgrade Guide.
78
+
79
+ **How to use:**
80
+
81
+ - **View raw file**: Open the file in a new tab to see the complete migration mapping
82
+ - **Download as txt**: Save the file locally to upload or paste into your LLM/code assistant
83
+ - **Use with LLM**: Provide the raw content to your LLM/code assistant as context for automated
84
+ migration
85
+
86
+ <DownloadLLMFile
87
+ rawFileLink="https://raw.githubusercontent.com/Workday/canvas-kit/master/modules/docs/llm-txt/llm-canvas-kit-upgrade-guide-v14.txt"
88
+ filename="llm-canvas-kit-upgrade-guide-v14.txt"
89
+ />
90
+
61
91
  ## Codemod
62
92
 
63
93
  We've provided a [codemod](https://github.com/Workday/canvas-kit/tree/master/modules/codemod) to
@@ -114,20 +144,23 @@ yarn canvas-kit-codemod v14 [path]
114
144
  yarn remove @workday/canvas-kit-codemod
115
145
  ```
116
146
 
117
- > **Note**: The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
147
+ > **Note:** The codemod only works on `.js`, `.jsx`, `.ts`, and `.tsx` files. You'll need to
118
148
  > manually edit other file types (`.json`, `.mdx`, `.md`, etc.). You may need to run your linter
119
149
  > after executing the codemod, as its resulting formatting (spacing, quotes, etc.) may not match
120
150
  > your project conventions.
121
151
 
122
152
  ## Tokens
123
153
 
124
- Canvas Kit v14 now uses `@workday/canvas-tokens-web` v3, which introduces new color palettes and
154
+ Canvas Kit v14 uses `@workday/canvas-tokens-web` v3, which introduces new color palettes and
125
155
  deprecates the old "fruity" color names (for example, use `red` instead of `cinnamon`, `blue`
126
156
  instead of `blueberry`, and `green` instead of `greenApple`). We strongly recommend upgrading to
127
157
  `@workday/canvas-tokens-web` v3, as using older versions will not match the new brand guidelines or
128
158
  color system. Although this dependency upgrade is not required, we've offered migration guides and
129
159
  codemods separately from the v14 upgrade so that teams can upgrade when they can.
130
160
 
161
+ For more information and changes, please view our
162
+ [Tokens v3 Upgrade Guide](https://workday.github.io/canvas-tokens/?path=/guides-upgrade-guides-v3-overview--docs).
163
+
131
164
  > **Note:** v3 Tokens should be backwards compatible with older versions of Canvas Kit.
132
165
 
133
166
  Follow these guides to migrate:
@@ -215,7 +248,8 @@ someFunction(ErrorType.Caution);
215
248
 
216
249
  ### New Documentation
217
250
 
218
- We've **significantly** improved our theming documentation. Please consult our new [Canvas Kit Theming Guide](/get-started/for-developers/theming/overview/).
251
+ We've **significantly** improved our theming documentation. Please consult our new
252
+ [Canvas Kit Theming Guide](/get-started/for-developers/theming/overview/).
219
253
 
220
254
  ### Canvas Provider 🚨
221
255
 
@@ -231,7 +265,10 @@ Canvas Provider has been updated to **remove** default branding colors to ensure
231
265
  our CSS variables. Instead of generating a palette and shifting the brightness and darkness with
232
266
  `chroma.js`, we use `oklch` to generate the palette colors.
233
267
 
234
- Prior to v14, `CanvasProvider` created a [cascade barrier](/get-started/for-developers/theming/overview/#what-is-a-cascade-barrier), which redefined brand CSS variables under a class and created a higher specificity. This made it difficult to override brand tokens in certain scenarios. v14 removes that barrier.
268
+ Prior to v14, `CanvasProvider` created a
269
+ [cascade barrier](/get-started/for-developers/theming/overview/#what-is-a-cascade-barrier), which
270
+ redefined brand CSS variables under a class and created a higher specificity. This made it difficult
271
+ to override brand tokens in certain scenarios. v14 removes that barrier.
235
272
 
236
273
  **Before in v13** In v13, the `useTheme` hook would call `createCanvasTheme` which generated a
237
274
  palette given a `main` color via `chroma.js`.
@@ -291,7 +328,6 @@ The reason for this change is to ensure that the CSS variables properly cascade
291
328
  Before in v13, the `CanvasProvider` would add the brand tokens under a class name, creating a higher
292
329
  specificity.
293
330
 
294
-
295
331
  ### useIsRTL
296
332
 
297
333
  **PR:** [#3480](https://github.com/Workday/canvas-kit/pull/3477)
@@ -362,9 +398,9 @@ revolve around the use of our new brand colors. For a better guide on what has c
362
398
  tokens, please view the Tokens v3.0.0
363
399
  [Upgrade Guide](https://workday.github.io/canvas-tokens/?path=/docs/guides-upgrade-guides-v3-overview--docs).
364
400
 
365
-
366
- The following components have been updated (**see [v14 Visual Changes](/help/upgrade-guides/canvas-v14-upgrade-guide/#tab=visual-changes) for a visual reference of the updates**):
367
-
401
+ The following components have been updated (**see
402
+ [v14 Visual Changes](/help/upgrade-guides/canvas-v14-upgrade-guide/#tab=visual-changes) for a visual
403
+ reference of the updates**):
368
404
 
369
405
  - `Breadcrumbs`
370
406
  [#3270](https://github.com/Workday/canvas-kit/pull/3270),[#3447](https://github.com/Workday/canvas-kit/pull/3447)
@@ -671,8 +707,8 @@ Variant names of the preview `StatusIndicator` have been updated by the followin
671
707
  - `gray` → `neutral`
672
708
 
673
709
  The `StatusIndicatorVariant` type has been updated to contain the new variant names listed above. If
674
- you use the old variant values, update to use the new ones mapped above. It has also been
675
- deprecated. Use `StatusIndicatorProps['variant']` instead.
710
+ you use the old variant values, update to use the new ones mapped above. Use
711
+ `StatusIndicatorProps['variant']` instead.
676
712
 
677
713
  **Before in v13**
678
714
 
@@ -22,23 +22,26 @@ import textInputImage from './images/v14-text-input.png';
22
22
 
23
23
  # Canvas Kit 14.0 Visual Changes
24
24
 
25
- This guide contains an overview of the changes in Canvas Kit v14. If you have any issues, feel free to report them [here](https://github.com/Workday/canvas-kit/issues). For a mode detailed overview of the changes in v14, please view our [v14 Upgrade Guide](/help/upgrade-guides/canvas-v14-upgrade-guide/).
25
+ This guide contains an overview of the changes in Canvas Kit v14. If you have any issues, feel free
26
+ to report them [here](https://github.com/Workday/canvas-kit/issues). For a mode detailed overview of
27
+ the changes in v14, please view our
28
+ [v14 Upgrade Guide](/help/upgrade-guides/canvas-v14-upgrade-guide/).
26
29
 
27
30
  <Graphic src={{url: avatarImage}} />
28
31
  <Graphic src={{url: breadcrumbsImage}} />
32
+ <Graphic src={{url: primaryButtonImage}} />
33
+ <Graphic src={{url: secondaryButtonImage}} />
34
+ <Graphic src={{url: tertiaryButtonImage}} />
29
35
  <Graphic src={{url: cardImage}} />
30
36
  <Graphic src={{url: checkboxImage}} />
37
+ <Graphic src={{url: radioImage}} />
38
+ <Graphic src={{url: selectImage}} />
39
+ <Graphic src={{url: textAreaImage}} />
40
+ <Graphic src={{url: textInputImage}} />
31
41
  <Graphic src={{url: countBadgeImage}} />
32
42
  <Graphic src={{url: expandableImage}} />
33
43
  <Graphic src={{url: infoHighlightImage}} />
34
44
  <Graphic src={{url: loadingDotsImage}} />
35
45
  <Graphic src={{url: pillImage}} />
36
- <Graphic src={{url: primaryButtonImage}} />
37
- <Graphic src={{url: radioImage}} />
38
- <Graphic src={{url: secondaryButtonImage}} />
39
- <Graphic src={{url: selectImage}} />
40
46
  <Graphic src={{url: statusIndicatorImage}} />
41
- <Graphic src={{url: tabsImage}} />
42
- <Graphic src={{url: tertiaryButtonImage}} />
43
- <Graphic src={{url: textAreaImage}} />
44
- <Graphic src={{url: textInputImage}} />
47
+ <Graphic src={{url: tabsImage}} />
@@ -7,54 +7,67 @@ import Theming from './examples/Theming';
7
7
 
8
8
  ## Overview
9
9
 
10
- Canvas Kit v14 introduces a significant shift in our approach to theming: we've moved away from JavaScript-based theme objects to CSS variables. This change provides better performance, improved developer experience, and greater flexibility for theming applications.
10
+ Canvas Kit v14 introduces a significant shift in our approach to theming: we've moved away from
11
+ JavaScript-based theme objects to CSS variables. This change provides better performance, improved
12
+ developer experience, and greater flexibility for theming applications.
11
13
 
12
14
  ## Migration from v10 Theme Prop to v14 CSS Variables
13
15
 
14
16
  ### The Evolution
15
17
 
16
- **Canvas Kit v10** introduced CSS tokens through the `@workday/canvas-tokens-web` package, providing a foundation for consistent design system values.
18
+ **Canvas Kit v10** introduced CSS tokens through the `@workday/canvas-tokens-web` package, providing
19
+ a foundation for consistent design system values.
17
20
 
18
- **Canvas Kit v14** Removes the cascade barrier created by the `CanvasProvider`, allowing CSS variables to work as intended.
21
+ **Canvas Kit v14** Removes the cascade barrier created by the `CanvasProvider`, allowing CSS
22
+ variables to work as intended.
19
23
 
20
24
  ## Old Approach (v10-v13)
21
25
 
22
26
  The old theming approach used JavaScript objects passed to the `CanvasProvider` theme prop:
23
27
 
24
28
  ```tsx
25
- import {CanvasProvider} from "@workday/canvas-kit-react/common"
26
- import {base} from "@workday/canvas-tokens-web"
29
+ import {CanvasProvider} from '@workday/canvas-kit-react/common';
30
+ import {base} from '@workday/canvas-tokens-web';
27
31
 
28
32
  <CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
29
- <App/>
30
- </CanvasProvider>
33
+ <App />
34
+ </CanvasProvider>;
31
35
  ```
32
36
 
33
37
  This would use `chroma.js` to generate a palette based on the `main` color provided.
34
38
 
35
39
  **Why we're moving away from this approach:**
40
+
36
41
  - Performance overhead from JavaScript theme object processing
37
42
  - Limited flexibility for complex theming scenarios
38
43
  - Inconsistent cascade behavior
39
44
 
40
- Any time `theme` is passed, the `CanvasProvider` would generate a palette and attach brand variables via a `className` scoping those brand variables to a wrapping div.
41
- In order for us to provide a better solution to theming that is scalable and is more aligned with our CSS variables, we changed this approach.
45
+ Any time `theme` is passed, the `CanvasProvider` would generate a palette and attach brand variables
46
+ via a `className` scoping those brand variables to a wrapping div. In order for us to provide a
47
+ better solution to theming that is scalable and is more aligned with our CSS variables, we changed
48
+ this approach.
42
49
 
43
50
  ## What is a Cascade Barrier?
44
51
 
45
- When we say "cascade barrier", we're talking about how [CSS cascades](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Cascade) and takes precedence. Take the following example:
52
+ When we say "cascade barrier", we're talking about how
53
+ [CSS cascades](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Cascade) and takes
54
+ precedence. Take the following example:
46
55
 
47
56
  ```css
48
57
  :root {
49
- --cnbvs-brand-primary-base: blue;
58
+ --cnbvs-brand-primary-base: blue;
50
59
  }
51
60
 
52
61
  // the element with the class .my-app will have a higher specificity than root, creating a barrier where the CSS variables gets redefined and takes precedence over what is defined at root.
53
62
  .my-app {
54
- --cnvs-brand-primary-base: red;
63
+ --cnvs-brand-primary-base: red;
55
64
  }
56
65
  ```
57
- In the case of the `CanvasProvider` prior to v14, all our brand tokens where defined within a class and scoped to the `div` that the `CanvasProvider` created. This meant that anything set on `:root` or outside of the `CanvasProvider` would not be able to cascade down to the components within the `CanvasProvider`.
66
+
67
+ In the case of the `CanvasProvider` prior to v14, all our brand tokens where defined within a class
68
+ and scoped to the `div` that the `CanvasProvider` created. This meant that anything set on `:root`
69
+ or outside of the `CanvasProvider` would not be able to cascade down to the components within the
70
+ `CanvasProvider`.
58
71
 
59
72
  ## ✅ Preferred Approach (v14+)
60
73
 
@@ -62,7 +75,8 @@ Canvas Kit v14 promotes using CSS variables for theming, which can be applied in
62
75
 
63
76
  ### Method 1: Global CSS Variables (Recommended)
64
77
 
65
- Apply theming at the global level by importing CSS variable files and overriding values in your root CSS:
78
+ Apply theming at the global level by importing CSS variable files and overriding values in your root
79
+ CSS:
66
80
 
67
81
  ```css
68
82
  /* index.css */
@@ -82,13 +96,17 @@ Apply theming at the global level by importing CSS variable files and overriding
82
96
  }
83
97
  ```
84
98
 
85
- > **Note:** You should only import the CSS variables *once* at the root level of your application. If your application renders within another environment that imports these and sets them, **do not** re import them.
99
+ > **Note:** You should only import the CSS variables _once_ at the root level of your application.
100
+ > If your application renders within another environment that imports these and sets them, **do
101
+ > not** re import them.
86
102
 
87
103
  ### Method 2: Provider-Level CSS Variables
88
104
 
89
- Use Canvas Kit's `createStyles` utility to generate themed class names that can be applied to specific components or sections:
105
+ Use Canvas Kit's `createStyles` utility to generate themed class names that can be applied to
106
+ specific components or sections:
90
107
 
91
- > **Note:** Doing the following **will create a cascade barrier**. Only use this method if you intentionally want to override the default theme.
108
+ > **Note:** Doing the following **will create a cascade barrier**. Only use this method if you
109
+ > intentionally want to override the default theme.
92
110
 
93
111
  ```tsx
94
112
  import {createStyles}from "@workday/canvas-kit-styling"
@@ -121,7 +139,9 @@ const themedBrand = createStyles({
121
139
  Canvas Kit provides three layers of CSS variables.
122
140
 
123
141
  ### Base Tokens (`base/_variables.css`)
142
+
124
143
  Base tokens define foundation palette and design values.
144
+
125
145
  ```css
126
146
  --cnvs-base-palette-blue-600: oklch(0.5198 0.1782 256.11 / 1);
127
147
  --cnvs-base-palette-magenta-600: oklch(0.534 0.183 344.19 / 1);
@@ -130,7 +150,9 @@ Base tokens define foundation palette and design values.
130
150
  ```
131
151
 
132
152
  ### Brand Tokens (`brand/_variables.css`)
153
+
133
154
  Brand tokens define semantic color assignments.
155
+
134
156
  ```css
135
157
  --cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600);
136
158
  --cnvs-brand-primary-accent: var(--cnvs-base-palette-neutral-0);
@@ -139,7 +161,9 @@ Brand tokens define semantic color assignments.
139
161
  ```
140
162
 
141
163
  ### System Tokens (`system/_variables.css`)
164
+
142
165
  System tokens define component-specific values.
166
+
143
167
  ```css
144
168
  --cnvs-sys-color-bg-primary-default: var(--cnvs-base-palette-blue-600);
145
169
  --cnvs-sys-color-text-primary-default: var(--cnvs-base-palette-blue-600);
@@ -171,10 +195,10 @@ System tokens define component-specific values.
171
195
  ### App-Specific Theming
172
196
 
173
197
  ```tsx
174
- import {createStyles} from "@workday/canvas-kit-styling";
175
- import {brand, base} from "@workday/canvas-tokens-web";
176
- import {PrimaryButton} from "@workday/canvas-kit-react/button";
177
- import {CanvasProvider} from "@workday/canvas-kit-react/common";
198
+ import {createStyles} from '@workday/canvas-kit-styling';
199
+ import {brand, base} from '@workday/canvas-tokens-web';
200
+ import {PrimaryButton} from '@workday/canvas-kit-react/button';
201
+ import {CanvasProvider} from '@workday/canvas-kit-react/common';
178
202
 
179
203
  const greenTheme = createStyles({
180
204
  [brand.primary.base]: base.green600,
@@ -187,9 +211,8 @@ const greenTheme = createStyles({
187
211
  });
188
212
 
189
213
  <CanvasProvider className={greenTheme}>
190
- <PrimaryButton>Click me</PrimaryButton>
191
- </CanvasProvider>
192
- );
214
+ <PrimaryButton>Click me</PrimaryButton>
215
+ </CanvasProvider>;
193
216
  ```
194
217
 
195
218
  <ExampleCodeBlock code={Theming} />
@@ -198,7 +221,7 @@ const greenTheme = createStyles({
198
221
 
199
222
  ```css
200
223
  /* Dark mode theming */
201
- [data-theme="dark"] {
224
+ [data-theme='dark'] {
202
225
  --cnvs-sys-color-bg-default: var(--cnvs-base-palette-neutral-950);
203
226
  --cnvs-sys-color-text-default: var(--cnvs-base-palette-neutral-50);
204
227
  --cnvs-sys-color-border-container: var(--cnvs-base-palette-slate-700);
@@ -207,25 +230,30 @@ const greenTheme = createStyles({
207
230
  ```
208
231
 
209
232
  ### RTL Support
210
- Canvas Kit supports RTL out of the box. Our components are styled to use [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values). If you want to add additional styles based on RTL,
211
- you can also use the `:dir` [pseudo selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir).
233
+
234
+ Canvas Kit supports RTL out of the box. Our components are styled to use
235
+ [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
236
+ If you want to add additional styles based on RTL, you can also use the `:dir`
237
+ [pseudo selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir).
212
238
 
213
239
  <ExampleCodeBlock code={RTL} />
214
240
 
215
241
  ### Resetting to Default Brand Theme
216
242
 
217
- If you need to reset the theme in parts of your application, there's a few ways to do this.
218
- We export a `defaultBranding` class that can be applied to the `CanvasProvider` which can wrap parts of your application.
243
+ If you need to reset the theme in parts of your application, there's a few ways to do this. We
244
+ export a `defaultBranding` class that can be applied to the `CanvasProvider` which can wrap parts of
245
+ your application.
219
246
 
220
247
  ```tsx
221
- import {CanvasProvider, defaultBranding} from "@workday/canvas-kit-react/common"
248
+ import {CanvasProvider, defaultBranding} from '@workday/canvas-kit-react/common';
222
249
 
223
250
  <CanvasProvider className={defaultBranding}>
224
- <SomeSubComponent/>
225
- </CanvasProvider>
251
+ <SomeSubComponent />
252
+ </CanvasProvider>;
226
253
  ```
227
254
 
228
- > **Note:** Doing the following **will create a cascade barrier**. Only use this method if you intentionally want to override the default theme.
255
+ > **Note:** Doing the following **will create a cascade barrier**. Only use this method if you
256
+ > intentionally want to override the default theme.
229
257
 
230
258
  ## Migration Guide
231
259
 
@@ -278,22 +306,24 @@ Replace theme-based `CanvasProvider` usage with CSS class-based theming.
278
306
  </CanvasProvider>
279
307
  ```
280
308
 
281
- > **Note:** Using a class means you will need to define each property of the palette for full control over theming.
309
+ > **Note:** Using a class means you will need to define each property of the palette for full
310
+ > control over theming.
282
311
 
283
312
  ### Step 4: Test Component Rendering
284
313
 
285
314
  Verify that Canvas Kit components (like `PrimaryButton`) correctly use the new CSS variables.
286
315
 
287
316
  ```tsx
288
- import {PrimaryButton} from "@workday/canvas-kit-react/button";
317
+ import {PrimaryButton} from '@workday/canvas-kit-react/button';
289
318
 
290
319
  // This should automatically use your CSS variable overrides
291
- <PrimaryButton>Themed Button</PrimaryButton>
320
+ <PrimaryButton>Themed Button</PrimaryButton>;
292
321
  ```
293
322
 
294
323
  ## Best Practices
295
324
 
296
325
  ### 1. Use Semantic Token Names
326
+
297
327
  Use brand tokens instead of base tokens for better maintainability.
298
328
 
299
329
  ```css
@@ -304,8 +334,8 @@ Use brand tokens instead of base tokens for better maintainability.
304
334
  --cnvs-base-palette-blue-600: blue;
305
335
  ```
306
336
 
307
-
308
337
  ### 2. Test Accessibility
338
+
309
339
  Ensure color combinations meet accessibility standards.
310
340
 
311
341
  ```css
@@ -318,7 +348,8 @@ Ensure color combinations meet accessibility standards.
318
348
 
319
349
  ### 3. Avoid Component Level Theming
320
350
 
321
- Theming is meant to be done at the app level or root level of the application. Avoid theming at the component level.
351
+ Theming is meant to be done at the app level or root level of the application. Avoid theming at the
352
+ component level.
322
353
 
323
354
  ```tsx
324
355
  /* ✅ Good - App level theming */
@@ -351,9 +382,11 @@ const myCustomTheme = createStyles({
351
382
 
352
383
  ## Component Compatibility
353
384
 
354
- All Canvas Kit components in v14 automatically consume CSS variables. No component-level changes are required when switching from the theme prop approach to CSS variables.
385
+ All Canvas Kit components in v14 automatically consume CSS variables. No component-level changes are
386
+ required when switching from the theme prop approach to CSS variables.
355
387
 
356
388
  ### Supported Components
389
+
357
390
  - ✅ All Button variants (`PrimaryButton`, `SecondaryButton`, etc.)
358
391
  - ✅ Form components (`TextInput`, `FormField`, etc.)
359
392
  - ✅ Layout components (`Card`, `Modal`, etc.)
@@ -371,8 +404,13 @@ The CSS variable approach provides several performance improvements:
371
404
  ## Troubleshooting
372
405
 
373
406
  ### Theme Not Applied
407
+
374
408
  Ensure CSS variable files are imported in the correct order.
375
409
 
410
+ > **Note:** You should only import the CSS variables _once_ at the root level of your application.
411
+ > If your application renders within another environment that imports these and sets them, **do
412
+ > not** re import them.
413
+
376
414
  ```css
377
415
  /* Correct order */
378
416
  @import '@workday/canvas-tokens-web/css/base/_variables.css';
@@ -386,6 +424,7 @@ Ensure CSS variable files are imported in the correct order.
386
424
  ```
387
425
 
388
426
  ### Inconsistent Theming
427
+
389
428
  Check for CSS specificity issues.
390
429
 
391
430
  ```css
@@ -401,10 +440,11 @@ Check for CSS specificity issues.
401
440
  ```
402
441
 
403
442
  ### Missing Token Values
443
+
404
444
  Verify all required CSS token files are imported and token names are correct.
405
445
 
406
446
  ```tsx
407
- import {brand, base, system} from "@workday/canvas-tokens-web";
447
+ import {brand, base, system} from '@workday/canvas-tokens-web';
408
448
 
409
449
  // Check token availability in development
410
450
  console.log(brand.primary.base); // Should output CSS variable name
@@ -412,6 +452,9 @@ console.log(brand.primary.base); // Should output CSS variable name
412
452
 
413
453
  ## Conclusion
414
454
 
415
- The migration to CSS variables in Canvas Kit v14 provides a more performant, flexible, and maintainable theming solution. By following this guide and best practices, you can successfully migrate your applications and take advantage of the improved theming capabilities.
455
+ The migration to CSS variables in Canvas Kit v14 provides a more performant, flexible, and
456
+ maintainable theming solution. By following this guide and best practices, you can successfully
457
+ migrate your applications and take advantage of the improved theming capabilities.
416
458
 
417
- For additional support and examples, refer to the Canvas Kit Storybook documentation and the `@workday/canvas-tokens` [repository](https://github.com/Workday/canvas-tokens).
459
+ For additional support and examples, refer to the Canvas Kit Storybook documentation and the
460
+ `@workday/canvas-tokens` [repository](https://github.com/Workday/canvas-tokens).
@@ -25,8 +25,9 @@ use with LLM-based code assistants (such as [Cursor](https://www.cursor.so/) or
25
25
  file is not intended for direct human reference or team documentation, but rather as structured
26
26
  input for LLMs to automate and assist with your token migration process.
27
27
 
28
- > The LLM migration file is regularly updated to reflect the latest token mappings and best
29
- > practices. For more details, see other sections of this migration guide.
28
+ > Important: LLMs can make mistakes. Please review changes to be sure they are correct using our
29
+ > docs and upgrade guides. The LLM migration file is regularly updated to reflect the latest token
30
+ > mappings and best practices. For more details, see other sections of this migration guide.
30
31
 
31
32
  This file contains a comprehensive mapping of old Canvas Kit token usages to their new equivalents
32
33
  in `@workday/canvas-tokens-web`, along with migration tips and examples and formatted for optimal
@@ -40,8 +41,8 @@ LLM consumption.
40
41
  migration
41
42
 
42
43
  <DownloadLLMFile
43
- rawFileDir="https://raw.githubusercontent.com/Workday/canvas-kit/master/modules/docs/llm-txt/llm-token-migration-14.0.0.txt"
44
- filenames="llm-token-migration-14.0.0.txt"
44
+ rawFileLink="https://raw.githubusercontent.com/Workday/canvas-kit/master/modules/docs/llm-txt/llm-token-migration-14.txt"
45
+ filename="llm-token-migration-14.0.0.txt"
45
46
  />
46
47
 
47
48
  ## Core Principles
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@workday/canvas-kit-docs",
3
- "version": "14.0.0-alpha.1256-next.0",
3
+ "version": "14.0.0-alpha.1258-next.0",
4
4
  "description": "Documentation components of Canvas Kit components",
5
5
  "author": "Workday, Inc. (https://www.workday.com)",
6
6
  "license": "Apache-2.0",
@@ -45,10 +45,10 @@
45
45
  "@emotion/styled": "^11.6.0",
46
46
  "@stackblitz/sdk": "^1.11.0",
47
47
  "@storybook/csf": "0.0.1",
48
- "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1256-next.0",
49
- "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1256-next.0",
50
- "@workday/canvas-kit-react": "^14.0.0-alpha.1256-next.0",
51
- "@workday/canvas-kit-styling": "^14.0.0-alpha.1256-next.0",
48
+ "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1258-next.0",
49
+ "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1258-next.0",
50
+ "@workday/canvas-kit-react": "^14.0.0-alpha.1258-next.0",
51
+ "@workday/canvas-kit-styling": "^14.0.0-alpha.1258-next.0",
52
52
  "@workday/canvas-system-icons-web": "^3.0.35",
53
53
  "@workday/canvas-tokens-web": "3.0.0-alpha.12",
54
54
  "markdown-to-jsx": "^7.2.0",
@@ -61,5 +61,5 @@
61
61
  "mkdirp": "^1.0.3",
62
62
  "typescript": "5.0"
63
63
  },
64
- "gitHead": "ecb8230f9b648de52e89d8b84340dcd31b2514b2"
64
+ "gitHead": "a455f82fedaccde04d905face6d63445e9c589e6"
65
65
  }