best practice of using custom styles / classNames on paste components

[krnan9525]

Hi everyone,
We started using Paste components recently, and there are some problems around custom styling we have been facing.

Currently paste components do not allow us to add classNames. This makes things a bit difficult when we want to add some custom styling if those properties are not exposed by Paste. The work around we use is to wrap them in another element and give that element a className then add stylesheet on that class or using styled component (@twilio-paste/styling-library).

Is there a better way to do all this? So we don't need to create an extra element just to pass in some additional stylings?

Also, is there an example of good practice project using Paste we can refer to?

Thanks for the help.

🙇

[SiTaggart]

There's a couple of topics covered here and I'll try my best to cover them as best I can.

When using Paste to build Twilio products there are some expectations set on what process to follow. Part of that process is ensuring that what we put in front of users is well researched and vetted within the UX organization, plus robust and accessible. We want the very best user experience so we put a lot of up front effort into design process of our components. As a result, we don't necessarily want that work to be degraded or removed without critical reasoning, peer review and use of a cohesive design language.

This is the main reason around our design decision to not allow direct, uncontrolled customization of our components.

Whilst we are acutely aware that a Design System cannot do and hold everything that is needed for each individual product, and that extension and customization is the key to a successful Design System at scale, we will not be providing that functionality via a custom classname.

We won't be doing this for a number of reasons:

• Global classnames, especially overrides, impact the confidence teams can have on the state of their styling. There is no guarantee you won't affect someone else or they won't affect you, impacting the success of independent teams and confidence in your deploys. This particularly applies to a number of Twilio products that are multi-tenant UI, where multiple independent teams are providing UI to a single page
• Uncontrolled customization causes design fragmentation
• Uncontrolled customization impacts the ability of the Design System team to push changes to and evolve the Design System, without adversely impacting downstream consumers

Above all, custom classnames erode trust in the system, the components, the product and adversely affect the trust of the customer.

Customization and extension will be provided, but it will be provided via a controlled API, within the constraints of the Design System. More on that soon.

In the meantime we have a number of existing mechanisms for product teams to use to ship their product features.

The first part is process based. There should be regular design critique sessions for a designer to attend to get feedback on their designs and Paste usage. There are also twice weekly Design System Office hours to ask questions about component use and design. In these forums designers can present challenges, or research that suggests that a component within the system doesn't address the customer need. Upon receiving this feedback the Design System team can offer advice, reasoning and alternative suggestions, but most importantly use that feedback to improve the system for everyone else who uses it.

The second part is based on the way we designed the system and our component APIs. A lot of our components accept any children due to the flexibility we want to provide to consumers. Here, components can take any styled content that solves that particular customer problem. What this does is keep a cohesive overall design, structure and interaction to all the base components whilst allowing you to display your data to the user in any format you wish. If that still isn't meeting the customer need, the system provides Component Primitives.

Primitives come in 2 forms; functional and design. A design primitive like Box and Text encapsulate our design language into style props. Style props take a design token name and translate it to css. This allows you to create custom components within the guardrails of our design language, and when we update that design language you will inherit those changes just by updating the design tokens package. A functional primitive provides accessible functionality and interaction with out providing a UI, like the Menu Primitive. Coupled with a Design Primitive, you are then able to create product specific, accessible, custom components that will always use the approved design language provided by the Twilio UX organization.

I hope that helps answer why we don't just allow consumers to change our components, and the mechanisms and primitives we provide still allow you to ship products that solve specific customer problems. Let us know if you have any further questions.

[krnan9525]

Hi Simon,
This all sounds good. A few very specific questions tho:

1. we currently don't allow arbitrary values, how should I set one column to 35% another to 65%?
2. Box is basically a wrapper around native DOM elements, should we not use <div> / <span> / <li> etc. any more?
3. If the primitive component is to unify design tokens (which can be passed as props to define styling), can we also just use native DOM elements with imported design token variables? This will help us using arbitrary values, and supports existing design. And it is also the most familiar for every developer from all background.

Thanks

[SiTaggart]

Just some quick answers to these:

1. we currently don't allow arbitrary values, how should I set one column to 35% another to 65%?

Until we add the arbitrary width and height values you can just extend Box as a styled component if you like.

import {styled} from '@twilio-paste/styling-library';
import [Box} from '@twilio-paste/core';

const CustomBox = styled(Box)({
  width: 65%;
})

// <CustomBox backgroundColor="colorBackgroundSuccess" />

2. Box is basically a wrapper around native DOM elements, should we not use div / span / li etc. any more?

If you're not styling it, go for it. If you're styling it we're hopeful that Box and Text will be your go to tool.

3. If the primitive component is to unify design tokens (which can be passed as props to define styling), can we also just use native DOM elements with imported design token variables? This will help us using arbitrary values, and supports existing design. And it is also the most familiar for every developer from all background.

You can, it's documented here https://paste.twilio.design/tokens/theme-package/#using-tokens-in-custom-components, but using Box is always going to be preferred from our perspective.

[krnan9525]

I tried to style a Flex but the following doesn't seem to work:
const test = styled(Flex)({ width: '50%' });
Am I only able to use for styled component?

[SiTaggart]

Only primitives are allowed to be styled. Flex is a layout component.

[krnan9525]

Also, I will have to import basic Paste components / primitives every time, just to achieve something simple already supported by browser.

Another thing will be on testability:
comparing these two on snapshot mounting tests:
<div className='some-class'>Test</div>
and
<Box width='size60'>Test</Box>
with a new version update, the width60 might change, then the new snapshot will be different and causing the test to fail.
I wouldn't say this is a blocker but it's more of an overhead.

Thanks

[SiTaggart]

So, a couple of things here.

If you're snapshotting generated CSS, we've found this to be super problematic and not particularly worth while. If you don't wrap the test in a theme provider it will only snapshot the token names so there is much less thrash in breaking snapshots, but it's still not particularly a useful test. If you want to catch visual regressions we would strongly suggest you utilize something like Applitools which is a paid for tool from Platform Engineering and much better at the job.

If you're only snapshotting the markup, the tokens you set will only differ in the snapshot if you change them. If you're snapshotting markup that is generated from our components, then yes the reflected attributes in the DOM would change but that is an expected change that I would expect a test to catch. Just like a visual regression test, a component update should break your test if that test is working. The real question then, is that test worth while you writing?

For what its worth, we don't snapshot markup or CSS anymore and will be removing them from our repo. We've found that the tests aren't very useful, are not intentional enough and prone to breaking often. If we're trying to catch visual regression we use a visual regression tool, and if we're trying to ensure something about the generated DOM we write very explicit tests querying the DOM and expecting certain tagnames or attributes to be present in expect statements. These are much less brittle and less effected by natural change

[krnan9525]

Although, with everything said, they are all just open questions. I will use Paste the way they are suggested now.
and thanks for the help 🙇