RFC: customising the style of Source components #306

SiAdcock · 2020-04-03T15:27:11Z

SiAdcock
Apr 3, 2020
Collaborator

In an effort to maximise the usefulness of components, we support consumers customising styles. We do this for two reasons:

it's an opportunity for consumers to experiment with new visual patterns and appearances without having to codify them in Source
it ensures consumers can use our components even if they don't fully match the desired visual requirements. We must accept that our applications are slightly different. The alternative would see potential consumers forking Source components, leading to unacceptable fragmentation.

Currently there are a number of ways to customise styles of components:

Theming

Source allows consumers to create their colour theme for a component. This is a first class approach to customisation.

cssOverrides

Users of @emotion/core can pass additional styles to the cssOverrides prop. This is more idiomatic to @emotion/core, but it's a bit clunky as the overrides get applied to a single element that is part of the component.

If a consumer wishes to override the styles of a different element, they must try and target it using sibling or descendant selectors. Some elements are not stylable in this way, so the approach is limited.

className

Source allow consumers to pass classes to the className prop. This is more idiomatic to React. Depending on the order in which style elements are added to the DOM (and @emotion/core is very keen to get styles at the bottom of the <head>), styles that use classes passed in this way may need !important declarations.

Like with cssOverrides, if a consumer wishes to override the styles of a different element, they must try and target it using sibling or descendant selectors. Some elements are not stylable in this way, so the approach is limited.

Request for comments

I'm considering a new API that works similar to the cssOverrides property but instead of receiving a single SerializedStyles object, it receives a map of SerializedStyles, expressed as a Map or a plain JS object:

<TextInput 
    label="One snazzy text input field"
    supporting="Do not adjust your set"
    customStyles={{ 
        label: css`color: hotpink;`,
        input: css`background-color: green;`,
        supporting: css`font-family: Latino;`
    }}
/>

We would need to document which elements are stylable, and how to reach them using keys in the map.

I'll be happy to hear opinions on this, or thoughts about limitations or difficulties with this approach. If anyone has any other suggestions, please add them below.

Thanks so much for reading!

JamieB-gu · 2020-04-06T13:30:46Z

JamieB-gu
Apr 6, 2020
Collaborator

That's a really interesting idea, I like it! I think we'd have to try it out with a few components to know whether it works for us.

Is the advantage that it has over className that it limits the extent to which consumers can reach in and change parts of the component?

I'm not sure I understand the difference between cssOverrides and className. Do the cssOverrides styles get applied inline?

0 replies

SiAdcock · 2020-04-07T14:01:22Z

SiAdcock
Apr 7, 2020
Collaborator Author

That's a really interesting idea, I like it! I think we'd have to try it out with a few components to know whether it works for us.

🎉 Thanks! Agreed. Let me know if you can think of any use cases for this.

Is the advantage that it has over className that it limits the extent to which consumers can reach in and change parts of the component?

No. If anything className limits what parts can be styled because the className only gets applied to one element. For instance, with <TextInput>, the className is passed to the <input> element, so it's not possible to use className to override the <label> styles.

I'm not sure I understand the difference between cssOverrides and className.

With cssOverrides the styles are managed by @emotion/core, whereas with className they are managed by whatever you're using to generate the className. Let me know if you'd like to go over this in more detail.

0 replies

JamieB-gu · 2020-04-08T08:15:43Z

JamieB-gu
Apr 8, 2020
Collaborator

so it's not possible to use className to override the <label> styles.

What about:

label {
  font-size: 8px;
}

the styles are managed by @emotion/core

I'm not sure I understand the mechanics of this, but probably best for us to discuss separate from this issue.

0 replies

SiAdcock · 2020-04-08T08:49:49Z

SiAdcock
Apr 8, 2020
Collaborator Author

Sadly not, since the TextInput JSX looks like this (simplified):

<label>
  <input type="text" className={className} />
</label>

@emotion/core takes the styles you define as template literals, serialises them and generates CSS. It targets the CSS at an auto-generated class that it assigns to the appropriate element. Then in the DOM, it adds the CSS to a style tag and adds that style tag to the bottom of the head.

In most cases, we're composing a list of serialised styles and passing it to a component. @emotion/core smooshes the serialised styles together into a single block of CSS. The styles are smooshed based on the order in which they are passed, with later styles overriding earlier ones. cssOverrides are the last styles in the list so they override all other styles.

Allowing @emotion/core to manage all styling is preferred because it gives us better guarantees over the cascade. If we use @emotion/core to generate some styles and use className to manage others, we can't guarantee the order in which style properties appear in the head, so we have to use !important in our override styles.

I might not be explaining clearly, and some of these details are not 100% clear to me either, so I'll be happy to discuss further if you wanna hangout

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC: customising the style of Source components #306

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 4 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

RFC: customising the style of Source components #306

Uh oh!

Uh oh!

SiAdcock Apr 3, 2020 Collaborator

Theming

cssOverrides

className

Request for comments

Replies: 4 comments

Uh oh!

JamieB-gu Apr 6, 2020 Collaborator

Uh oh!

SiAdcock Apr 7, 2020 Collaborator Author

Uh oh!

Uh oh!

JamieB-gu Apr 8, 2020 Collaborator

Uh oh!

SiAdcock Apr 8, 2020 Collaborator Author

SiAdcock
Apr 3, 2020
Collaborator

JamieB-gu
Apr 6, 2020
Collaborator

SiAdcock
Apr 7, 2020
Collaborator Author

JamieB-gu
Apr 8, 2020
Collaborator

SiAdcock
Apr 8, 2020
Collaborator Author