Theming and applying tokens

[mejiaj]

Curious to see approaches and hear thoughts on shared styles across web components.

Problem

We want to set global theme styles, such as colors, spacing, and font tokens.

Example

// USA Link
a {
  color: var(--theme-link-color, #005ea2);
}

a:visited {
  color: var(--theme-link-visited-color, #54278f);
}

And re-use that theme link color in another component, such as banner.

// USA Banner
.usa-banner__action {
  color: var(--theme-link-color);
}

.usa-banner__action:visited {
  color: var(--theme-link-visited-color);
}

The lit recommendation

Creating a module that exports tagged styles.

// colors.css.js

import { css } from "lit";

export const Colors = css`
  :host {
    --usa-base-lightest: #f0f0f0;

    --theme-link-color: #005ea2;
    --theme-link-visited-color: #54278f;
  }
`;

Source: https://lit.dev/docs/components/styles/#sharing-styles

The problem here is that the variables can't be attached to :root and instead go to the component (:host). This could lead to redundant/duplicate code. As well as making it difficult to theme because it'll be hard to sift through all the other variables. There's no clear hierarchy from semantic i.e. "primary color" to component token i.e. "banner background color".

Alternatives

One possible alternative is creating a CSS file that has global tokens attached to :root and using that in components.

// core.css
:root {
  --usa-base-lightest: #f0f0f0;
  … 
  --theme-link-color: #005ea2;
}

// usa-banner.css.js
:host {
  --theme-banner-background-color: var(--usa-base-lightest, lightGray);
  --theme-banner-font-family: var(--usa-font-ui, "a fallback stack");
  --theme-banner-link-color: var(--theme-link-color, blue);
}

This approach allows us to set a token hierarchy, re-use tokens, and users a familiar way to use tokens.

Possible downsides

A possible downside is it's now a new dependency. It's not a "recommended" lit approach. CSS props are mentioned, but variables are attached to :host ¹

---

Questions to answer

1. Is there a "best" approach and why?
2. How are other teams handling theming from a global and component level?
3. Are there any other alternatives?

Footnotes

1. https://lit.dev/docs/components/styles/#customprops ↩

[mahoneycm]

Thanks for outlining this @mejiaj ! Maybe a good thing to check for the styles section of our landscape analysis. I'm curious what approaches other Design Systems are taking for CSS structure.

[sorvell]

It's not a "recommended" lit approach.

I think this is a misunderstanding. What you describe is generally a recommended approach, but the options and details can vary a lot based on the amount of customization that you want to support. Here are some examples to consider:

1. The use of system and component level tokens in Material Web.
2. The use of both custom properties and CSS parts in Shoelace.

This is probably obvious, but custom properties provide targeted, property level customization whereas CSS parts allow users to customize any properties for a given, otherwise not selectable, element.

Given that it looks like you do want to support at least theme and component levels, consider a setup like this using a conceptually private property:

:host {
  --_usa-banner-background-color: var(--usa-banner-background-color, var(--usa-base-lightest));
}

.banner {
  background-color: var(--_usa-banner-background-color);
}

This way the user can customize the base-lightest color presumably used in a bunch of components or just the banner-background-color used here. The use of a "private" property ensures you can freely use the property inside the element as needed and allow the user to customize it as you see fit.

Providing the default value here can be done a few ways, but I would suggest not baking in hardcoded values into each element as your example shows. This is bloated and hard to maintain. Instead, consider defining properties with initial-value via @property, requiring users to load a "theme" to use the elements, or injecting the base "theme" sheet yourself using @layer so a user's values take precedence.

[mejiaj]

Thanks @sorvell, the approach with private properties you mentioned is one of a few we looked at. The @property rule recently got baseline support so will have to revisit.