@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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
675
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
26
|
-
import {base} from
|
|
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
|
-
|
|
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
|
|
41
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
63
|
+
--cnvs-brand-primary-base: red;
|
|
55
64
|
}
|
|
56
65
|
```
|
|
57
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
175
|
-
import {brand, base} from
|
|
176
|
-
import {PrimaryButton} from
|
|
177
|
-
import {CanvasProvider} from
|
|
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
|
-
|
|
191
|
-
|
|
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=
|
|
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
|
-
|
|
211
|
-
|
|
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
|
-
|
|
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
|
|
248
|
+
import {CanvasProvider, defaultBranding} from '@workday/canvas-kit-react/common';
|
|
222
249
|
|
|
223
250
|
<CanvasProvider className={defaultBranding}>
|
|
224
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
>
|
|
29
|
-
>
|
|
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
|
-
|
|
44
|
-
|
|
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.
|
|
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.
|
|
49
|
-
"@workday/canvas-kit-preview-react": "^14.0.0-alpha.
|
|
50
|
-
"@workday/canvas-kit-react": "^14.0.0-alpha.
|
|
51
|
-
"@workday/canvas-kit-styling": "^14.0.0-alpha.
|
|
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": "
|
|
64
|
+
"gitHead": "a455f82fedaccde04d905face6d63445e9c589e6"
|
|
65
65
|
}
|