@workday/canvas-kit-react-core

Canvas Kit Core

Canvas Kit Core contains values and base styles that are shared across the kit.

Includes:

• Colors
• Border Radius
• Spacing
• Depth
• Type
• Providers

Installation

yarn add @workday/canvas-kit-react

or

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

Colors

Workday Canvas Colors are directly exported from @workday/canvas-colors-web. Colors come in shades from 100 (lighter) - 600 (darker). These can be used directly, but semantic constants are preferred.

Colors (100-600):

• Cinnamon
• Peach
• Chili Mango
• Cantaloupe
• Sour Lemon
• Juicy Pear
• Kiwi
• Green Apple
• Watermelon
• Jewel
• Toothpaste
• Blueberry
• Plum
• Berry Smoothie
• Blackberry
• Island Punch
• Grape Soda
• Pomegranate
• Fruit Punch
• Root Beer
• Toasted Marshmallow
• Coconut
• Cappuccino
• Soap
• Licorice
• French Vanilla
• Black Pepper

Usage

import {colors} from '@workday/canvas-kit-react-core';

colors.blueberry400;

Each of the colors have a gradient version as well

import {colors} from '@workday/canvas-kit-react-core';

colors.gradients.blueberry;

Semantic constants

To ensure consistency across implementations, our semantic constants should be used wherever possible. This allows us to swap out the color of a button or icon for example, without having to find every instance of it and change the color manually.

We have several semantic groupings:

• commonColors
• buttonColors
  • delete
  • primary
  • secondary
• iconColors
• statusColors
• typeColors

import {iconColors} from '@workday/canvas-kit-react-core';

iconColors.hover;

Border Radius

Border Radius variables are in a "t-shirt size" format. Border Radius values are in px format.

Variable	Size (px)
zero	0
s	'2px'
m	'4px'
l	'8px'
circle	'999px'

Spacing

Workday Canvas Spacing is directly exported from @workday/canvas-spacing-web.

Spacing variables are in a "t-shirt size" format. Spacing values are in px format (spacing) or number format (spacingNumbers).

Variable	Size (px)	Size (number)
xxxs	'4px'	4
xxs	'8px'	8
xs	'12px'	12
s	'16px'	16
m	'24px'	24
l	'32px'	32
xl	'40px'	40
xxl	'64px'	64
xxxl	'80px'	80

Margin & Padding

Spacing functions provide margin and padding spacing. These are available with the space function. The space function utilizes the following props:

Margin Props

• m margin
• mt margin-top
• mr margin-right
• mb margin-bottom
• ml margin-left
• mx margin-left & margin-right
• my margin-top & margin-bottom

Padding Props

• p padding
• pt padding-top
• pr padding-right
• pb padding-bottom
• pl padding-left
• px padding-left & padding-right
• py padding-top & padding-bottom

Usage

import {spacing, spacingNumbers, space} from '@workday/canvas-kit-react-core';

spacing.s; // 16px
spacingNumbers.s; // 16

...

const Box = styled('div')(space)

<Box p={spacing.xl} pb={64} m={40} mx={10}>
  ...
</Box>

/*
  margin-top: 40px;
  margin-right: 10px;
  margin-bottom: 40px;
  margin-left: 10px;
  padding-top: 40px;
  padding-right: 40px;
  padding-bottom: 64px;
  padding-left: 40px;
*/

Depth

Five levels of depth are available. They are directly exported from @workday/canvas-depth-web.

Level	Usage Recommendations
Depth -1 (inset)	Inset card depth
Depth 1	Standard card depth
Depth 2	Increased card depth on hover
Depth 3	Active cards, popups
Depth 4	Cards on white backgrounds, menus

Usage

import {depth} from '@workday/canvas-kit-react-core';

depth.inset;
depth['2'];

Type

Type styles are available as objects to use alone or with Emotion.

Fonts

To use the Canvas Kit font install and import the @workday/canvas-kit-react-fonts module. Note that this module sources fonts from the Workday CDN.

Hierarchy

Our type module is a combination of hierarchy and variants. The hierarchy has the font size, weight, etc. for different levels of type (e.g. canvas.type.h1, canvas.type.body, etc.). The variants (e.g. canvas.type.variant.label) are applied to a hierarchy level to achieve certain styling. Variants only come their augmenting styles and a base type object is required.

Hierarchy Levels
dataViz1
dataViz2
h1
h2
h3
h4
h5
body
body2
small

Variants
label
button
caps
hint
error
inverse
mono
link

Disclaimer

A new type hierarchy is in the process of being introduced into our products. You can find more info about it in the Labs Type section. We plan to maintain both hierarchies for a short time, but there will be a breaking change when we replace the current one with the new one.

Usage

If you're working in emotion, you can simply spread the type objects to use their styles.

import {type} from '@workday/canvas-kit-react-core';

const MyLabel = styled('label')({
  ...type.body,
  ...type.variant.label,
});

If you are only using one object, you can do this inline with the style attribute. For headings, styled components are also available.

import {H2, type} from '@workday/canvas-kit-react-core';

<h1 style={type.h1}>H1 Header</h1>;
<H2>H2 Header</H2>;

To combine objects inline, you can also use emotion's css function.

import {type} from '@workday/canvas-kit-react-core';

<label css={[canvas.type.body, canvas.type.variant.label]}>Label Text</label>;

Providers

Providers are higher order (wrapping) components used to provide global configuration to Canvas components.

Input Provider

This is a higher order (wrapping) component for providing css-referencable data attributes for the users current input. Focus outlines are required for accesibility, but they can be unnecessary visual noise when using a mouse. This allows us to hide focus outlines (as desired) while the user is interacting with components using a mouse, touch, etc. and show them when keyboard navigation begins. This logic is heavily influenced by what-input. You can use it to style your own components as well using the examples below.

Preferably you would use the CanvasProvider as InputProvider functionality is included within it. However, if you want InputProvider functionality on it's own, you can use this.

Definitions

Input: The current input method from the user.

• Equal to one of InputTypes
• Triggered by the following events:
  • keydown
  • keyup
  • mousedown
  • MSPointerDown
  • pointerdown
  • touchstart

Intent: The potential next input method from the user. Mouse, pointer and mouse wheel events only demonstrate potential, but not actual, interaction and are treated separately. Note: if input type updates from the events above, the intent type will also be updated to the same value.

• Equal to one of InputTypes
• Triggered by the following events:
  • mousemove
  • MSPointerMove
  • pointermove
  • wheel
  • mousewheel
  • DOMMouseScroll

Usage

As an external consumer, you should reference the following example.

If you are contributing a component, you must add the necessary styling (see below) and use the InputProviderDecorator in your stories. DO NOT use an InputProvider directly within any Canvas Kit components.

import * as React from 'react';
import {InputProvider} from '@workday/canvas-kit-react';

<div>
  <InputProvider />
  {/* All your components containing any Canvas components */}
<div>;

This will result in these data attributes being added to the body element (by default)

<body data-whatinput="mouse" data-whatinput="mouse">
  <!-- All your components' HTML -->
</body>

Now in any component within this wrapper, you can use these data attributes to customize the focus handling.

React/Emotion:

[`[data-whatinput='mouse'] &:focus,
  [data-whatinput='touch'] &:focus,
  [data-whatinput='pointer'] &:focus`]: {
  outline: 'none',
  border: 'none',
},

SCSS:

[data-whatinput='mouse'],
[data-whatinput='touch'],
[data-whatinput='pointer'] {
  .my-component:focus {
    outline: none;
    border: none;
  }
}

We provide a helper to hide the focus outlines on mouse input. Simply spread it in your styles (i.e. ...hideMouseFocus).

Note: It is best practice to show focus outlines by default and specifically hide them in the cases you would like (i.e. mouse/touch/pointer input).

Note: Multiple InputProviders in the same tree are not supported. Any nested InputProvider will remove itself from the DOM (rendering only its children) and not attach any event listeners.

Static Properties

InputTypes

Theme
Keyboard
Mouse
Pointer
Touch

---

Component Props

Required

None

Optional

provideIntent: boolean

Whether you would like the attribute data-whatintent rendered (see definition of intent above). Note: detecting intent will add scroll and mouse positioning listeners which could affect performance.

container: HTMLElement | React.RefObject<HTMLElement>

The containing element in which the InputProvider attaches its data attributes. This property should be set to an element that is an ancestor of all your Canvas components.

Default: document.body

Storybook Decorator

We provide a storybook decorator to wrap your stories in an InputProvider automatically.

Add this decorator to your /.storybook/preview.js configuration file to apply to all stories:

import {InputProviderDecorator} from '../utils/storybook';

export const decorators = [InputProviderDecorator];

Or, add it to stories individually:

import {InputProviderDecorator} from '../../../../utils/storybook';

export default {
  title: 'MyComponent',
  component: MyComponent,
  decorators: [InputProviderDecorator],
};

// OR

MyStory.decorators = [InputProviderDecorator];