@workday/canvas-kit-docs 16.0.0-alpha.0499-next.0 → 16.0.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 (122) hide show
  1. package/dist/es6/lib/docs.js +2801 -17
  2. package/dist/es6/lib/specs.js +1549 -615
  3. package/dist/es6/lib/stackblitzFiles/packageJSONFile.js +5 -5
  4. package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts +5 -5
  5. package/dist/es6/utils/parseSpecFile.d.ts.map +1 -1
  6. package/dist/es6/utils/parseSpecFile.js +27 -6
  7. package/dist/mdx/16.0-UPGRADE-GUIDE.mdx +148 -3
  8. package/dist/mdx/react/common/mdx/Theming.mdx +75 -431
  9. package/dist/mdx/react/common/mdx/examples/SimplifiedSanaSetup.tsx +35 -0
  10. package/dist/mdx/react/common/mdx/examples/ThemingBrandScope.tsx +29 -0
  11. package/package.json +6 -6
  12. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.d.ts +0 -2
  13. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.d.ts.map +0 -1
  14. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.js +0 -31
  15. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/FilterListWithLiveStatus.d.ts +0 -2
  16. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/FilterListWithLiveStatus.d.ts.map +0 -1
  17. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/FilterListWithLiveStatus.js +0 -43
  18. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/HiddenLiveRegion.d.ts +0 -2
  19. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/HiddenLiveRegion.d.ts.map +0 -1
  20. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/HiddenLiveRegion.js +0 -27
  21. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/IconButtonsWithLiveBadges.d.ts +0 -2
  22. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/IconButtonsWithLiveBadges.d.ts.map +0 -1
  23. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/IconButtonsWithLiveBadges.js +0 -56
  24. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/TextInputWithLiveError.d.ts +0 -2
  25. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/TextInputWithLiveError.d.ts.map +0 -1
  26. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/TextInputWithLiveError.js +0 -19
  27. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/VisibleLiveRegion.d.ts +0 -2
  28. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/VisibleLiveRegion.d.ts.map +0 -1
  29. package/dist/es6/mdx/accessibility/examples/AriaLiveRegions/VisibleLiveRegion.js +0 -35
  30. package/dist/es6/mdx/accessibility/examples/GlobalHeader.d.ts +0 -8
  31. package/dist/es6/mdx/accessibility/examples/GlobalHeader.d.ts.map +0 -1
  32. package/dist/es6/mdx/accessibility/examples/GlobalHeader.js +0 -149
  33. package/dist/es6/mdx/accessibility/examples/PageStructure/BreadcrumbNavRegion.d.ts +0 -2
  34. package/dist/es6/mdx/accessibility/examples/PageStructure/BreadcrumbNavRegion.d.ts.map +0 -1
  35. package/dist/es6/mdx/accessibility/examples/PageStructure/BreadcrumbNavRegion.js +0 -12
  36. package/dist/es6/mdx/accessibility/examples/PageStructure/FullPageDemo.d.ts +0 -2
  37. package/dist/es6/mdx/accessibility/examples/PageStructure/FullPageDemo.d.ts.map +0 -1
  38. package/dist/es6/mdx/accessibility/examples/PageStructure/FullPageDemo.js +0 -46
  39. package/dist/es6/mdx/accessibility/examples/PageStructure/LandmarkRegions.d.ts +0 -2
  40. package/dist/es6/mdx/accessibility/examples/PageStructure/LandmarkRegions.d.ts.map +0 -1
  41. package/dist/es6/mdx/accessibility/examples/PageStructure/LandmarkRegions.js +0 -28
  42. package/dist/es6/mdx/accessibility/examples/Popups/InlinePopupNoPortal.d.ts +0 -2
  43. package/dist/es6/mdx/accessibility/examples/Popups/InlinePopupNoPortal.d.ts.map +0 -1
  44. package/dist/es6/mdx/accessibility/examples/Popups/InlinePopupNoPortal.js +0 -62
  45. package/dist/es6/mdx/accessibility/examples/Popups/InlinePortalPopup.d.ts +0 -7
  46. package/dist/es6/mdx/accessibility/examples/Popups/InlinePortalPopup.d.ts.map +0 -1
  47. package/dist/es6/mdx/accessibility/examples/Popups/InlinePortalPopup.js +0 -65
  48. package/dist/es6/mdx/accessibility/examples/Popups/PopupAriaOwns.d.ts +0 -7
  49. package/dist/es6/mdx/accessibility/examples/Popups/PopupAriaOwns.d.ts.map +0 -1
  50. package/dist/es6/mdx/accessibility/examples/Popups/PopupAriaOwns.js +0 -46
  51. package/dist/es6/mdx/accessibility/examples/SidePanelWithNavigation.d.ts +0 -3
  52. package/dist/es6/mdx/accessibility/examples/SidePanelWithNavigation.d.ts.map +0 -1
  53. package/dist/es6/mdx/accessibility/examples/SidePanelWithNavigation.js +0 -100
  54. package/dist/es6/mdx/accessibility/examples/SidePanelWithOverlay.d.ts +0 -2
  55. package/dist/es6/mdx/accessibility/examples/SidePanelWithOverlay.d.ts.map +0 -1
  56. package/dist/es6/mdx/accessibility/examples/SidePanelWithOverlay.js +0 -30
  57. package/dist/es6/mdx/accessibility/examples/Table/WithColumnHeaderFilters.d.ts +0 -2
  58. package/dist/es6/mdx/accessibility/examples/Table/WithColumnHeaderFilters.d.ts.map +0 -1
  59. package/dist/es6/mdx/accessibility/examples/Table/WithColumnHeaderFilters.js +0 -101
  60. package/dist/es6/mdx/accessibility/examples/Table/WithExpandableRows.d.ts +0 -2
  61. package/dist/es6/mdx/accessibility/examples/Table/WithExpandableRows.d.ts.map +0 -1
  62. package/dist/es6/mdx/accessibility/examples/Table/WithExpandableRows.js +0 -115
  63. package/dist/es6/mdx/accessibility/examples/Table/WithFormFields.d.ts +0 -2
  64. package/dist/es6/mdx/accessibility/examples/Table/WithFormFields.d.ts.map +0 -1
  65. package/dist/es6/mdx/accessibility/examples/Table/WithFormFields.js +0 -79
  66. package/dist/es6/mdx/accessibility/examples/Table/WithSelectableRows.d.ts +0 -2
  67. package/dist/es6/mdx/accessibility/examples/Table/WithSelectableRows.d.ts.map +0 -1
  68. package/dist/es6/mdx/accessibility/examples/Table/WithSelectableRows.js +0 -89
  69. package/dist/es6/mdx/accessibility/examples/Table/WithSortableColumnHeaders.d.ts +0 -2
  70. package/dist/es6/mdx/accessibility/examples/Table/WithSortableColumnHeaders.d.ts.map +0 -1
  71. package/dist/es6/mdx/accessibility/examples/Table/WithSortableColumnHeaders.js +0 -114
  72. package/dist/es6/mdx/installBlock.d.ts +0 -6
  73. package/dist/es6/mdx/installBlock.d.ts.map +0 -1
  74. package/dist/es6/mdx/installBlock.js +0 -35
  75. package/dist/es6/mdx/style-props/examples/Background.d.ts +0 -2
  76. package/dist/es6/mdx/style-props/examples/Background.d.ts.map +0 -1
  77. package/dist/es6/mdx/style-props/examples/Background.js +0 -13
  78. package/dist/es6/mdx/style-props/examples/Border.d.ts +0 -2
  79. package/dist/es6/mdx/style-props/examples/Border.d.ts.map +0 -1
  80. package/dist/es6/mdx/style-props/examples/Border.js +0 -11
  81. package/dist/es6/mdx/style-props/examples/Color.d.ts +0 -2
  82. package/dist/es6/mdx/style-props/examples/Color.d.ts.map +0 -1
  83. package/dist/es6/mdx/style-props/examples/Color.js +0 -10
  84. package/dist/es6/mdx/style-props/examples/Depth.d.ts +0 -2
  85. package/dist/es6/mdx/style-props/examples/Depth.d.ts.map +0 -1
  86. package/dist/es6/mdx/style-props/examples/Depth.js +0 -11
  87. package/dist/es6/mdx/style-props/examples/Flex.d.ts +0 -2
  88. package/dist/es6/mdx/style-props/examples/Flex.d.ts.map +0 -1
  89. package/dist/es6/mdx/style-props/examples/Flex.js +0 -9
  90. package/dist/es6/mdx/style-props/examples/FlexItem.d.ts +0 -2
  91. package/dist/es6/mdx/style-props/examples/FlexItem.d.ts.map +0 -1
  92. package/dist/es6/mdx/style-props/examples/FlexItem.js +0 -9
  93. package/dist/es6/mdx/style-props/examples/Grid.d.ts +0 -2
  94. package/dist/es6/mdx/style-props/examples/Grid.d.ts.map +0 -1
  95. package/dist/es6/mdx/style-props/examples/Grid.js +0 -7
  96. package/dist/es6/mdx/style-props/examples/GridItem.d.ts +0 -2
  97. package/dist/es6/mdx/style-props/examples/GridItem.d.ts.map +0 -1
  98. package/dist/es6/mdx/style-props/examples/GridItem.js +0 -7
  99. package/dist/es6/mdx/style-props/examples/Layout.d.ts +0 -2
  100. package/dist/es6/mdx/style-props/examples/Layout.d.ts.map +0 -1
  101. package/dist/es6/mdx/style-props/examples/Layout.js +0 -10
  102. package/dist/es6/mdx/style-props/examples/Other.d.ts +0 -2
  103. package/dist/es6/mdx/style-props/examples/Other.d.ts.map +0 -1
  104. package/dist/es6/mdx/style-props/examples/Other.js +0 -11
  105. package/dist/es6/mdx/style-props/examples/Position.d.ts +0 -2
  106. package/dist/es6/mdx/style-props/examples/Position.d.ts.map +0 -1
  107. package/dist/es6/mdx/style-props/examples/Position.js +0 -12
  108. package/dist/es6/mdx/style-props/examples/Space.d.ts +0 -2
  109. package/dist/es6/mdx/style-props/examples/Space.d.ts.map +0 -1
  110. package/dist/es6/mdx/style-props/examples/Space.js +0 -9
  111. package/dist/es6/mdx/style-props/examples/Text.d.ts +0 -2
  112. package/dist/es6/mdx/style-props/examples/Text.d.ts.map +0 -1
  113. package/dist/es6/mdx/style-props/examples/Text.js +0 -3
  114. package/dist/es6/mdx/tokens/StorybookInformationHighlight/index.d.ts +0 -2
  115. package/dist/es6/mdx/tokens/StorybookInformationHighlight/index.d.ts.map +0 -1
  116. package/dist/es6/mdx/tokens/StorybookInformationHighlight/index.js +0 -6
  117. package/dist/es6/mdx/versionsTable.d.ts +0 -2
  118. package/dist/es6/mdx/versionsTable.d.ts.map +0 -1
  119. package/dist/es6/mdx/versionsTable.js +0 -60
  120. package/dist/es6/mdx/welcomePage.d.ts +0 -2
  121. package/dist/es6/mdx/welcomePage.d.ts.map +0 -1
  122. package/dist/es6/mdx/welcomePage.js +0 -57
@@ -1,497 +1,141 @@
1
1
  import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
2
2
 
3
- import RTL from './examples/RTL';
4
- import Theming from './examples/Theming';
3
+ import ThemingBrandScope from './examples/ThemingBrandScope';
4
+ import SimplifiedSetup from './examples/SimplifiedSanaSetup';
5
5
 
6
6
 
7
7
  # Canvas Kit Theming Guide
8
8
 
9
- ## Overview
9
+ Canvas Kit v16 components are Sana-aligned out of the box. The Sana Canvas **theme** is a separate,
10
+ opt-in step that updates brand colors, neutrals, surfaces, and shapes at the application
11
+ level.
10
12
 
11
- Canvas Kit v14 and v15 introduce a significant shift in our approach to theming: we've moved away
12
- from JavaScript-based theme objects to CSS variables. This change provides better performance,
13
- improved developer experience, and greater flexibility for theming applications.
13
+ For a full list of what changes when you opt in, see the
14
+ [v16 Upgrade Guide](https://workday.github.io/canvas-kit/?path=/docs/guides-upgrade-guides-v-16-0-overview--docs#sana-canvas-theme).
14
15
 
15
- > **📌 Quick Start:**
16
- >
17
- > 1. **Import CSS variables once** at the root level of your application (e.g., in `index.css`)
18
- > 2. **Override tokens at `:root`** for global theming — this is the recommended approach
19
- > 3. **Use `CanvasProvider` scoped theming only** for specific scenarios like multi-brand sections
20
- > or embedded components
21
- >
22
- > If your application renders within an environment that already imports these CSS variables, **do
23
- > not re-import them**.
16
+ ## Sana Canvas Theme
24
17
 
25
- View our latest tokens documentation
26
- [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
27
-
28
- ## Migration from v10 Theme Prop to v14 CSS Variables
29
-
30
- ### The Evolution
31
-
32
- **Canvas Kit v10** introduced CSS tokens through the `@workday/canvas-tokens-web` package, providing
33
- a foundation for consistent design system values.
34
-
35
- **Canvas Kit v14** Removes the cascade barrier created by the `CanvasProvider`, allowing CSS
36
- variables to work as intended.
37
-
38
- ## Old Approach (v10-v13)
39
-
40
- The old theming approach used JavaScript objects passed to the `CanvasProvider` theme prop:
41
-
42
- ```tsx
43
- import {CanvasProvider} from '@workday/canvas-kit-react/common';
44
- import {base} from '@workday/canvas-tokens-web';
45
-
46
- <CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
47
- <App />
48
- </CanvasProvider>;
49
- ```
50
-
51
- This would use `chroma.js` to generate a palette based on the `main` color provided.
52
-
53
- **Why we're moving away from this approach:**
54
-
55
- - Performance overhead from JavaScript theme object processing
56
- - Limited flexibility for complex theming scenarios
57
- - Inconsistent cascade behavior
58
-
59
- Any time `theme` is passed, the `CanvasProvider` would generate a palette and attach brand variables
60
- via a `className` scoping those brand variables to a wrapping div. In order for us to provide a
61
- better solution to theming that is scalable and is more aligned with our CSS variables, we changed
62
- this approach.
63
-
64
- **Note:** While we support theme overrides, we advise to use global theming via CSS Variables.
65
-
66
- ## What is a Cascade Barrier?
67
-
68
- When we say "cascade barrier", we're talking about how
69
- [CSS cascades](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Cascade) and takes
70
- precedence. Take the following example:
71
-
72
- ```css
73
- :root {
74
- --cnbvs-brand-primary-base: blue;
75
- }
76
-
77
- // 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.
78
- .my-app {
79
- --cnvs-brand-primary-base: red;
80
- }
81
- ```
82
-
83
- In the case of the `CanvasProvider` prior to v14, all our brand tokens where defined within a class
84
- and scoped to the `div` that the `CanvasProvider` created. This meant that anything set on `:root`
85
- or outside of the `CanvasProvider` would not be able to cascade down to the components within the
86
- `CanvasProvider`.
87
-
88
- If you provide a `theme` to the `CanvasProvider`, it will create a scoped theme. Note that in v14
89
- and v15, global CSS variables are the recommended way to theme Popups and Modals consistently.
90
-
91
- ## Global vs Scoped Theming
92
-
93
- Canvas Kit v14 and v15 support two theming strategies: **global theming** and **scoped theming**.
94
- Understanding the difference is important to avoid unexpected behavior.
95
-
96
- ### Global Theming
97
-
98
- Global theming applies CSS variables at the `:root` level, making them available throughout your
99
- entire application. This is the **recommended approach** for most use cases.
100
-
101
- ```css
102
- @import '@workday/canvas-tokens-web/css/base/_variables.css';
103
- :root {
104
- // This is showing how you can change the value of a token at the root level of your application.
105
- --cnvs-brand-primary-600: var(--cnvs-base-palette-magenta-600);
106
- }
107
- ```
108
-
109
- ### Scoped Theming
110
-
111
- Scoped theming applies CSS variables to a specific section of your application using the
112
- `CanvasProvider` via the `theme` prop. The theme only affects components within that provider.
113
-
114
- ```tsx
115
- // Using the theme prop for scoped theming. This will set the [brand.primary.**] tokens to shades of purple. This will also ensure that the Popup and Modal components are themed consistently.
116
- <CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
117
- <ScopedSection />
118
- </CanvasProvider>
119
- ```
120
-
121
- > **⚠️ Warning:** Scoped theming creates a cascade barrier that **will break global theming**. Any
122
- > CSS variables defined at `:root` will be overridden by the scoped theme. Only the tokens
123
- > explicitly defined in the `theme` prop will be changed - other tokens will use their default
124
- > values, not your global overrides.
125
-
126
- ### When to Use Scoped Theming
127
-
128
- Only use scoped theming when you intentionally need a different theme for a specific section of your
129
- application, such as:
130
-
131
- - Embedding a Canvas Kit component in a third-party application with a different brand
132
- - Creating a preview panel that shows components with different themes
133
- - Supporting multi-tenant applications where sections have different branding
134
-
135
- For all other cases, use global theming at `:root` to ensure consistent theming throughout your
136
- application.
137
-
138
- ## ✅ Preferred Approach (v14+)
139
-
140
- Canvas Kit v14 and v15 promote using CSS variables for theming, which can be applied in two ways:
141
-
142
- ### Method 1: Global CSS Variables (Recommended)
143
-
144
- Apply theming at the global level by importing CSS variable files and overriding values in your root
145
- CSS:
18
+ Import the Sana variables **last** in your root CSS and set `data-theme="sana-canvas"` on `<html>`.
146
19
 
147
20
  ```css
148
- /* index.css */
21
+ /* index.css — order matters */
149
22
  @import '@workday/canvas-tokens-web/css/base/_variables.css';
150
- @import '@workday/canvas-tokens-web/css/system/_variables.css';
151
23
  @import '@workday/canvas-tokens-web/css/brand/_variables.css';
152
24
  @import '@workday/canvas-tokens-web/css/component/_variables.css';
25
+ @import '@workday/canvas-tokens-web/css/system/_variables.css';
26
+ @import '@workday/canvas-tokens-web/css/sana/_variables.css';
153
27
 
154
28
  :root {
155
- /* Override brand primary colors */
29
+ /* Optional — override only if you have a custom brand color */
156
30
  --cnvs-brand-primary-600: var(--cnvs-base-palette-magenta-600);
157
- --cnvs-brand-primary-200: var(--cnvs-base-palette-magenta-200);
158
- --cnvs-brand-primary-50: var(--cnvs-base-palette-magenta-50);
159
- --cnvs-brand-primary-25: var(--cnvs-base-palette-magenta-25);
160
- --cnvs-brand-primary-700: var(--cnvs-base-palette-magenta-700);
161
- --cnvs-brand-primary-800: var(--cnvs-base-palette-magenta-800);
162
31
  }
163
32
  ```
164
33
 
165
- > **Note:** You should only import the CSS variables _once_ at the root level of your application.
166
- > If your application renders within another environment that imports these and sets them, **do
167
- > not** re import them.
168
-
169
- ### Method 2: Provider-Level CSS Variables
170
-
171
- Use Canvas Kit's `CanvasProvider` and `theme` prop to generate themed class names that can be
172
- applied to specific components or sections:
173
-
174
- ```tsx
175
- import {CanvasProvider} from '@workday/canvas-kit-react/common';
176
-
177
- // This will set the [brand.primary.**] tokens to shades of purple. This will also ensure that the Popup and Modal components are themed consistently.
178
- <CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
179
- <App />
180
- </CanvasProvider>;
34
+ ```html
35
+ <html lang="en" data-theme="sana-canvas"></html>
181
36
  ```
182
37
 
183
- ## CSS Token Structure
184
-
185
- Canvas Kit provides three layers of CSS variables.
38
+ ## Classic Canvas (without Sana theme)
186
39
 
187
- ### Base Tokens (`base/_variables.css`)
40
+ If you are not opting into the Sana Canvas theme, omit `data-theme` from `<html>`. The `:root`
41
+ tokens apply as-is — no `theme` prop on `CanvasProvider` is required.
188
42
 
189
- Base tokens define foundation palette and design values.
190
-
191
- ```css
192
- --cnvs-base-palette-blue-600: oklch(0.5198 0.1782 256.11 / 1);
193
- --cnvs-base-palette-magenta-600: oklch(0.534 0.183 344.19 / 1);
194
- --cnvs-base-font-size-100: 1rem;
195
- --cnvs-base-space-x4: calc(var(--cnvs-base-unit) * 4);
196
- ```
197
-
198
- ### Brand Tokens (`brand/_variables.css`)
199
-
200
- Brand tokens define semantic color assignments.
201
-
202
- ```css
203
- --cnvs-brand-primary-600: var(--cnvs-base-palette-blue-600);
204
- --cnvs-brand-primary-200: var(--cnvs-base-palette-blue-200);
205
- --cnvs-brand-primary-50: var(--cnvs-base-palette-blue-50);
206
- --cnvs-brand-primary-25: var(--cnvs-base-palette-blue-25);
207
- --cnvs-brand-primary-700: var(--cnvs-base-palette-blue-700);
208
- --cnvs-brand-primary-800: var(--cnvs-base-palette-blue-800);
209
- ```
210
-
211
- ### System Tokens (`system/_variables.css`)
212
-
213
- System tokens define component-specific values.
214
-
215
- ```css
216
- --cnvs-sys-color-bg-default: var(--cnvs-base-palette-blue-600);
217
- --cnvs-sys-shape-sm: var(--cnvs-base-size-50);
218
- ```
219
-
220
- ## Practical Examples
221
-
222
- ### Complete Brand Theming
223
-
224
- ```css
225
- /* themes/magenta-theme.css */
226
- @import '@workday/canvas-tokens-web/css/base/_variables.css';
227
- @import '@workday/canvas-tokens-web/css/system/_variables.css';
228
- @import '@workday/canvas-tokens-web/css/brand/_variables.css';
229
-
230
- :root {
231
- /* Primary brand colors */
232
- --cnvs-brand-primary-600: var(--cnvs-base-palette-magenta-600);
233
- --cnvs-brand-primary-200: var(--cnvs-base-palette-magenta-200);
234
- --cnvs-brand-primary-50: var(--cnvs-base-palette-magenta-50);
235
- --cnvs-brand-primary-25: var(--cnvs-base-palette-magenta-25);
236
- --cnvs-brand-primary-700: var(--cnvs-base-palette-magenta-700);
237
- --cnvs-brand-primary-800: var(--cnvs-base-palette-magenta-800);
238
- }
43
+ ```html
44
+ <html lang="en"></html>
239
45
  ```
240
46
 
241
- ### Scoped Theming
242
-
243
- <ExampleCodeBlock code={Theming} />
244
-
245
- ### RTL Support
246
-
247
- Canvas Kit supports RTL out of the box. Our components are styled to use
248
- [CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
249
- If you want to add additional styles based on RTL, you can also use the `:dir`
250
- [pseudo selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir).
251
-
252
- #### Setting RTL Direction
253
-
254
- Use the native HTML `dir` attribute to set the text direction. The `CanvasProvider` accepts a `dir`
255
- prop which sets this attribute on its wrapper element:
256
-
257
47
  ```tsx
258
48
  import {CanvasProvider} from '@workday/canvas-kit-react/common';
259
49
 
260
- // Set RTL direction
261
- <CanvasProvider dir="rtl">
50
+ <CanvasProvider>
262
51
  <App />
263
- </CanvasProvider>;
264
- ```
265
-
266
- You can also set it on any HTML element:
267
-
268
- ```tsx
269
- <div dir="rtl">
270
- <MyComponent />
271
- </div>
272
- ```
273
-
274
- > **Note:** The `dir` attribute is the standard HTML way to set text direction. It's preferred over
275
- > the deprecated `theme.canvas.direction` approach because it works natively with CSS logical
276
- > properties and the `:dir()` pseudo-class.
277
-
278
- #### Using CSS Logical Properties
279
-
280
- CSS logical properties automatically adapt to the text direction. Use these instead of physical
281
- properties:
282
-
283
- ```css
284
- /* Physical properties (don't adapt to RTL) */
285
- .my-component {
286
- margin-left: 1rem;
287
- padding-right: 1rem;
288
- border-left: 1px solid;
289
- }
290
-
291
- /* Logical properties (adapt to RTL automatically) */
292
- .my-component {
293
- margin-inline-start: 1rem;
294
- padding-inline-end: 1rem;
295
- border-inline-start: 1px solid;
296
- }
297
- ```
298
-
299
- #### Conditional RTL Styles with `:dir()`
300
-
301
- For styles that need to change based on direction (like rotating icons), use the `:dir()`
302
- pseudo-class:
303
-
304
- ```tsx
305
- import {createStyles} from '@workday/canvas-kit-styling';
306
-
307
- const rtlButtonStyles = createStyles({
308
- ':dir(rtl)': {
309
- svg: {
310
- transform: 'rotate(180deg)',
311
- },
312
- },
313
- });
52
+ </CanvasProvider>
314
53
  ```
315
54
 
316
- <ExampleCodeBlock code={RTL} />
317
-
318
- ### Resetting to Default Brand Theme
55
+ The sana stylesheet only defines `[data-theme="sana-canvas"]` overrides. Without that attribute,
56
+ those rules do not apply.
319
57
 
320
- If you need to reset the theme in parts of your application, there's a few ways to do this. We
321
- export a `defaultBranding` class that can be applied to the `CanvasProvider` which can wrap parts of
322
- your application.
58
+ If your application **has** opted into Sana globally but one subsection needs classic Canvas branding,
59
+ use `defaultBranding` on a scoped `CanvasProvider`:
323
60
 
324
61
  ```tsx
325
62
  import {CanvasProvider, defaultBranding} from '@workday/canvas-kit-react/common';
326
63
 
327
64
  <CanvasProvider className={defaultBranding}>
328
- <SomeSubComponent />
329
- </CanvasProvider>;
65
+ <ClassicCanvasSection />
66
+ </CanvasProvider>
330
67
  ```
331
68
 
332
- > **Note:** Doing the following **will create a cascade barrier**. Only use this method if you
333
- > intentionally want to override the default theme.
69
+ ## Scoped Theming
334
70
 
335
- ## Migration Guide
71
+ Most application teams should use the Sana Canvas theme globally and not pass a `theme` prop to
72
+ `CanvasProvider`. Use scoped theming only when a section of your app needs a different brand — for
73
+ example, embedding Canvas in a third-party application, multi-tenant branding, or popup parity.
336
74
 
337
- ### Step 1: Identify Current Theme Usage
75
+ The `theme` prop accepts a numerical `brand` object. Each key maps 1:1 to a `--cnvs-brand-*` CSS
76
+ variable.
338
77
 
339
- Find all instances of `CanvasProvider` with theme props in your application.
78
+ | You set | Components affected |
79
+ | ------- | ------------------- |
80
+ | `brand.primary['600']` alone | `PrimaryButton`, selected `Menu.Item` (text + background) |
81
+ | `brand.primary['500']` | Focus rings, border primary (independent of `600`) |
82
+ | `brand.action.*` | `PrimaryButton` (read before `brand.primary`) |
83
+ | `brand.critical.*` | `TextInput` error, critical accents |
84
+ | `brand.caution.*` | `TextInput` caution, caution focus |
85
+ | `brand.positive.*` | `Checkbox`, `Radio` checked states |
86
+ | `brand.neutral.*` | Neutral brand text/surfaces |
87
+ | `selected.fg` / `selected.surface` | Selected list/menu states directly |
340
88
 
341
- ```tsx
342
- // Find these patterns:
343
- <CanvasProvider theme={{canvas: {palette: {...}}}}>
344
- ```
345
-
346
- ### Step 2: Extract Theme Values
347
-
348
- Convert JavaScript theme objects to CSS variable overrides.
89
+ **Focus does not follow primary.** Setting only `brand.primary['600']` leaves focus rings at the
90
+ default blue unless you also set `brand.primary['500']`.
349
91
 
350
92
  ```tsx
351
- // Old approach:
352
- const theme = {
353
- canvas: {
354
- palette: {
355
- primary: {
356
- main: colors.greenApple400,
357
- dark: colors.greenApple500,
358
- }
359
- }
360
- }
361
- };
362
-
363
- // New approach - CSS variables:
364
- :root {
365
- --cnvs-brand-primary-base: var(--cnvs-base-palette-green-400);
366
- --cnvs-brand-primary-dark: var(--cnvs-base-palette-green-500);
367
- }
368
- ```
369
-
370
- ### Step 3: App Level Theming Usage
371
-
372
- Replace theme-based `CanvasProvider` usage with CSS class-based theming.
93
+ import {CanvasProvider} from '@workday/canvas-kit-react/common';
94
+ import {base} from '@workday/canvas-tokens-web';
373
95
 
374
- ```tsx
375
- <CanvasProvider theme={{canvas: {palette: {primary: {main: 'green'}}}}}>
376
- <App />
96
+ <CanvasProvider theme={{brand: {primary: {'600': base.magenta600}}}}>
97
+ <ScopedSection />
377
98
  </CanvasProvider>
378
99
  ```
379
100
 
380
- ## Best Practices
381
-
382
- ### 1. Use Semantic Token Names
101
+ <ExampleCodeBlock code={ThemingBrandScope} />
383
102
 
384
- Use brand tokens instead of base tokens for better maintainability.
103
+ Popups (including menus, selects, modals, and toasts) portal to `document.body` — outside the
104
+ parent component's DOM hierarchy. How theming reaches them:
385
105
 
386
- ```css
387
- /* Good - semantic meaning */
388
- --cnvs-brand-primary-600: var(--cnvs-base-palette-blue-600);
389
-
390
- /* ❌ Avoid - direct base token usage */
391
- --cnvs-base-palette-blue-600: blue;
392
- ```
393
-
394
- ### 2. Test Accessibility
395
-
396
- Ensure color combinations meet accessibility standards.
397
-
398
- For a full list of color contrast pairs, view our
399
- [Color Contrast](https://canvas.workday.com/guidelines/color/color-contrast) documentation.
400
-
401
- ### 3. Avoid Component Level Theming
402
-
403
- Theming is meant to be done at the app level or root level of the application. Avoid theming at the
404
- component level.
106
+ **Preferred — you control the document root:** set `data-theme="sana-canvas"` on the `<html>`
107
+ element. Popups inherit Sana CSS variables automatically; no `theme` prop needed:
405
108
 
406
109
  ```tsx
407
- /* ✅ Good - App level theming */
408
- import {CanvasProvider} from '@workday/canvas-kit-react/common';
409
-
410
- import {base, brand} from '@workday/canvas-tokens-web';
411
-
412
-
413
- <CanvasProvider theme={{canvas: {palette: {primary: {main: base.magenta600}}}}}>
414
- <App/>
415
- </CanvasProvider>
416
-
417
- /* ❌ Avoid - wrapping components to theme */
418
110
  import {CanvasProvider} from '@workday/canvas-kit-react/common';
419
- import {PrimaryButton} from '@workday/canvas-kit-react/button';
420
111
 
421
- const myCustomTheme = createStyles({
422
- [brand.primary.base]: base.magenta600
423
- })
424
-
425
- <CanvasProvider className={myCustomTheme}>
426
- <PrimaryButton>Click Me</PrimaryButton>
112
+ // <html data-theme="sana-canvas">
113
+ <CanvasProvider>
114
+ <App />
427
115
  </CanvasProvider>
428
-
429
- ```
430
-
431
- ## Performance Benefits
432
-
433
- The CSS variable approach provides several performance improvements:
434
-
435
- - **Reduced Bundle Size**: No JavaScript theme object processing
436
- - **Better Caching**: CSS variables can be cached by the browser
437
- - **Faster Rendering**: Native CSS cascade instead of JavaScript calculations
438
- - **Runtime Efficiency**: No theme context propagation overhead
439
-
440
- ## Troubleshooting
441
-
442
- ### Theme Not Applied
443
-
444
- Ensure CSS variable files are imported in the correct order.
445
-
446
- > **Note:** You should only import the CSS variables _once_ at the root level of your application.
447
- > If your application renders within another environment that imports these and sets them, **do
448
- > not** re import them.
449
-
450
- ```css
451
- /* Correct order */
452
- @import '@workday/canvas-tokens-web/css/base/_variables.css';
453
- @import '@workday/canvas-tokens-web/css/system/_variables.css';
454
- @import '@workday/canvas-tokens-web/css/brand/_variables.css';
455
- @import '@workday/canvas-tokens-web/css/component/_variables.css';
456
-
457
- /* Your overrides after imports */
458
- :root {
459
- --cnvs-brand-primary-base: var(--cnvs-base-palette-magenta-600);
460
- }
461
- ```
462
-
463
- ### Inconsistent Theming
464
-
465
- Check for CSS specificity issues.
466
-
467
- ```css
468
- /* Ensure your overrides have sufficient specificity */
469
- :root {
470
- --cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600) !important;
471
- }
472
-
473
- /* Or use more specific selectors */
474
- .my-app {
475
- --cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600);
476
- }
477
116
  ```
478
117
 
479
- ### Missing Token Values
480
-
481
- Verify all required CSS token files are imported and token names are correct.
118
+ **Scoped / no document-root control:** if you cannot set `data-theme` on `<html>` (embedded apps,
119
+ microfrontends, third-party shells), a nested `data-theme` alone does **not** reach portaled
120
+ popups. Pass both `data-theme="sana-canvas"` (for in-tree UI) and `sanaCanvasProviderTheme` (so
121
+ Canvas Kit forwards Sana brand variables onto the popup stack container):
482
122
 
483
123
  ```tsx
484
- import {base, brand, system} from '@workday/canvas-tokens-web';
124
+ import {CanvasProvider, sanaCanvasProviderTheme} from '@workday/canvas-kit-react/common';
485
125
 
486
- // Check token availability in development
487
- console.log(brand.primary.base); // Should output CSS variable name
126
+ <CanvasProvider theme={sanaCanvasProviderTheme} data-theme="sana-canvas">
127
+ <App />
128
+ </CanvasProvider>
488
129
  ```
489
130
 
490
- ## Conclusion
131
+ `sanaCanvasProviderTheme` is also useful in tests without global Sana CSS or with custom popup
132
+ hosts outside the normal document flow.
133
+
134
+ <ExampleCodeBlock code={SimplifiedSetup} />
491
135
 
492
- The migration to CSS variables in Canvas Kit v14 provides a more performant, flexible, and
493
- maintainable theming solution. By following this guide and best practices, you can successfully
494
- migrate your applications and take advantage of the improved theming capabilities.
136
+ See the
137
+ [Sana Canvas](?path=/story/features-theming--sana-canvas) Storybook story for a side-by-side
138
+ comparison of global and scoped branding.
495
139
 
496
- For additional support and examples, refer to the Canvas Kit Storybook documentation and the
497
- `@workday/canvas-tokens` [repository](https://github.com/Workday/canvas-tokens).
140
+ View token documentation
141
+ [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).
@@ -0,0 +1,35 @@
1
+ import React from 'react';
2
+
3
+ import {PrimaryButton, SecondaryButton} from '@workday/canvas-kit-react/button';
4
+ import {CanvasProvider, sanaCanvasProviderTheme} from '@workday/canvas-kit-react/common';
5
+ import {Menu} from '@workday/canvas-kit-react/menu';
6
+ import {Popup, useCloseOnOutsideClick, usePopupModel} from '@workday/canvas-kit-react/popup';
7
+
8
+ /**
9
+ * Scoped Sana setup for popup parity: `data-theme` themes the in-tree UI, and
10
+ * `sanaCanvasProviderTheme` forwards brand CSS variables onto portaled popups
11
+ * (menus, selects, modals) that render under `document.body`.
12
+ */
13
+ export default () => {
14
+ const myModel = usePopupModel();
15
+ useCloseOnOutsideClick(myModel);
16
+ return (
17
+ <CanvasProvider theme={sanaCanvasProviderTheme} data-theme="sana-canvas">
18
+ <Popup model={myModel}>
19
+ <Popup.Target as={SecondaryButton}>Open Menu</Popup.Target>
20
+ <Popup.Popper>
21
+ <Popup.Card>
22
+ <Popup.Body>
23
+ <Menu>
24
+ <Menu.Item>Option 1</Menu.Item>
25
+ <Menu.Item>Option 2</Menu.Item>
26
+ <Menu.Item>Option 3</Menu.Item>
27
+ </Menu>
28
+ <PrimaryButton>Hello World</PrimaryButton>
29
+ </Popup.Body>
30
+ </Popup.Card>
31
+ </Popup.Popper>
32
+ </Popup>
33
+ </CanvasProvider>
34
+ );
35
+ };
@@ -0,0 +1,29 @@
1
+ import {PrimaryButton} from '@workday/canvas-kit-react/button';
2
+ import {Card} from '@workday/canvas-kit-react/card';
3
+ import {CanvasProvider} from '@workday/canvas-kit-react/common';
4
+ import {Menu} from '@workday/canvas-kit-react/menu';
5
+ import {base} from '@workday/canvas-tokens-web';
6
+
7
+ export default () => (
8
+ <CanvasProvider theme={{brand: {primary: {'600': base.magenta600}}}}>
9
+ <Card>
10
+ <Card.Heading>Brand scope</Card.Heading>
11
+ <Card.Body>
12
+ <p>
13
+ Only primary is set — buttons and selected menu items update. Focus rings stay default.
14
+ </p>
15
+ <PrimaryButton>Primary</PrimaryButton>
16
+ <Menu initialSelectedIds={['selected']}>
17
+ <Menu.Card>
18
+ <Menu.List>
19
+ <Menu.Item id="other">Other item</Menu.Item>
20
+ <Menu.Item id="selected" aria-selected="true">
21
+ Selected item
22
+ </Menu.Item>
23
+ </Menu.List>
24
+ </Menu.Card>
25
+ </Menu>
26
+ </Card.Body>
27
+ </Card>
28
+ </CanvasProvider>
29
+ );
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@workday/canvas-kit-docs",
3
- "version": "16.0.0-alpha.0499-next.0",
3
+ "version": "16.0.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",
@@ -47,10 +47,10 @@
47
47
  "@stackblitz/sdk": "^1.11.0",
48
48
  "@storybook/csf": "0.0.1",
49
49
  "@workday/canvas-expressive-icons-web": "1.0.2",
50
- "@workday/canvas-kit-labs-react": "^16.0.0-alpha.0499-next.0",
51
- "@workday/canvas-kit-preview-react": "^16.0.0-alpha.0499-next.0",
52
- "@workday/canvas-kit-react": "^16.0.0-alpha.0499-next.0",
53
- "@workday/canvas-kit-styling": "^16.0.0-alpha.0499-next.0",
50
+ "@workday/canvas-kit-labs-react": "^16.0.0",
51
+ "@workday/canvas-kit-preview-react": "^16.0.0",
52
+ "@workday/canvas-kit-react": "^16.0.0",
53
+ "@workday/canvas-kit-styling": "^16.0.0",
54
54
  "@workday/canvas-system-icons-web": "^5.0.3",
55
55
  "@workday/canvas-tokens-web": "^4.4.0",
56
56
  "markdown-to-jsx": "^7.2.0",
@@ -63,5 +63,5 @@
63
63
  "mkdirp": "^1.0.3",
64
64
  "typescript": "5.0"
65
65
  },
66
- "gitHead": "cd5cbb846495120a4bffea4ee17b3b0a482e68c0"
66
+ "gitHead": "3f3f7e9a3251cf61ffb40f93dba3dd50d9f3e3cf"
67
67
  }
@@ -1,2 +0,0 @@
1
- export declare const CommentBoxWithCharLimit: () => import("react/jsx-runtime").JSX.Element;
2
- //# sourceMappingURL=CommentBoxWithCharLimit.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"CommentBoxWithCharLimit.d.ts","sourceRoot":"","sources":["../../../../../../mdx/accessibility/examples/AriaLiveRegions/CommentBoxWithCharLimit.tsx"],"names":[],"mappings":"AASA,eAAO,MAAM,uBAAuB,+CA2CnC,CAAC"}