@workday/canvas-kit-react
Version:
The parent module that contains all Workday Canvas Kit React components
230 lines (170 loc) • 6.35 kB
Markdown
# Canvas Kit Theming
> **Deprecation Notice:** The `theme` prop on `CanvasProvider` and all associated theming utilities
> (`useTheme`, `getTheme`, `styled`, `defaultCanvasTheme`, `ContentDirection`, etc.) are deprecated.
> Please use CSS variables from `/canvas-tokens-web` for theming. For the full theming
> guide, see our
> [Theming Documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs).
## Sana Canvas Theme
For application-level theming in v16, import the Sana CSS variables and set `data-theme="sana-canvas"`
on `<html>`. See the
[v16 Upgrade Guide](https://workday.github.io/canvas-kit/?path=/docs/guides-upgrade-guides-v-16-0-overview--docs#sana-canvas-theme)
for the canonical setup. The `CanvasProvider` `theme` prop is for **scoped** theming only.
## Installation
```sh
yarn add /canvas-kit-react/common
```
## Recommended Approach: CSS Variables
Canvas Kit v16 promotes using CSS variables for theming. Import CSS variable files and override
values in your root CSS:
```css
/* index.css */
'/canvas-tokens-web/css/base/_variables.css';
'/canvas-tokens-web/css/system/_variables.css';
'/canvas-tokens-web/css/brand/_variables.css';
'/canvas-tokens-web/css/component/_variables.css';
'/canvas-tokens-web/css/sana/_variables.css';
:root {
/* Override brand primary colors */
--cnvs-brand-primary-600: var(--cnvs-base-palette-magenta-600);
--cnvs-brand-primary-500: var(--cnvs-base-palette-magenta-500);
--cnvs-brand-primary-A50: var(--cnvs-base-palette-magenta-A50);
}
```
Or use `createStyles` to generate themed class names:
```tsx
import {CanvasProvider} from '/canvas-kit-react/common';
import {createStyles} from '/canvas-kit-styling';
import {base, brand} from '/canvas-tokens-web';
const themedBrand = createStyles({
[brand.primary600]: base.magenta600,
[brand.primary700]: base.magenta700,
});
<CanvasProvider className={themedBrand}>
<App />
</CanvasProvider>;
```
## Scoped Theming (CanvasProvider)
For embedded or multi-brand sections, use the numerical `brand` shape:
```tsx
import {CanvasProvider} from '/canvas-kit-react/common';
import {base} from '/canvas-tokens-web';
<CanvasProvider theme={{brand: {primary: {'600': base.magenta600}}}}>
<ScopedSection />
</CanvasProvider>
```
### Popups and `sanaCanvasProviderTheme`
Popups (menus, selects, modals) portal to `document.body`. Theme inheritance depends on where
`data-theme="sana-canvas"` lives:
- **You control `<html>`:** set `data-theme="sana-canvas"` there. Popups inherit Sana variables —
no `theme` prop needed.
- **You cannot control `<html>`** (embedded apps, microfrontends, third-party shells): pass
`sanaCanvasProviderTheme` to your root `CanvasProvider`. Nested `data-theme` on a wrapper does
not reach portaled popups; this preset forwards Sana brand variables onto the popup stack.
```tsx
import {CanvasProvider, sanaCanvasProviderTheme} from '/canvas-kit-react/common';
// Required when <html> is unavailable
<CanvasProvider theme={sanaCanvasProviderTheme}>
<App />
</CanvasProvider>
```
See the [Theming documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs) for details.
## Bidirectionality (RTL Support)
### Setting RTL Direction
Use the native HTML `dir` attribute to set the text direction. The `CanvasProvider` accepts a `dir`
prop:
```tsx
import {CanvasProvider} from '/canvas-kit-react/common';
<CanvasProvider dir="rtl">
<App />
</CanvasProvider>;
```
### CSS Logical Properties
Use
[CSS logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties)
for styling. These automatically adapt to the text direction:
```css
/* Use CSS logical properties */
.my-component {
margin-inline-start: 1rem; /* Instead of margin-left */
padding-inline-end: 1rem; /* Instead of padding-right */
}
```
### Conditional RTL Styles
For styles that need to change based on direction, use the
[`:dir()` pseudo-class selector](https://developer.mozilla.org/en-US/docs/Web/CSS/:dir):
```css
/* Use :dir() for RTL-specific styles */
.my-component:dir(rtl) {
/* RTL-specific styles */
}
```
```tsx
import {createStyles} from '/canvas-kit-styling';
const styles = createStyles({
':dir(rtl)': {
svg: {
transform: 'rotate(180deg)',
},
},
});
```
## Breakpoints
Breakpoints are used by media queries to conditionally apply or modify styles based on viewport
width.
### Values
| Name | Size (px) |
| ------ | --------- |
| `zero` | 0 |
| `s` | 320 |
| `m` | 768 |
| `l` | 1024 |
| `xl` | 1440 |
Standard screen size ranges:
- `small` (320px - 767px) - Mobile screens
- `medium` (768px - 1023px) - Tablet screens
- `large` (1024px - 1439px) - Laptop/small desktop screens
- `extra-large` (≥1440px) - Large screens
### Using Breakpoints
You can use standard CSS media queries:
```css
(min-width: 768px) {
.my-component {
padding: 1rem;
}
}
```
---
## Deprecated API Reference
The following APIs are deprecated and should not be used in new code.
### ~~CanvasProvider theme prop~~ (Deprecated)
```tsx
// DEPRECATED - Do not use
<CanvasProvider theme={{canvas: {palette: {primary: {main: 'purple'}}}}}>
<App />
</CanvasProvider>
```
### ~~useTheme / getTheme~~ (Deprecated)
```tsx
// DEPRECATED - Use CSS variables instead
const theme = useTheme();
const theme = getTheme();
```
### ~~styled~~ (Deprecated)
```tsx
// DEPRECATED - Use createStyles or createStencil instead
import {styled} from '/canvas-kit-react/common';
```
### ~~ContentDirection~~ (Deprecated)
```tsx
// DEPRECATED - Use :dir() pseudo-class and CSS logical properties instead
import {ContentDirection} from '/canvas-kit-react/common';
```
### ~~defaultCanvasTheme~~ (Deprecated)
```tsx
// DEPRECATED - Use defaultBranding instead
import {defaultCanvasTheme} from '/canvas-kit-react/common';
// NEW - Use defaultBranding
import {defaultBranding} from '/canvas-kit-react/common';
```
For detailed migration guidance, see our
[Theming Documentation](https://workday.github.io/canvas-kit/?path=/docs/features-theming-overview--docs).