Using Sana Canvas Kit

The primary way you will interact with Sana Canvas will be with our Sana Canvas Kit React library . Sana Canvas Kit provides a set of components and primitives that can be used to implement user experiences consistent with the rest of Workday. As of v11, our library relies on the usage of our Tokens  package for styling.

Sana Canvas Kit

We support installation for existing projects and bootstrapping in a new project.

Installation

For an existing project, add the Sana Canvas Kit React dependency with your preferred package manager.

With Yarn:

> yarn add @workday/canvas-kit-react

With npm:

> npm install --save @workday/canvas-kit-react

Sana Canvas Tokens

This package provides Sana Canvas design tokens for web applications. As of v11 our components rely on our Tokens Package . You must install and import the variables to ensure our components are styled correctly.

> yarn add @workday/canvas-tokens-web

Import the variables at the top level of your application to prevent duplicate imports and avoid unintentional overwrites. Import them in a native CSS file or in a JavaScript / TypeScript file as shown below. Order matters — import the Sana variables last.

/* index.css */
@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';
@import '@workday/canvas-tokens-web/css/sana/_variables.css';

// index.ts
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';
import '@workday/canvas-tokens-web/css/sana/_variables.css';

For more information, view our Sana Canvas Tokens docs .

Important: If your application lives within another application that already imports the CSS variables, you do not need to import these again. If you need tokens for local development, add them via a plugin or directly to the environment but do not ship code to production with duplicate token imports.

Importing the Sana variables last also sets you up for the Sana Canvas theme — see Theming below.

Sana Canvas Kit Fonts

Sana Canvas Kit doesn’t include fonts by default. Which font you need depends on whether your application has the Sana Canvas theme (data-theme="sana-canvas") enabled:

• If the Sana Canvas theme is enabled, use Sana Sans.
• If the Sana Canvas theme is not enabled (the default/legacy Canvas theme), use Roboto.

Inject @font-face styles with injectGlobal from @workday/canvas-kit-styling. We prefer this approach over @emotion/react’s Global component.

Note: If your application environment already provides the correct font, you don’t need to inject it. Font files are sourced from the Workday CDN.

Sana Sans

Use Sana Sans whenever the Sana Canvas theme is enabled. The fonts module is exported from @workday/canvas-kit-react/fonts and includes Sana Sans VF (a variable font supporting weights 100–700) and IBM Plex Mono for system.fontFamily.mono.

import {fonts} from '@workday/canvas-kit-react/fonts';
import {injectGlobal} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';
 
injectGlobal({
  ...fonts,
  'html, body': {
    fontFamily: system.fontFamily.default,
    margin: 0,
    minHeight: '100vh',
  },
});

Once the theme’s font-family token and the loaded @font-face share the same family name, Sana Sans renders automatically wherever data-theme="sana-canvas" is set — no additional CSS override is required.

Roboto

If your application doesn’t have the Sana Canvas theme enabled, install @workday/canvas-kit-react-fonts to load Roboto instead. This module also includes Roboto Mono for system.fontFamily.mono.

yarn add @workday/canvas-kit-react-fonts

import {fonts} from '@workday/canvas-kit-react-fonts';
import {injectGlobal} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';
 
injectGlobal({
  ...fonts,
  'html, body': {
    fontFamily: system.fontFamily.default,
    margin: 0,
    minHeight: '100vh',
  },
});

Theming

Sana Canvas Kit theming has two layers: components are Sana-aligned out of the box regardless of theme, and the Sana Canvas theme is a separate, opt-in step that updates brand colors, neutrals, surfaces, and shapes at the application level.

Global Theming

To enable the full Sana Canvas theme, import the Sana variables last (see Canvas Tokens above) and set data-theme="sana-canvas" on <html>:

<html lang="en" data-theme="sana-canvas"></html>

Omitting data-theme keeps classic Canvas branding — there is no [data-theme="canvas"] rule; the Sana stylesheet only defines [data-theme="sana-canvas"] overrides, so removing the attribute is how you get classic Canvas back. For a full list of what changes when you opt in, see the Sana Canvas Kit v16 Upgrade Guide.

Note: The Sana Canvas theme requires @workday/canvas-tokens-web 4.4.0 or later.

Sana Canvas Kit uses logical CSS properties, so layout direction is controlled by the standard HTML dir attribute rather than a theme setting. Set dir="rtl" on <html> or a scoped ancestor to switch to right-to-left layout:

<html lang="ar" dir="rtl" data-theme="sana-canvas"></html>

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: 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 level in <CanvasProvider>.

When the Sana Canvas theme is enabled globally via data-theme="sana-canvas" on <html>, most applications don’t need to pass a theme prop to CanvasProvider:

import {CanvasProvider} from '@workday/canvas-kit-react/common';
 
// <html data-theme="sana-canvas">
<CanvasProvider>
  <App />
</CanvasProvider>;

If you are not opting into the Sana Canvas theme, omit data-theme from <html> and wrap your app the same way — no theme prop is required.

Scoped Theming

Most application teams should use the Sana Canvas theme globally and not pass a theme prop to CanvasProvider. Use scoped theming only when a section of your app needs a different brand — for example, embedding Canvas in a third-party application, multi-tenant branding, or popup parity.

The theme prop accepts a numerical brand object. Each key maps 1:1 to a --cnvs-brand-* CSS variable. Focus does not follow primary — setting only brand.primary['600'] leaves focus rings at the default blue unless you also set focus.primary.

import {CanvasProvider} from '@workday/canvas-kit-react/common';
import {base} from '@workday/canvas-tokens-web';
 
<CanvasProvider theme={{brand: {primary: {'600': base.magenta600}}}}>
  <ScopedSection />
</CanvasProvider>;

If your application has opted into Sana globally but one subsection needs classic Canvas branding, use defaultBranding on a scoped CanvasProvider:

import {CanvasProvider, defaultBranding} from '@workday/canvas-kit-react/common';
 
<CanvasProvider className={defaultBranding}>
  <ClassicCanvasSection />
</CanvasProvider>;

Popups and Portaled Content

Popups (menus, selects, modals, and toasts) portal to document.body — outside the parent component’s DOM hierarchy. When you control the document root, setting data-theme="sana-canvas" on <html> is enough; popups inherit Sana CSS variables automatically.

If you cannot set data-theme on <html> (embedded apps, microfrontends, third-party shells), a nested data-theme alone does not reach portaled popups. Pass both data-theme="sana-canvas" (for in-tree UI) and sanaCanvasProviderTheme (so Canvas Kit forwards Sana brand variables onto the popup stack container):

import {CanvasProvider, sanaCanvasProviderTheme} from '@workday/canvas-kit-react/common';
 
<CanvasProvider theme={sanaCanvasProviderTheme} data-theme="sana-canvas">
  <App />
</CanvasProvider>;

For more on theming, see the Canvas Kit Theming story .

Bootstrapping

Canvas Kit is built with React and Create React App  is recommended for bootstrapping a new React project.

Usage

Now you’re ready to import our components.

import {PrimaryButton} from '@workday/canvas-kit-react/button';
 
<PrimaryButton>Get Started</PrimaryButton>;

For more information on how to use Canvas Kit components, check out their documentation in the Components section.

Resources

For more documentation, helpful links and other developer resources, check out the Resources page.

Reporting a Bug

If you spot a bug, inconsistency, or typo, please open a bug issue . Better yet, submit a pull request to addresses it.

Feature Requests

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.

Questions

If you have a question, we are here to help! Start a new discussion  to be connected to one of our team members.

Contributing

Want to contribute to Canvas Kit? Please read our contributing guidelines  on GitHub to find out more and how to get started.

Versioning

Canvas Kit follows semantic versioning  and is enforced automatically by conventional commits  (see “Commit Message Format” .