Web Components – Styling

[ashleynolan]

This is to start discussions over how we at JET want to handle styling as we build out a web component library.

To note down some of my own thoughts/opinions on the subject to start things off and maybe provoke some discussion on the subject;

Dynamic Styling (and CSS Variables)

I feel like this is probably the least controversial decision – Web Component Styles should use CSS variables (custom properties) – specifically from our PIE design tokens. This will enable us to change component definitions across components, without recompiling (for example, colours – and light/dark theming – common settings such as border definitions, spacing, typography definitions.

This is backed up by the Lit docs, which recommend using CSS Variables for this kind of theming

The other area of dynamic styling that would be good to discuss is how we handle styles when props are defined. Lit doesn't give any hard and fast rules on this, but does provide the classMap and styleMap directives to help in this area. I would probably rather use something like classMap to add/remove classes dynamically over direct styling, but would be good to hear thoughts on if there are pros/cons to either approach potentially.

Tooling / Processors

We have had some initial chats about whether we should (or need) to use a CSS Pre (or Post) processor, such as Sass (SCSS) or PostCSS.

My initial thoughts are it would likely be useful to have access to a tool that can provide common mixins/functions that we can use across our components, but I'm interested to hear what others feel on this subject.

The processing tool shouldn't affect consuming applications, as our current assumption is that the the styles will be compiled as part of the component release (so consuming applications will just need to consume the resulting CSS).

Styling Separation

There's been some brief discussion around if (or how much) of the components styles we would want to pull out of the web components to reduce duplication across components.

My initial thoughts are that it would be useful to be able to share common utility classes, mixins and functions at the lease across our web components.

In the past we have also set some styling definitions for consuming applications at a more global scope – for example, setting defaults for h1/h2/h3, normalisation/reset styles etc. If we want to do something similar for our web component library, these would likely need to live in a separate CSS package similar to how we share styles like this in something like fozzie (pie-css/pie-styles?)

The Lit docs mention CSS inheritance briefly, from the point of view of using it in the above way (for setting global selector definitions that components will then inherit)

We've also mentioned whether we should pull out the styling for our components so that consuming applications could potentially just consume the CSS for a component (for example, button styles) and not need to pull in the entire web component. I think this probably needs a bit more thought as to the pros/cons, but again would be good to hear other peoples thoughts on this.

The Lit documentation shares some opinions on sharing styles between components, mainly by defining styling modules in JS that are passed into components. Styles can also be defined and inherited through Class based inheritance and superclasses.

Other stuff

If anyone has any other topics/areas that they think we should be discussing to do with web components styling, please add them into the thread – would like for this discussion to be a source of truth for our discussions on this topic as we look to make engineering choices around styling.

I'm also looking to setup a call with the Lit team shortly too so we can discuss this topic with them too (incase they have any recommendations) – looking at their docs they suggest a few approaches, but no real guidelines on things like tooling.

N.b. One thing that the Lit team do advise against is importing external stylesheets into a component using link tags.

Feedback

It would be great to get engineers views on these topics – I'll likely arrange a F2F once we've got initial thoughts down in this discussion so we can look at actions that may come out of these discussions (potential spikes or just to finalise any decisions/conclusions we come to)

[jamieomaguire]

Thanks for putting this together @ashleynolan, I'll add some initial thoughts too and may add some additional points in the near future.

Dynamic Styling (and CSS Variables)

I fully agree that we should use CSS variables. I think the benefits these provide us for theming (light/dark etc) as well as any needed runtime style updates are a huge benefit.

Tooling / Processors

Although I am a big fan of using SCSS, I am open to alternatives here. I personally do not like CSS-in-JS and would prefer we avoid it, however I appreciate it's a rather popular approach in the industry and in some parts of our organisation. I think as long as the result compiles down to CSS that is bundled with the web component, and it doesn't impact consumers, I am happy.

Styling Separation

This is where I am perhaps most opinionated. To be direct, I still strongly favour separating our styles from our web components library. I have a few reasons for this which I will outline, however the crux of my point is that I think Web Components are just an implementation of our design system:

1. Whilst we aim for Web Components to be universally compatible with all JET applications and websites, I don't think this means we won't have use for another component library down the line. Even in perhaps 2-5 years I think it's reasonable to assume we may end up with extra libraries or different implementations of our PIE components. Having to copy styles over from one component library to another is messy, and leads to more duplication (which we are trying to remove in the first place).

2. Web components are a single implementation of our Design system, and if there could ever be a situation where we cannot use Web Components (albeit this could be unlikely), I believe it is the responsibility of the design system team to provide an alternate means of implementing our component styles. Therefore if a consumer, for whatever reason, cannot use web components then we can still control how the styling is implemented.

3. Some design systems, such as Carbon, will implement the design system components as their own consumable stylesheets or SCSS files. Then the consuming applications can pick and choose which ones they want to import to the project. An example, the Carbon React implementation simply forwards the core styling library. This appears to be how the vue implementation works as well (community maintained)

4. Regardless of separating component styles from web components, we will absolutely want a style library for common and core styles. Redefining spacing, typography, colours, animations and utility styles would be a huge effort. We have had great success on the L-JE side using the Fozzie SCSS library to store common bits of reusable styling.

That's all I have for now, cheers!

[fernandofranca]

Dynamic Styling (and CSS Variables)

I believe using classMap over styleMap is the best option, as styles are too verbose and don't favor reuse as classes.

My only concern with CSS variables is the degree of flexibility it brings, potentially leading to misuse and visual inconsistency.

[thejfreitas]

I think both can be used for specific use cases. classMap can render different classes shaping specific styles but not too dynamic in the other hand styleMap can be used to give the user more liberty to change attributes such as width, height, etc...

I agree with you, leverage high degree of flexibility leads to misuse and visual inconsistency. I think we can take advantage of both approaches also limiting how flexible the component can be.

Look at the sample below.

  get styles() {
    return css`
      margin: ${unsafeCSS(this.margin)};
      width: ${unsafeCSS(this.fullWidth ? '100%' : 'inherit')}; // user can use rem, px or whatever width as they need.
    `;
  }

  override render() {
    const variant = getOptionClass(this.variant);
    const size = getOptionClass(this.size);

    const classes = {
      'base-button': true,
      disabled: this.disabled, // Classes for specific designs
      ...variant,
      ...size,
    };

    return html`
      <button
        class=${classMap(classes)}
        part="pie-button"
        style=${this.styles}
        type=${this.type}
        disabled=${this.disabled}
      >
        ${this.isLoading ? html` Loading... ` : html` <slot></slot> `}
      </button>
    `;
  }

[xander-marjoram]

Apologies if I'm misunderstanding your example, @thejfreitas, but I think using both styleMap and classMap at the same time has the potential to be quite unclear.

How flexible do we want the components to be? I think that components should only be used in the ways that are specified by designs, and if there is a particular design requirement for flexibility then it should be built into the classes we write. Because of this, I believe we should use classMap over styleMap in the vast majority of scenarios.

[fernandofranca]

@thejfreitas styleMap can be convenient for tackling edge cases. For most cases in Design System context, classMap fits better as @xander-marjoram described.

[davidpn11]

My two cents on this discussion,

First is good to note that aligning styling for a global library is HARD. Is gonna be quite a challenge to find the perfect solution that fits the whole organization, especially since we are already implementing our libraries using such different methodologies. There is also the fact that we want to tackle problems such as the ones mentioned above - reduce styling duplication (problem 1) but also make sure that we can still use the same styling for the next iterations of the Design System (problem 2). Let me try to break down the problems the best I can, so it can be easier to discuss specific points.

Foundation tokens

I think is a no-brainer that foundations tokens should be consumed using CSS variables. Those fit extremely well on the modern web:

• They are easy to consume and instantiate
• Extremely performant when switching CSS properties values, something we do basically to all components when we switch between light and dark themes
• Fits really well on some edge cases such as micro frontends. As the CSS variables exist in a global context, all the sub-apps rendered on a micro-frontend application can access it, meaning we only have to instantiate once. This is important as Skip and Takeaway heavily rely on micro-frontends

Those also should be separate from the Component Library, for the reasoning that Jamie brought which is “Web Components (the component library) are just an implementation of our design system”.

Tooling

This is the most difficult topic, due to problems 1 and 2 mentioned above, and also some personal preference can be brought here. Being backed up by Lit’s docs, their go-to styling solution is using their own css property, which uses template strings, basically being a tiny CSS-in-JS framework. I like that for two main reasons:

• Allows us to create helper methods to consume foundations: That can be a huge win when building components, as those reusable functions can go really well when creating styling sheets:

const fortmWrapperStyle = css`
  /* Doing this */
  margin: ${getSpacing('s00', 's04')};
  
  /* instead of */
  margin: var(--spacing--0) var(--spacing-40);
`;

This is something we at Skip really like when using Styled Components. We have helpers for getColorAlias ,getSpacing , getFontSize, and more! They make not only building components easier but also using those helpers to consume the foundations tokens and build our pages with them. Also, those methods are can be typed which makes it MUCH better

• Allow better reusability of styling sheets: Not only you can create reusable stylesheets to use at components, but you can create reusable visual components to assemble the final component. One example of this is creating form components. Selects, TextAreas, and TextFields all share the same elements/styles, such as the label, the input box, the assistive text, etc. Creating reusable stylesheets and visual components would make it much easier to share those between components.

// Render for TextField, with reusable components (form-label and
// form-assistive-text) and reusable styling (form-box-style)

render(){
  return html`
    <div>
     <form-label></form-label> 
     <div style={form-box-style}>
      <input />
     </div>
    <form-assistive-text />
    </div>
  `;
}

I know this is not a valid Lit syntax, but hope you get the idea 😅. The hard part would be able to share those across a big chunk of our components. Lots of components share the same rules for creating label's, but we would have to identify those.

I am a big fan of CSS-in-JS as I think it would give us the best tooling. As much as Lit’s css doesn’t have the same power as full-blown libraries such as Styled Components, I’m happy with the fact that can help us with reusability and still provide us with some tooling to better consume the tokens.

[ashleynolan]

Think there are some really good points here.

Firstly, I agree with everything you said about CSS Variables. For me, the benefits that they bring – especially in terms of light/dark mode and micro-frontends inheritance – mean that there are fairly huge benefits. Completely understand @fernandofranca's point about potential misuse, but I think that if someone wants to override our styles they'd probably find a way no matter what we choose 😆

Around the tooling side of things, it would be useful to see what the helpers you mentioned do in each of those examples. Currently, we use similar helpers in SCSS (or PostCSS) – so we have font-size() functions that convert px to rems for instance (we have others for breakpoints/spacing).

I can see a future where PIE could potentially provide both a set of JS utilities (for CSS-in-JS styling) and SCSS/PostCSS utility mixins/functions – the thing to remember is that whatever we choose to use in the global components themselves doesn't need to be the same as what teams use within their own applications (or more localised component systems outside the scope of the global set). So if we decided to use either SCSS/PostCSS or CSS-in-JS, other teams could use the complete opposite if they wanted.

I think the main thing would be that we decide if (and what) we want to support, as we should maintain any helper/utility set-up for scenarios centrally as part of PIE (to avoid duplication). I'm keen for PIE to allow engineers to not dictate methodologies as much as possible – ultimately, we'll need to choose one or the other within the global components themselves, but as that will just be consumed as CSS by other teams, we should look to provide the tools/methodolgies that we think will be most popular across JET.

For the components themselves, I personally prefer keeping styles a bit more separate from the JS, using CSS classes to build up styling – but I'm open to hearing the pros/cons of both approaches and understanding if there are any reasons to use one approach over the other.

Just a couple of q's specifically about some of the points you mentioned above:

• The helper methods I think I addressed above, but would be good to compare the ones you have available in CSS-in-JS. As I say, I imagine they directly compare to what we use in SCSS/PostCSS but interested to find out a bit more.

• Where you mention above:

  Allow better reusability of styling sheets: Not only you can create reusable stylesheets to use at components, but you can create reusable visual components to assemble the final component.

  I'm guessing the reuability is only for others using a similar CSS-in-JS approach? If we wanted to share those styles with others, would that be an assumption/dependency?

[thejfreitas]

Thank you @ashleynolan to put this together.
Here's my two cents.

Dynamic Styling (and CSS Variables)

Like @jamieomaguire said I fully agree too.
Build a single source of truth such as foundation tokens will help us to reduce styling duplication.

Tooling / Processors

Like @davidpn11 said, that's a difficult topic.

Honestly I am not a big fan to CSS-in-JS however on my first contact with Lit I skew to rely more in this approach since the Lit documentation kinda recommend this approach in the other hand I really enjoy what SCSS/SASS can bring in terms of tooling and flexibility.

I believe we can get a lot of insights from the Lit team if/when we talk directly to them.

[xander-marjoram]

Dynamic Styling (and CSS Variables)

My opinions don't differ from everyone else's here. CSS variables seem like a great fit.

Tooling / Processors

Personally I think that writing CSS these days without a processor is just making your own life harder. Simple features like nesting and mixins make writing and maintaining styles so much easier.

I'm happy to reserve judgment on exact implementations until we've spoken to the Lit team to see what they suggest, but generally speaking I like the idea of having a step to compile SCSS which then gets brought into the component.

Styling Separation

I'm reasonably in favour of keeping styles alongside (but not within) their respective component. For example, modal-specific styles (e.g., the overlay, the positioning of the modal, etc) that aren't likely to be reused could live inside pie-modal, in a file which is imported into the web component.

If these styles are needed by an application that does not support web components then the styles could still be imported without needing to import the web component itself.

If the styles were totally separated from the component then I wonder how we would go about testing them. I would argue that in the hypothetical case of having several component libraries, one of them could be the source of truth (and testing) and the others could import the styles from there.

I am 100% in favour of having a shared module (or set of them) for shared styles and mixins for typography, spacing, and more.

[kevinrodrigues]

Dynamic Styling (and CSS Variables)

1. Regarding styleMap & ClassMap I do much prefer the latter as it feels more organised & concise. I also think it just feels a little cleaner using classes over inline styles in general.

2. Happy with the css variable (i.e custom properties) approach.

Tooling / Processors

I've not looked at solutions for this but i do feel writing standard css as opposed to using a preprocessor is a little harder it would be nice to use a tool that allows nesting and all the other benefits preprocessors bring to writing css. I don't think this is necessarily a massive problem though.

Styling Separation

IMO It would be nice to try and separate out the styling requirements for a component as much as we can so they can be extracted out if required. I quite like the LIT approach of using superclasses to import (inherit) and use styles within the static array & also the module way via tagged styles (although i think the superclass way seems nicer). I think this way we you could define a superclass called "button" that contains styles for all elements that should be styled as buttons then use where required. There seems to be one catch with superclasses but it's covered in the docs when using typescript.