Preferred approach for styling in Flex 2.0

[curtis-perficient]

We're a partner evaluating the Flex 2.0 private beta, so this is our first real introduction to Paste. So be gentle ;-)

Couple of general questions not 100% obvious from the docs around styling. For context, we are doing an exercise where we move Flex 1.0 plug-ins using Material UI to Flex 2.0/Paste.

Given the requirement to use symbols for styling, I'll ask a super basic question.

Given a Card or Button component for instance, if I wanted to change the background color of that object, what is the correct way to do it? Maybe this is a customer brand color.

1. Override one of the default theme symbols (not clear how to do this from the docs)
2. Add a new symbol to the default theme (not clear how to do this either)
3. Use the styled component approach
4. What you are trying to do isn't fully supported yet, come back later.

Appreciate any advice.

[SiTaggart]

Hi @curtis-perficient, thanks for your interest in Paste, we're super excited to hear about it.

We've been working hard on something to support this for the last few months. The documentation for it is likely going to be released in the next couple of weeks. We're super close, and looking for feedback on them once out in the wild.

Customization Provider

Ordinarily you would wrap you application in a Theme Provider from the @twilio-paste/theme package. This provides the application with one of two themes, default and dark. This has been specifically designed for internal Twilio use, which is why it's restricted.

So, for customers like yourselves, who would like to extend, modify or change the design language that comes with Paste, we added a new package just for you. @twilio-paste/customization.

The main export is a Customization Provider, which is designed to replace the normal Theme Provider.

import {CustomizationProvider} from '@twilio-paste/core/customization';

const App = () => {
  return (
    <CustomizationProvider>
      // your app
    </CustomizationProvider>
  )
}

This will allow you to do two things. Theme the entire Application by providing your own theme (as long as it matches the Paste theme shape) and Customize tagged elements inside a Paste component.

Theming

Theming, just like Material UI, or Chakra UI, allows you to provide a full application theme to change atomic design characteristics of Paste. We embrace the concept of Design Tokens, and our theme is representative of the full list of design tokens, bucketed by category.

The customization provider allows you to provide a theme object as a prop, that can be a partial of a full Paste Theme. This means you can provide Paste just the design tokens you want to override and we'll merge it with the base theme you choose. Or you can provide an entire theme in full. The default base theme is default.

import {CustomizationProvider} from '@twilio-paste/core/customization';

const App = () => {
  return (
    <CustomizationProvider
      baseTheme="default|dark"
      theme={{
        textColors: {
          colorText: 'hotpink'
        }
      }}
    >
      // your app
    </CustomizationProvider>
  )
}

Currently the easiest way to create a full custom theme might be to use our new experimental tool https://remix.twilio.design/.

Component element customization

In Paste we are also introducing the concept of Component Elements. These are tagged DOM elements, inside a component, that can be provided custom CSS.

When inspecting the DOM of Paste components you will start seeing more components are decorating DOM nodes with a data attribute called data-paste-element.

<article data-paste-element="CARD">
  <h2 data-paste-element="HEADING">...</h2>
  <p data-paste-element="PARAGRAPH">
    ...
  </p>
  <a data-paste-element="BUTTON" href="#">...</a>
</article>;

These DOM nodes with data-paste-element are tagged Component Elements. You can use the value of these as keys in a elements object, and pass it to the Customization Provider as a prop.

import {CustomizationProvider} from '@twilio-paste/core/customization';

const App = () => {
  return (
    <CustomizationProvider
      baseTheme="default|dark"
      elements={{
        CARD: {},
        BUTTON: {},
        HEADING: {},
        PARAGRAPH: {}
      }}
    >
      // your app
    </CustomizationProvider>
  )
}

Each element in the elements object should be assigned an object of custom CSS that you would like to be applied to that DOM node. We use Emotion CSS under the hood, so following their guidelines should inform you of the syntax we're expecting here.

In summary, every component will expose one or more Component Elements. Inspect the DOM, use the values of those data attributes in the elements object on the customization provider to override the CSS for that DOM node. Your custom styles will be merged on top of the base styles of that node.

Right now, the CSS object you provide is fairly restrictively typed in TypeScript. We are assuming that CSS properties that are aligned to one of our Design Token categories, should only use Design Token values to start with. This will naturally constrain you to style components using the provided theme, which you can override. This should make it easier to create custom, themed, or themable components, which will naturally respond to light and dark modes, should you choose to implement them. So, for example the backgroundColor CSS prop can only be assigned a background color design token. If this proves to be too restrictive, we may open this up later.

What you can do today

The good news is this all works today. We are roughly 70-80% of the way through refactoring our components to tag Component Elements and we continuously deploy those changes.

We have created a small example codesandbox with a working example: https://codesandbox.io/s/customization-example-s3yx9?file=/src/CustomizationExample.tsx

The easiest way to find out which components support element customization right now, is to just inspect the DOM using the browser developer tools. Soon all components will support it.

As mentioned the documentation will be released soon, but we are excited to hear what you think about it and what your experiences are using it.

Flex specifics

Flex will soon be providing documentation around theming and how it will relate to Paste. I think some of that might already be available to Flex 2.0 beta customers. Please contact your Flex reps from Twilio for that. From my understanding the Flex theme is a superset of the Paste theme.

For Flex Plugins, I believe as they are basically new React apps inside a large Flex app, you can just wrap the plugin with the customization provider, and use Paste components as you wish.

I hope that helps answer your initial questions. Let us know how you get on and if we can help any further.

[curtis-perficient]

Very nice. This gets me most of the way there. We are using the theme provider already. I did play around with using a styled-components approach a bit and that worked to do some custom CSS, but I would like to avoid that in cases where I really just want to override theme symbols. I would say in Flex, our typical engagements would tend towards overriding of certain theme elements rather than creating a whole new theme from scratch. We could do some of this in Flex 1.0 of course, but 2.0 will open this up in a way that is more flexible and consistent across all the various views and elements. Let me give that customization package a try.

If I'm understanding it correctly, I could see us using the component element customization approach quite a bit as well and I like how that is a bit more centralized and structured than creating individual styled components within a React component.

Really appreciate the detailed answer and you taking the time to provide it.