Refactor palette and component styles

[oliverschuerch]

Our design system implements palette styles in a custom way. While the current implementation works fine for the current palettes, it's very difficult to enhance or expand the technique for other elements.

We just discovered a new technique how to implement these styles, with an approach very similar to what the native light-dark() function would do. Which by the way does not yet supported all browsers we need to.

To show how it works, we've created a codepen: https://codepen.io/oliverschuerch/pen/QwWBjxZ

Quick explanation:
We define two different custom-properties which are used to define the current color-scheme, --light-mode and --dark-mode.
One of them is holding the value initial, the other is set to an empty string. Both will be used to create some kind of OR statment.
Because whichever variable is set to initial will cause the associated fallback value to be applied, while the variable set to ; is considered to be "defined", but it only adds a whitespace to the final value.

Example:

:root {
  --light-mode: initial;
  --dark-mode: ;
  
  --btn-light-bg: black;
  --btn-dark-bg: white;
}

.btn {
  /*
  Since --light-mode is set to `initial`, which is similar to "undefined" here, the first `var()` statement will use its fallback value.
  The second `var()` statement will just produce a empty string `''`, because that's what `--dark-mode` is set to. Its fallback value will not be used at all.
  */
  background-color: var(--light-mode, var(--btn-light-bg)) var(--dark-mode, var(--btn-dark-bg));
}

This would meen, we need to implement all of our component tokens the way showed above, which can be done easily, by adapting the output of the existing tokens.get() SCSS function.

The example shows also, how we can redefine --light-mode and --dark-mode for specific selectors like the .palette-default, .palette-accent or something totally independent like .banner.

[gfellerph]

Implementing this has the potential to abstract the logic into a scss function and once light-dark is available, we can just switch the functions inner logic.

/* While light-dark is not supported */
function light-dark($light, $dark) {
  @return var(--post-light-mode, #{$light}) var(--post-dark-mode, #{$dark});
}

@mixin mode($mode: light) {
  @if ($mode == light) {
    --light-mode: initial;
    --dark-mode: ;
  } @else {
    --light-mode: ;
    --dark-mode: initial;
  }
}

/* When light dark is supported */
function light-dark($light, $dark) {
  @return light-dark(#{$light}, #{$dark});
}

@mixin mode($mode: light) {
  color-scheme: $mode;
}

[alizedebray]

This implies using the custom light-dark() function in the component styles like so:

@use './functions' as fn;

.component {
  color: fn.light-dark(var(--component-token-light), var(--component-token-dark));
}

But we would need to refactor the styles anyways as in the future the native light-dark() function will most probably be used in the component token definition itself:

:root {
  --core-token-1: value1;
  --core-token-2: value2;
  --component-token: light-dark(var(--core-token-1), var(--core-token-2));
}

.component {
  color: var(--component-token);
}

This is to avoid polluting the root with duplicate tokens:

:root {
  --core-token-1: value1;
  --core-token-2: value2;
  --component-token-light: var(--core-token-1);
  --component-token-dark: var(--core-token-2);
}

.component {
  color: light-dark(var(--component-token-light), var(--component-token-dark));
}

[alizedebray]

This approach is interesting, however it does not solve the current issue.

The complexity does not lie within the fact that the light-dark() function cannot be used, it is that the color-scheme cannot be set via a simple token.

This forces us to resolve the token value in advance by parsing the palette tokens in a very specific way.

It is also the case on this proposed approach: it is still needed to pass the argument to the mode mixin as a string: 'light' or 'dark'.

Therefore, expanding the solution to other backgrounds or containers will necessitate exactly the same changes as with the current solution.

Hope that clarifies

[oliverschuerch]

The current state of the POC shows, that we can resolve the color-scheme through simple tokens, which makes it clearly a different solution than the current implementation.
To do so, we need to generate two custom output files for scheme tokens, but we do not need to resolve their tokens during build time and I'd expect we also do not need a special tokens config to output them. The only important thing is, that these tokens are defined in a separate scss-map, so we know exactly how to handle them.

The first of these files (e.g. root-scheme.scss) will contain the different scheme variations, which rely on the root-scheme.
They will be static and never ever change again, because there are no more possible variations as long as we only have scheme light and dark.

• aligned (light-on-light, dark-on-dark)
• swapped (dark-on-light, light-on-dark)
• static-light (light-on-light, light-on-dark)
• static-dark (dark-on-light, dark-on-dark)

The second file (e.g. root-component-scheme.scss) will contain scheme related tokens for components, which only rely on the root-scheme.

• palette colors
• banner colors
• ...

The third file, which already exists (scheme.scss), will contain all the scheme related tokens, which rely on the --scheme-{mode} tokens.
Since the --scheme-{mode} variables can be changed by a component containing the class .post-scheme-component, all these scheme tokens need to react and change their values based on the current scheme.

• card colors
  Yes, because they must react to a wrapping palette. And btw, it's not necessary to lead their scheme tokens through the palette tokens. Have a look at the POC.
  On the other side, it is still possible, that cards can define their own (inner) scheme, which is then used by their children.
• btn colors
• accordion colors
• ...

Why do we need these three files?
Because we need to output different selectors and/or use a different scheme to define them.

Thanks to the class .post-scheme-component it is not even necessary anymore to generate any selector. Just use the once defined in the POC, output the related tokens to it and you're done.
This means, we could make an existing component work like palettes or like cards within minutes.

I've tested even further and it is possible to let all but one variants of a component act like palettes (which only relys on the root-scheme), while the other variant of the same component act like cards (which relys on the color-scheme of the wrapping component).

[gfellerph]

Web component POC: https://codepen.io/tuelsch/pen/dPyqGgd?editors=1100

[gfellerph]

Conclusions

• Remove the build step that is resolving tokens to core value and rely on client side resolution for switching colour schemes
• Use @supports to detect support for light-dark and use it wherever it's supported to define the scheme layer tokens
• Try to make the migration to light-dark in the future as easy as possible. Flagging and dating code that can be removed in the future, for example.
• Solution should be easy to maintain and flexible to extend (listing all the selectors for scheme-changing components might be necessary if we don't use web components)
• Prevent usage of web components as much as possible to ensure SRR compatibility and prevent FOUC
• Check if we can add a style dictionary plugin that adds necessary tokens for the space toggle fallback for light-dark without the need to add additional tokens to tokens studio

Currently discussed solutions

• Adding new palette semantic layer
• Light-dark polyfill with space toggles
• Token resolution on build time (current solution)
• Web component <post-palette>

[alizedebray]

POC mixing multiple of the solutions, that meets all above criteria: https://codepen.io/alizedebray/pen/QwWVXzm?editors=1100

[oliverschuerch]

What is fullfilled at the time being in the Tokens and CSS only POC: https://codepen.io/oliverschuerch/pen/QwWBjxZ

• Remove the build step that is resolving tokens to core value and rely on client side resolution for switching colour schemes ✅
• Use @supports to detect support for light-dark and use it wherever it's supported to define the scheme layer tokens ✅ (should be possible to change everything so we use light-dark() and use the POC to implement a fallback)
• Try to make the migration to light-dark in the future as easy as possible. Flagging and dating code that can be removed in the future, for example. ✅
• Solution should be easy to maintain and flexible to extend (listing all the selectors for scheme-changing components might be necessary if we don't use web components) ✅ (no JS needed)
• Prevent usage of web components as much as possible to ensure SRR compatibility and prevent FOUC ✅
• Check if we can add a style dictionary plugin that adds necessary tokens for the space toggle fallback for light-dark without the need to add additional tokens to tokens studio ✅ (it should be possible to generate everything we need for the fallback)

[alizedebray]

Final solution proposal: https://codepen.io/alizedebray/pen/GgRPwNe?editors=1100