This project provides a set of components for the Workday Canvas Design System that can be used to implement user experiences consistent with Workday's design principles.
Dependency Version Support
The following are supported versions of dependencies.
- React: >=17.0
- Typescript: >=5.0 (optional)
- Emotion: ^11.7.0
Installation
To get started using Canvas kit React first add or install the module to your existing React project
yarn add @workday/canvas-kit-react @workday/canvas-tokens-webor
npm install @workday/canvas-kit-react @workday/canvas-tokens-webFonts
Canvas Kit doesn't include fonts by default. See our Fonts guide for setup instructions, including which font package to use depending on whether your application has the Sana Canvas theme enabled.
Usage
Update your root index.js file to import Canvas Kit's design tokens.
import {createRoot} from 'react-dom/client';
import {injectGlobal} from '@emotion/css';
import {system} from '@workday/canvas-tokens-web';
import {cssVar} from '@workday/canvas-kit-styling';
import '@workday/canvas-tokens-web/css/base/_variables.css';
import '@workday/canvas-tokens-web/css/brand/_variables.css';
import '@workday/canvas-tokens-web/css/component/_variables.css';
import '@workday/canvas-tokens-web/css/system/_variables.css';
// The Sana variables import is needed if you're using the Sana Canvas theme, imported after
// system so its rules win the cascade tie over system's unscoped `:root` rules when set on <html>.
import '@workday/canvas-tokens-web/css/sana/_variables.css';
import {App} from './App';
injectGlobal({
'html, body': {
fontFamily: cssVar(system.fontFamily.default),
margin: 0,
minHeight: '100vh',
},
'#root, #root < div': {
minHeight: '100vh',
...system.type.body.sm,
},
});
const container = document.getElementById('root')!;
const root = createRoot(container);
root.render(<App />);Set data-theme="sana-canvas" on <html> in your index.html:
<html lang="en" data-theme="sana-canvas"></html>Then in your App.js you can wrap your application with CanvasProvider.
import {CanvasProvider} from '@workday/canvas-kit-react/common';
export const App = () => {
return (
<CanvasProvider>
<main>
<p>Get Started With Canvas Kit</p>
</main>
</CanvasProvider>
);
};If you cannot control <html> (embedded apps, microfrontends), pass sanaCanvasProviderTheme
instead so menus, selects, and other popups still get Sana brand variables:
import {CanvasProvider, sanaCanvasProviderTheme} from '@workday/canvas-kit-react/common';
<CanvasProvider theme={sanaCanvasProviderTheme}>
<App />
</CanvasProvider>Note: Don't use the
CanvasProviderto theme, instead use our CSS tokens from@workday/canvas-tokens-web. For more information, view our Token docs. Theming should be global.
If you spot a bug, inconsistency, or typo, please open a bug issue. Better yet, submit a pull request to address it.
If you have an idea, we would love to hear about it. The best way to suggest a feature is to open a feature issue. The Canvas Kit core team will take a look and discuss it with you.
Want to contribute to Canvas Kit React? Please read our contributing guidelines to find out more and how to get started.
If you're a Canvas Kit maintainer, please read our maintaining docs to learn more about our processes.
All work on the Canvas Kit happens directly on GitHub. Both core team members and external contributors can send pull requests which go through the same review process. Any and all issues are public and available for discussion.
Canvas Kit follows semantic versioning and is enforced automatically by conventional commits (see "Commit Message Format").
Each module is independently versioned using Lerna.
At any given time, we support three major versions of Canvas Kit: previous, current, and next. Each of these has different levels of support.
The previous major version is stable for production and will receive patch updates as needed, but there will be no new features added. Patch releases are automatically deployed upon merge by GitHub Actions.
The current major version is also stable and receives new features and patch updates. Patch releases are automatically deployed upon merge by GitHub Actions, and minor releases are manually deployed at the end of each sprint.
The next major version is typically an unstable environment and has major breaking changes. You are welcome to pull this version down for local development and experimentation, but we generally recommend against using it in production until the first stable version has been released.
- Contributing
- Code of Conduct
- Upgrade Guides:
- Code Style / Best Practices:
The Workday Canvas Kits are licensed under the Apache 2.0 License.
- Microsoft Edge: last 2 versions
- Mozilla Firefox: last 2 versions
- Google Chrome: last 2 versions
- Apple Safari: last 2 versions
- Opera: last 2 versions
Visual Testing by ChromaticQA
Builds by Github Actions