National Poetry Month

    @workday/canvas-kit-react-core
    TypeScript icon, indicating that this package has built-in type declarations

    4.8.1 • Public • Published

    Canvas Kit Core

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

    Includes:

    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];

    Install

    npm i @workday/canvas-kit-react-core

    DownloadsWeekly Downloads

    639

    Version

    4.8.1

    License

    Apache-2.0

    Unpacked Size

    277 kB

    Total Files

    84

    Last publish

    Collaborators

    • workday-canvas-kit
    • justin.pante
    • byed
    • anicholls