FAQ and best practices for adopting v10 new styling library

[mannycarrera4]

Why is there a new way of styling for Canvas Kit in v10?

We introduced a new styling library @workday/canvas-kit-styling in v10 so that we can slowly move off of Emotion and provide better support to our consumers that need CSS. For a more in depth discussion you can reference our Future of Styling Discussion.

How am I supposed to style Canvas Kit components in v10?

At the moment, there should be no change in how you style our components. Meaning, you can still use Emotion styled components, style props, the css prop, or inline styles.

Should we stop using Style Props, the css prop, and Emotion styled components?

Short answer: Not yet

Long answer: There's two possible paths:

1. Update everything to use the new styling now.
2. Use new styling for new things and/or when refactoring. The Canvas Kit team is working on more incremental migration tooling including codemods.

It's our intention as a library to not dictate how consumers use our library or what preferences they have when styling our components. However with the introduction of this new styling library, and the unstable future of Emotion, we intend to introduce patterns to help guide our consumers when transitioning to this new way of styling.

TLDR

• Style props will probably be deprecated in the near future in favor of our new styling utilities. We will give teams ample time for this transition and we understand that they are heavily used!
• Box, Flex, Text and Grid will probably be deprecated with the exception of maybe supporting style props that are associated to a token instead of dynamic styles.

What does style merging look like in v10?

1. On an element that only uses createStyles (we'll call this static styling), styles are merged according to CSS specificity. Basically, the order that styles are defined in a file determines merge order. The order of styles in the element's ClassList don't matter.
2. If style components, style props, or the css prop are used (we'll call these dynamic styling), styles are merged according to the rules of Emotion. The order on the ClassList does matter. Therefore it is best to both order createStyles correctly in your file as well as the correct order in the cs prop list.

const baseStyles = createStyles({
  padding: 10
  // base styles
})

const modifierStyles = createModifiers({
  size: {
    small: createStyles({
      padding: 8 // overrides base style padding 10
    })
  }
  // modifiers AFTER base styles because modifiers should override base styles
})

// in render function
<Button cs={[baseStyles, modifiersStyles(/* ... */)]} />
// Note the modifiers are listed AFTER base styles so the merge order is always consistent

Here's a storybook example covering what style merging looks like.

createStyles > CSS Prop > Styled Component > Style props

We wanted to provide backwards compatibility with Emotion while introducing the future of how we want to style components.

How are style props applied differently in v10 than in v9?

Only buttons use our new styling, so the changes only apply to Buttons.

1. Style props are no longer forwarded to components via the as prop. This was most commonly a problem with routers using a Link. Box has conditional logic to determine how it should do prop filtering. If the as is a base element (as="button", as="a"), it will use Emotion's isPropValid function. If the as is a component (as={MyComponent}, as={Link}), Box would not to any prop filtering. Box cannot assume what props the component understands and therefore the as component needs to understand all style props as well and filter out manually.

   // v9
   // filter out `padding` because `Link` doesn't filter it out
   const MyLink = ({padding, ...props}) => <Link {...props} />
   <PrimaryButton as={Link} padding={10}>Click Me</PrimaryButton>
   
   // v10
   // `padding` is already filtered out
   <PrimaryButton as={Link} padding={10}>Click Me</PrimaryButton>

2. Style props are applied via mergeStyles at each layer of wrapping. This means style props aren't unpredictable.

Here's more detail on the second point:

<MyComponent padding="40px" />

It isn't obvious what padding will do. It depends on the implementation of MyComponent.

// Padding will be 40px
const MyComponent = props => <Box {...props} />

// Padding will be 10px
const MyComponent = props => <Box css={{padding: 10}} {...props} />

Box works by setting padding at the Box component rendering layer. Emotion styles components based on a "outermost" styling winning. So the css prop added at the render layer will be considered outermost because the padding prop is passed via prop drilling to the innermost component Box. Style props have a way of making styling merging unpredictable. This can be further complicated if MyComponent didn't originally style padding via the css prop. Adding padding certainly didn't change the external interface of the component, but it changed the runtime contract in a non-obvious way.

In v10, we introduced mergeStyles which operates the same as the css prop from Emotion. Instead of prop drilling to a base component, it applies style props at each component layer. mergeStyles is also for handling the cs prop.

const myComponentStyles = createStyles({
  padding: 10
})

const MyComponent = props => <div {...mergeStyles(props, myComponentStyles)} />

// Padding will be 40 because 40 is applied as an _overriding_ style to `myComponentStyles`
<MyComponent padding={40} />