Theming and tokens

[gfellerph]

A couple of issues came up that could potentially be solved by introducing design tokens, sub-atomic particles in the Atomic Design methodology.

Issues

Theming

Interest in custom theming for Post related projects with slightly different styling is starting to build. At the moment, theming possibilities are not documented and only partially implemented by overriding sass variables at build time:

@use "@swisspost/design-system-styles" with "$yellow: blue";

The following scenarios could be handled by themes:

• Slightly changing the post style to create a sub-brand style
• Delivering components targeted for internal/applicatorical usage
• White labelling or heavily altering the default post styling to make components usable across differently branded applications

Dark mode

Similar to theming, a dark mode is not available for most patterns. While some patterns work on a dark background, documentation and support is lacking for most parts. As the mobile app is already implementing a dark mode, interest for a dark mode on the web is there as well.

An initial idea with utility classes for background colours has shown potential but could be improved further. The following snippet will render a white button with black text colour on a dark grey background. The light mode primary button would be dark grey with white text colour. The button is using CSS Custom Variables internally and .bg-primary is overriding the used variables.

<div class="p-4 bg-primary">
  <button class="btn btn-primary">Next</button>
</div>

Composed web components

It's hard to style slotted components. This would be useful for some of the more re-useable components like <post-button> or <post-link>.

<post-menu>
  <post-button>Copy</post-button>
  <post-button>Paste</post-button>
</post-menu>

Inside <post-menu>, any defined parts of the <post-button> cannot be accessed because the button belongs to the light-dom (https://stackoverflow.com/questions/65540853/how-to-style-slotted-parts-from-the-parent-downwards).

::slotted(post-button::part(button)) {
  background-color: white; // Does not work, because buttons belong to the parent document and not the menu
}

Principles

There are some principles that help with finding the best way to solve the issues above.

• Principle of least power: Choose the least powerful language to solve the problem (if CSS can do it, don't do it with JS), https://www.htmhell.dev/adventcalendar/2023/2/
• Keeping components "dumb" by not making any assumptions on the context they are going to be used in. Exposing CSS variables serves the same purpose as exposing props. A pre-defined interface to change the way a component looks or behaves while reducing the risk of breaking the functionality.
• Build with the platform: using standards ensures best possible future proofing and decreases maintenance

Tooling

Layering

Many different tools and methods are available for working with design tokens. Research shows, a three layered approach, also promoted by Brad Frost (Creating and maintaining successful Design Systems, Smashing Course), seems to be the most popular one:

• Primary layer (reference): definition of all available tokens, raw values, e.g. --post-yellow: #fc0;
• Secondary layer (systemic/semantic): adds semantic meaning, aliases for primary layer, e.g. --post-primary: var(--post-gray-80);
• Tertiary layer (component): specifies component level aliases to the second and sometimes primary layer, e.g. --post-button-background: var(--post-primary);

Implementations

There are different approaches to bring the token layers into a project. This list contains a few examples and could be expanded by more research.

Build time theming

This approach loads a theming layer at build time. The resulting CSS is static but only contains the necessary tokens for the current theme. Changing the theme at runtime would require some custom JS or a page refresh.

@use "design-system/core"; // Basic component styles
@use "design-system/themes/default"; // Variable definitions only

Theming via media query

This approach is specifically useful for light/dark themes, also for loading special print or tv styles. It's a great declarative way for theming and respects user preferences automatically. It would only load the necessary variables and can be changed at runtime by updating the operating system preferences. A theme switch on the page however, would be difficult to implement.

<head>
  <link rel="stylesheet" href="design-system/core.css" />
  <link rel="stylesheet" href="design-system/themes/dark.css" media="(prefers-color-scheme: dark)" />
  <link rel="stylesheet" href="design-system/themes/light.css" media="(prefers-color-scheme: light)" />
  <link rel="stylesheet" href="design-system/themes/light.css" media="print" />
</head>

All in one

This approach is very flexible, as it allows to easily change theming at runtime and also combine different themes on the same page by scoping themes to certain elements. It needs to load all variables for all themes initially. Increasing number of tokens and themes could add up quickly and increase initial loading times.

<head>
  <link rel="stylesheet" href="design-system/core.css" />
</head>
<body class="theme-light">
  <h1>I'm in a light theme</h1>
  <div class="theme-dark">
    <p>But I'm in a dark theme</p>
  </div>
</body>

Maybe the future?

Just a speculation, but maybe something like this will be available one day.

.theme-light {
  @import "design-system/light.css";
}

.theme-dark {
  @import "design-system/dark.css";
}

Possible solutions

What's necessary for such approaches to work in the Swiss Post Design System?

CSS custom properties

The first requirement would be strict component layer token implementation for components. This requirement is specifically not tied to the other layers or even integration with third party tools like Style Dictionary or Figma variables.

This example shows component styles for a tooltip web component. The component itself does not care how it actually looks. The only thing it cares about is that it displays and functions in a correct way and that semantics and accessibility (except for appearance related rules) are respected.

Available customisation options can easily be documented along with props, methods and events in storybook. Functionality of the component can be ensured by carefully selecting available options.

tooltip.component.css

:host {
  // List of all component variables, scoped inside the shadow dom. Component level variables are defined in a theme outside the component
  // Format [-][namespace][component][property]: [namespace][component][property], [fallback]
  // [-] used to create a local variant of the global component level variable
  // [fallback] used if the global component level variable is not defined
  ---post-tooltip-background-color: var(--post-tooltip-background-color, rgb(60,60,60));
  ---post-tooltip-color: var(--post-tooltip-background-color, #fff);
  ---post-tooltip-font-size: var(--post-tooltip-font-size, inherit);
  ---post-tooltip-padding: var(--post-tooltip-padding, 1em 0.75em);
}

.tooltip {
  position: absolute; // Cannot be configured because it's integral to the functionality of the component
  background-color: var(---post-tooltip-background-color);
  color: var(---post-tooltip-background-color);
  font-size: var(---post-tooltip-font-size);
  padding: var(---post-tooltip-padding);
}

Performance considerations: https://lisilinhart.info/posts/css-variables-performance

A theme file overrides the component defaults (or leaves them as is) and can be very flexible in the definition of variables.

theme.css

// Primary layer
--post-gray-80: rgb(60,60,60);

// Secondary layer
--post-primary: var(--post-gray-80);

// Component layer
--post-tooltip-background-color: var(--post-primary);
--post-tooltip-color: var(--post-color-white);

// Theme files could be very flexible
@media (max-width: 1440px) {
  --post-tooltip-font-size: var(--post-font-size-20);
}

// Theme files could be used to style based on other conditions
.theme-dark {
  --post-tooltip-background-color: var(--post-color-white);
  --post-tooltip-color: var(--post-primary);
}

post-tooltip:has(.error) {
  --post-tooltip-background-color: red;
 --post-tooltip-color: white;
}

CSS Custom properties + utility classes

Taking it a step further, utility classes could be used to simplify customisation. An example would be the currently implemented background colour classes.

The background utility class defines accessible colour combinations that can be flexibly used throughout the document.
background-class.css

:root {
  --post-background: color.$white;
  --post-contrast-color:  functions.get-contrast-color(color.$white);
}

.bg-primary {
  --post-background: color.$primary;
  --post-contrast-color: functions.get-contrast-color(color.$primary);
}

Component styles can expect these utility variables to be around and implement support
tooltip.component.css

:host {
  ---post-tooltip-background-color: var(--post-tooltip-background-color, var(--post-background, rgb(60,60,60)));
  ---post-tooltip-color: var(--post-tooltip-color, var(--post-contrast-color, white));
}

index.html

<body>
  <post-tooltip class="bg-primary">Oh look, a primary tooltip</post-tooltip>
</body>

Examples from other Design Systems

Adobe spectrum and salesforce lightning use a different namespace for theming.

• Salesforce button color: color: var(--slds-c-button-text-color, var(--sds-c-button-text-color, #0176d3));
• Spectrum avatar border radius: border-radius: var(--mod-avatar-border-radius, var(--spectrum-avatar-border-radius));

Examples of excessive token definitions

• Carbon button height tokens

   --cds-layout-size-height-xs: 1.5rem;
   --cds-layout-size-height-sm: 2rem;
   --cds-layout-size-height-md: 2.5rem;
   --cds-layout-size-height-lg: 3rem;
   --cds-layout-size-height-xl: 4rem;
   --cds-layout-size-height-2xl: 5rem;
   --cds-layout-size-height-min: 0px;
   --cds-layout-size-height-max: 999999999px;
  
   :host {
      --cds-layout-size-height-local: clamp(var(--cds-layout-size-height-min), var(--cds-layout-size-height, var(--cds-layout-size-height-lg)), var(--cds-layout-size-height-max));
   }

Styling slotted components

Using CSS Custom Properties allows for styling slotted components, something that is otherwise quite hard (without injecting styles through JavaScript).

In this example, the <post-menu> is able to set variables that can be used to style the buttons slotted inside, even if the buttons belong to the document and not the menu shadow dom (codepen example for styling slotted components).

<post-menu>
  <post-button>Copy</post-button>
  <post-button>Paste</post-button>
</post-menu>

The menu has access to slotted components through the ::slotted selector. That selector does not allow to style elements inside the <post-button> component. If the button implements variables, it's possible to set variables from the menu.

post-menu.component.css

:host {
  --post-button-background-color: white;
  --post-button-color: black;
}

[alizedebray]

A good example is the accordion component which:

• should be white when placed on a light or gray background,
• should be gray when placed on any other background.

There, not only the background color should change but the whole theme (for example, the text on a dark background is white, but the text in a gray accordion on a dark background is black).

To implement this behavior I simply used CSS custom properties like so:

// Component layer
.accordion {
    --post-bg: $gray;
    background-color: var(--post-bg); 
}

// Theme
.bg-gray .accordion {
    --post-bg: $white; 
}

This approach work find for the styles package, but the variable declared in .bg-light .accordion has no impact on the web component.

To me, there are then three solutions:

1. Leave the responsibility to users to apply the theme on their own,
2. Declare the variable again in the component styles using the .bg-light post-accordion selector (this is what I did in this PR),
3. Create a CSS custom property specific to the accordion:

// Component layer
.accordion {
    --post-accordion-bg: $gray;
    background-color: var(--post**-accordion**-bg); 
}

// Theme
.bg-gray {
    --post-accordion-bg: $white; 
}

The first approach is not that nice for the development journey and leads to potential errors.
The second approach leads to duplicated code thus maintenance becomes complicated.
The third approach implies declaring a whole lot of CSS custom properties for each component on each background and thus increase the CSS output.

@gfellerph Do you think of another approach?

[gfellerph]

In the long run, I think it will be beneficial to have customisable components through CSS variables. I'm assuming the accordion defines it's background-color something like this (as it would be after implementing the above solution).

.accordion {
  background-color: var(--post-accordion-background-color, var(--post-background-color, color.$grey));
}

My first thought was that project devs should specify this in the form of .bg-[color] classes. This keeps the component "dumb" because it does not make any assumptions about the context it's in and gives full control to the project dev. Maybe someone needs a green accordion on white background, it's impossible to predict all edge cases.

<!-- Grey, because that's the default accordion background color -->
<post-accordion>...</post-accordion>

<div class="p-4 bg-light">
  <!-- Dev needs to add bg-white on this background, according to design -->
  <post-accordion class="bg-white">...</post-accordion>
</div>

For Post projects, the theming file could then contain exceptions like this specifically for the accordion - or potentially for other components as necessary.

theming/post.css

.bg-light {
  --post-accordion-background-color: color.$white;
  --post-accordion-color: color.$black;
}

The contextual definition is not made inside the component, but inside the theming file. The accordion just knows that somebody can define it's background colour and text colour and does not care who that is or if they define it correctly.

In the theming file, we can make devs life easier and handle the special case of the white accordion.