@workday/canvas-kit-docs 14.0.0-alpha.1251-next.0 → 14.0.0-alpha.1253-next.0

package/dist/mdx/react/common/mdx/Theming.mdx

@@ -0,0 +1,417 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+import RTL from './examples/RTL';
+import Theming from './examples/Theming';
+
+
+# Canvas Kit Theming Guide
+
+## Overview
+
+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.
+
+## Migration from v10 Theme Prop to v14 CSS Variables
+
+### The Evolution
+
+**Canvas Kit v10** introduced CSS tokens through the `@workday/canvas-tokens-web` package, providing a foundation for consistent design system values.
+
+**Canvas Kit v14** Removes the cascade barrier created by the `CanvasProvider`, allowing CSS variables to work as intended.
+
+## Old Approach (v10-v13)
+
+The old theming approach used JavaScript objects passed to the `CanvasProvider` theme prop:
+
+```tsx
+import {CanvasProvider} from "@workday/canvas-kit-react/common"
+import {base} from "@workday/canvas-tokens-web"
+
+<CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
+   <App/>
+</CanvasProvider>
+```
+
+This would use `chroma.js` to generate a palette based on the `main` color provided.
+
+**Why we're moving away from this approach:**
+- Performance overhead from JavaScript theme object processing
+- Limited flexibility for complex theming scenarios
+- Inconsistent cascade behavior
+
+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.
+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.
+
+## What is a Cascade Barrier?
+
+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:
+
+```css
+:root {
+	--cnbvs-brand-primary-base: blue;
+}
+
+// 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.
+.my-app {
+	--cnvs-brand-primary-base: red;
+}
+```
+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`.
+
+## ✅ Preferred Approach (v14+)
+
+Canvas Kit v14 promotes using CSS variables for theming, which can be applied in two ways:
+
+### Method 1: Global CSS Variables (Recommended)
+
+Apply theming at the global level by importing CSS variable files and overriding values in your root CSS:
+
+```css
+/* index.css */
+@import '@workday/canvas-tokens-web/css/base/_variables.css';
+@import '@workday/canvas-tokens-web/css/system/_variables.css';
+@import '@workday/canvas-tokens-web/css/brand/_variables.css';
+
+:root {
+  /* Override brand primary colors */
+  --cnvs-brand-primary-base: var(--cnvs-base-palette-magenta-600);
+  --cnvs-brand-primary-light: var(--cnvs-base-palette-magenta-200);
+  --cnvs-brand-primary-lighter: var(--cnvs-base-palette-magenta-50);
+  --cnvs-brand-primary-lightest: var(--cnvs-base-palette-magenta-25);
+  --cnvs-brand-primary-dark: var(--cnvs-base-palette-magenta-700);
+  --cnvs-brand-primary-darkest: var(--cnvs-base-palette-magenta-800);
+  --cnvs-brand-primary-accent: var(--cnvs-base-palette-neutral-0);
+}
+```
+
+> **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.
+
+### Method 2: Provider-Level CSS Variables
+
+Use Canvas Kit's `createStyles` utility to generate themed class names that can be applied to specific components or sections:
+
+> **Note:** Doing the following **will create a cascade barrier**. Only use this method if you intentionally want to override the default theme.
+
+```tsx
+import {createStyles}from "@workday/canvas-kit-styling"
+import {brand, base} from "@workday/canvas-tokens-web"
+import {CanvasProvider} from "@workday/canvas-kit-react/common"
+
+// You can import the CSS variables in a ts file or an index.css file. You do not need to do both.
+import '@workday/canvas-tokens-web/css/base/_variables.css';
+import '@workday/canvas-tokens-web/css/system/_variables.css';
+import '@workday/canvas-tokens-web/css/brand/_variables.css';
+
+// Generate a class name that defines CSS variables
+const themedBrand = createStyles({
+  [brand.primary.accent]: base.neutral0,
+  [brand.primary.darkest]: base.blue800,
+  [brand.primary.dark]: base.blue700,
+  [brand.primary.base]: base.blue600,
+  [brand.primary.light]: base.blue200,
+  [brand.primary.lighter]: base.blue50,
+  [brand.primary.lightest]: base.blue25,
+})
+
+<CanvasProvider className={themedBrand}>
+  <App/>
+</CanvasProvider>
+```
+
+## CSS Token Structure
+
+Canvas Kit provides three layers of CSS variables.
+
+### Base Tokens (`base/_variables.css`)
+Base tokens define foundation palette and design values.
+```css
+--cnvs-base-palette-blue-600: oklch(0.5198 0.1782 256.11 / 1);
+--cnvs-base-palette-magenta-600: oklch(0.534 0.183 344.19 / 1);
+--cnvs-base-font-size-100: 1rem;
+--cnvs-base-space-x4: calc(var(--cnvs-base-unit) * 4);
+```
+
+### Brand Tokens (`brand/_variables.css`)
+Brand tokens define semantic color assignments.
+```css
+--cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600);
+--cnvs-brand-primary-accent: var(--cnvs-base-palette-neutral-0);
+--cnvs-brand-error-base: var(--cnvs-base-palette-red-600);
+--cnvs-brand-success-base: var(--cnvs-base-palette-green-600);
+```
+
+### System Tokens (`system/_variables.css`)
+System tokens define component-specific values.
+```css
+--cnvs-sys-color-bg-primary-default: var(--cnvs-base-palette-blue-600);
+--cnvs-sys-color-text-primary-default: var(--cnvs-base-palette-blue-600);
+--cnvs-sys-space-x4: calc(var(--cnvs-base-unit) * 4);
+```
+
+## Practical Examples
+
+### Complete Brand Theming
+
+```css
+/* themes/magenta-theme.css */
+@import '@workday/canvas-tokens-web/css/base/_variables.css';
+@import '@workday/canvas-tokens-web/css/system/_variables.css';
+@import '@workday/canvas-tokens-web/css/brand/_variables.css';
+
+:root {
+  /* Primary brand colors */
+  --cnvs-brand-primary-base: var(--cnvs-base-palette-magenta-600);
+  --cnvs-brand-primary-light: var(--cnvs-base-palette-magenta-200);
+  --cnvs-brand-primary-lighter: var(--cnvs-base-palette-magenta-50);
+  --cnvs-brand-primary-lightest: var(--cnvs-base-palette-magenta-25);
+  --cnvs-brand-primary-dark: var(--cnvs-base-palette-magenta-700);
+  --cnvs-brand-primary-darkest: var(--cnvs-base-palette-magenta-800);
+  --cnvs-brand-primary-accent: var(--cnvs-base-palette-neutral-0);
+}
+```
+
+### App-Specific Theming
+
+```tsx
+import {createStyles} from "@workday/canvas-kit-styling";
+import {brand, base} from "@workday/canvas-tokens-web";
+import {PrimaryButton} from "@workday/canvas-kit-react/button";
+import {CanvasProvider} from "@workday/canvas-kit-react/common";
+
+const greenTheme = createStyles({
+  [brand.primary.base]: base.green600,
+  [brand.primary.dark]: base.green700,
+  [brand.primary.darkest]: base.green800,
+  [brand.primary.light]: base.green200,
+  [brand.primary.lighter]: base.green50,
+  [brand.primary.lightest]: base.green25,
+  [brand.primary.accent]: base.neutral0,
+});
+
+<CanvasProvider className={greenTheme}>
+    <PrimaryButton>Click me</PrimaryButton>
+  </CanvasProvider>
+);
+```
+
+<ExampleCodeBlock code={Theming} />
+
+### Dark Mode Implementation
+
+```css
+/* Dark mode theming */
+[data-theme="dark"] {
+  --cnvs-sys-color-bg-default: var(--cnvs-base-palette-neutral-950);
+  --cnvs-sys-color-text-default: var(--cnvs-base-palette-neutral-50);
+  --cnvs-sys-color-border-container: var(--cnvs-base-palette-slate-700);
+  --cnvs-sys-color-bg-alt-default: var(--cnvs-base-palette-slate-800);
+}
+```
+
+### RTL Support
+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,
+you can also use the `:dir` [pseudo selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir).
+
+<ExampleCodeBlock code={RTL} />
+
+### Resetting to Default Brand Theme
+
+If you need to reset the theme in parts of your application, there's a few ways to do this.
+We export a `defaultBranding` class that can be applied to the `CanvasProvider` which can wrap parts of your application.
+
+```tsx
+import {CanvasProvider, defaultBranding} from "@workday/canvas-kit-react/common"
+
+<CanvasProvider className={defaultBranding}>
+	<SomeSubComponent/>
+</CanvasProvider>
+```
+
+> **Note:** Doing the following **will create a cascade barrier**. Only use this method if you intentionally want to override the default theme.
+
+## Migration Guide
+
+### Step 1: Identify Current Theme Usage
+
+Find all instances of `CanvasProvider` with theme props in your application.
+
+```tsx
+// Find these patterns:
+<CanvasProvider theme={{canvas: {palette: {...}}}}>
+```
+
+### Step 2: Extract Theme Values
+
+Convert JavaScript theme objects to CSS variable overrides.
+
+```tsx
+// Old approach:
+const theme = {
+  canvas: {
+    palette: {
+      primary: {
+        main: colors.greenApple400,
+        dark: colors.greenApple500,
+      }
+    }
+  }
+};
+
+// New approach - CSS variables:
+:root {
+  --cnvs-brand-primary-base: var(--cnvs-base-palette-green-400);
+  --cnvs-brand-primary-dark: var(--cnvs-base-palette-green-500);
+}
+```
+
+### Step 3: App Level Theming Usage
+
+Replace theme-based `CanvasProvider` usage with CSS class-based theming.
+
+```tsx
+// Before:
+<CanvasProvider theme={customTheme}>
+  <App />
+</CanvasProvider>
+
+// After:
+<CanvasProvider className={customThemeClass}>
+  <App />
+</CanvasProvider>
+```
+
+> **Note:** Using a class means you will need to define each property of the palette for full control over theming.
+
+### Step 4: Test Component Rendering
+
+Verify that Canvas Kit components (like `PrimaryButton`) correctly use the new CSS variables.
+
+```tsx
+import {PrimaryButton} from "@workday/canvas-kit-react/button";
+
+// This should automatically use your CSS variable overrides
+<PrimaryButton>Themed Button</PrimaryButton>
+```
+
+## Best Practices
+
+### 1. Use Semantic Token Names
+Use brand tokens instead of base tokens for better maintainability.
+
+```css
+/* ✅ Good - semantic meaning */
+--cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600);
+
+/* ❌ Avoid - direct base token usage */
+--cnvs-base-palette-blue-600: blue;
+```
+
+
+### 2. Test Accessibility
+Ensure color combinations meet accessibility standards.
+
+```css
+/* Verify contrast ratios for text/background combinations */
+:root {
+  --cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600);
+  --cnvs-brand-primary-accent: var(--cnvs-base-palette-neutral-0); /* White text */
+}
+```
+
+### 3. Avoid Component Level Theming
+
+Theming is meant to be done at the app level or root level of the application. Avoid theming at the component level.
+
+```tsx
+/* ✅ Good - App level theming */
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {base, brand} from '@workday/canvas-tokens-web';
+
+const myCustomTheme = createStyles({
+  [brand.primary.base]: base.magenta600
+})
+
+
+<CanvasProvider className={myCustomTheme}>
+  <App/>
+</CanvasProvider>
+
+/* ❌ Avoid - wrapping components to theme */
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+const myCustomTheme = createStyles({
+  [brand.primary.base]: base.magenta600
+})
+
+<CanvasProvider className={myCustomTheme}>
+  <PrimaryButton>Click Me</PrimaryButton>
+</CanvasProvider>
+
+```
+
+## Component Compatibility
+
+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.
+
+### Supported Components
+- ✅ All Button variants (`PrimaryButton`, `SecondaryButton`, etc.)
+- ✅ Form components (`TextInput`, `FormField`, etc.)
+- ✅ Layout components (`Card`, `Modal`, etc.)
+- ✅ Navigation components (`Tabs`, `SidePanel`, etc.)
+
+## Performance Benefits
+
+The CSS variable approach provides several performance improvements:
+
+- **Reduced Bundle Size**: No JavaScript theme object processing
+- **Better Caching**: CSS variables can be cached by the browser
+- **Faster Rendering**: Native CSS cascade instead of JavaScript calculations
+- **Runtime Efficiency**: No theme context propagation overhead
+
+## Troubleshooting
+
+### Theme Not Applied
+Ensure CSS variable files are imported in the correct order.
+
+```css
+/* Correct order */
+@import '@workday/canvas-tokens-web/css/base/_variables.css';
+@import '@workday/canvas-tokens-web/css/system/_variables.css';
+@import '@workday/canvas-tokens-web/css/brand/_variables.css';
+
+/* Your overrides after imports */
+:root {
+  --cnvs-brand-primary-base: var(--cnvs-base-palette-magenta-600);
+}
+```
+
+### Inconsistent Theming
+Check for CSS specificity issues.
+
+```css
+/* Ensure your overrides have sufficient specificity */
+:root {
+  --cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600) !important;
+}
+
+/* Or use more specific selectors */
+.my-app {
+  --cnvs-brand-primary-base: var(--cnvs-base-palette-blue-600);
+}
+```
+
+### Missing Token Values
+Verify all required CSS token files are imported and token names are correct.
+
+```tsx
+import {brand, base, system} from "@workday/canvas-tokens-web";
+
+// Check token availability in development
+console.log(brand.primary.base); // Should output CSS variable name
+```
+
+## Conclusion
+
+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.
+
+For additional support and examples, refer to the Canvas Kit Storybook documentation and the `@workday/canvas-tokens` [repository](https://github.com/Workday/canvas-tokens).

package/dist/mdx/react/common/mdx/examples/RTL.tsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import {createStyles} from '@workday/canvas-kit-styling';
+
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {Card} from '@workday/canvas-kit-react/card';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+import {FormField} from '@workday/canvas-kit-react/form-field';
+import {TextInput} from '@workday/canvas-kit-react/text-input';
+import {arrowRightSmallIcon} from '@workday/canvas-system-icons-web';
+import {system} from '@workday/canvas-tokens-web';
+
+const rtlStyles = createStyles({
+  paddingInlineStart: system.space.x16,
+});
+
+const rtlButtonStyles = createStyles({
+  ':dir(rtl)': {
+    svg: {
+      transform: 'rotate(180deg)',
+    },
+  },
+});
+
+const App = () => {
+  const [value, setValue] = React.useState('');
+
+  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+    setValue(event.target.value);
+  };
+  return (
+    <Card>
+      <Card.Heading>RTL Support</Card.Heading>
+      <Card.Body cs={rtlStyles}>
+        <FormField>
+          <FormField.Label>Email</FormField.Label>
+          <FormField.Field>
+            <FormField.Input as={TextInput} onChange={handleChange} value={value} />
+          </FormField.Field>
+        </FormField>
+        <PrimaryButton cs={rtlButtonStyles} iconPosition="end" icon={arrowRightSmallIcon}>
+          RTL
+        </PrimaryButton>
+      </Card.Body>
+    </Card>
+  );
+};
+
+export default () => {
+  return (
+    <CanvasProvider dir="rtl">
+      <App />
+    </CanvasProvider>
+  );
+};

package/dist/mdx/react/common/mdx/examples/Theming.tsx

@@ -0,0 +1,34 @@
+import {createStyles} from '@workday/canvas-kit-styling';
+import {brand, base, system} from '@workday/canvas-tokens-web';
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {Card} from '@workday/canvas-kit-react/card';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+const customTheme = createStyles({
+  [brand.primary.base]: base.green600,
+  [brand.primary.dark]: base.green700,
+  [brand.primary.darkest]: base.green800,
+  [brand.common.focusOutline]: base.green600,
+  [system.color.fg.strong]: base.indigo900,
+  [system.color.border.container]: base.indigo300,
+});
+
+const App = () => {
+  return (
+    <Card>
+      <Card.Heading>Theming</Card.Heading>
+      <Card.Body>
+        <PrimaryButton>Theming</PrimaryButton>
+        <input />
+      </Card.Body>
+    </Card>
+  );
+};
+
+export default () => {
+  return (
+    <CanvasProvider className={customTheme}>
+      <App />
+    </CanvasProvider>
+  );
+};

package/dist/mdx/welcome.mdx

@@ -9,8 +9,7 @@ import { version } from '../../../lerna.json';
 
 ### Canvas Provider
 
-The `<CanvasProvider>` is required for proper branding support. Furthermore, if you use Emotion for
-styling your components, the `<CanvasProvider>` ensures your styles will merge as expected. Note:
+If you use Emotion for styling your components, the `<CanvasProvider>` ensures your styles will merge as expected. Note:
 Custom use of `<CacheProvider>` provided by Emotion is not supported. `@workday/canvas-kit-styling`
 owns the creating of the cache reference. This ensures both static styling and Emotion’s dynamic
 styling solutions work together. In most cases you'll want to wrap your application at the root
@@ -20,9 +19,6 @@ level in `<CanvasProvider>`.
 import * as React from 'react';
 import {
   CanvasProvider,
-  ContentDirection,
-  PartialEmotionCanvasTheme,
-  useTheme,
 } from '@workday/canvas-kit-react/common';
 // Ensure CSS variables are defined. You Can also do this at the root index.css
 import '@workday/canvas-tokens-web/css/base/_variables.css';
@@ -30,15 +26,8 @@ import '@workday/canvas-tokens-web/css/brand/_variables.css';
 import '@workday/canvas-tokens-web/css/system/_variables.css';
 
 export const App = () => {
-  // useTheme is filling in the Canvas theme object if any keys are missing
-  const canvasTheme: PartialEmotionCanvasTheme = useTheme({
-    canvas: {
-      // Switch to `ContentDirection.RTL` to change direction
-      direction: ContentDirection.LTR,
-    },
-  });
   return (
-    <CanvasProvider theme={canvasTheme}>
+    <CanvasProvider>
         <main>
           <p>Get Started With Canvas Kit</p>
         </main>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "14.0.0-alpha.1251-next.0",
+  "version": "14.0.0-alpha.1253-next.0",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -45,10 +45,10 @@
     "@emotion/styled": "^11.6.0",
     "@stackblitz/sdk": "^1.11.0",
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1251-next.0",
-    "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1251-next.0",
-    "@workday/canvas-kit-react": "^14.0.0-alpha.1251-next.0",
-    "@workday/canvas-kit-styling": "^14.0.0-alpha.1251-next.0",
+    "@workday/canvas-kit-labs-react": "^14.0.0-alpha.1253-next.0",
+    "@workday/canvas-kit-preview-react": "^14.0.0-alpha.1253-next.0",
+    "@workday/canvas-kit-react": "^14.0.0-alpha.1253-next.0",
+    "@workday/canvas-kit-styling": "^14.0.0-alpha.1253-next.0",
     "@workday/canvas-system-icons-web": "^3.0.35",
     "@workday/canvas-tokens-web": "3.0.0-alpha.12",
     "markdown-to-jsx": "^7.2.0",
@@ -61,5 +61,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "74f6a6aa07c8b1689b37208aed829b22b162acf0"
+  "gitHead": "7b01743972e4f21990fe36d90fa5938f25c57410"
 }