Context-aware tokens / utility classes

[janhassel]

Related: #4358 (comment), #2912, #4826, #5598, #5914

When using tiles / cards / containers to layout an interface, it quickly becomes challenging to apply the correct theming to all elements due to the overlaps in some color tokens. Having a container that uses ui-01 as its background requires all inputs inside to use props.light in order to switch their background color from field-01 to field-02. Support for props.light is not given for all components though. The DataTable for example does not offer this prop and can therefore not be correctly displayed within a ui-01 container.

One solution to this is to apply different themes to different zones. One could create a g10/ui-01 container and then emit the white theme to its content, effectively treating the inside of the container as it would be a page using white. This would correctly render all components without using props.light and therefore supports the DataTable. However, this solution can also become tricky when nesting more objects and adds a lot of duplicates to the code.

From a developer experience standpoint it would be great if the components just "knew" how to render properly and in which context they are. One approach could be to introduce utility classes (@joshblack I believe you were exploring this direction before) that would emit only the necessary updated color tokens for their content.

---

Example

An input component would no longer use field-01 as its background and have a light variant to switch to field-02 but it would rather rely on a context-aware token field. By default, field could be set to field-01.
To make a container, developers would use a utility class, let's call it cds-bg-ui. This class would set the container's background color to ui (also context-aware) and override relevant color tokens for its content.
In this example, we'd want to use field-02 for all inputs. Any nested container should then use ui-02 as their background and revert to field-01 for its inputs.

:root {
  --cds-ui-01: #ffffff;
  --cds-ui-02: #f4f4f4;
  --cds-field-01: #ffffff;
  --cds-field-02: #f4f4f4;

  --cds-ui: var(--cds-ui-01);
  --cds-field: var(--cds-field-01);
}

.cds-bg-ui {
  background-color: var(--cds-ui);
  
  --cds-field: var(--cds-field-02);
}

.cds-bg-ui .cds-bg-ui {
  --cds-ui: var(--cds-ui-02);
  --cds-field: var(--cds-field-01);
}

(Since there are only ui-01 and ui-02 that describe a container background in the color usage guidelines, I assume it's a design choice to not encourage more deeply nested levels)

A developer would then not need to care about where components are rendered and if they might need any additional props.

<div class="cds-bg-ui">
  <TextInput />

  <div class="cds-bg-ui">
    <TextInput />
  </div>
</div>

Quick codepen example applying above described behaviour: https://codepen.io/janhassel/pen/7f593afc5cac9c7e9f94f506850e54b1?editors=1100

---

I think an approach like this could vastly improve the developer experience and make sure colors are used as intended (avoid having field colors and background colors the same or wrong usage of zoned themes). I have to say that I didn't work a lot with css frameworks like tailwind and this idea of context-awareness might not fit into the "only-one-rule-and-nothing-more" mindset. It would definitely make the styling more opinionated, although that might be a good thing for a design system (to ensure correct usage).

Would love y'all's thoughts on this.

[joshblack]

@janhassel love this exploration!

Zones/inline themes are definitely an artifact of the Duo exploration days that we never were really able to tackle in v10. I think that, unfortunately, some designs may still use this idea of "themes in themes" and the resulting compromise was the light prop, as you noted, with the limitations described above.

Ultimately you're totally right, CSS Custom Properties in this space would be ideal. It would allow us to solve this cleanly and efficiently and would require no re-write of the components themselves. It would just work. The mechanism for this may end up just being theme classes, and for the developer that may end up looking like:

<Theme value="white">
  <PageSection />
  <Theme value="g10">
    <PageSection />
  </Theme>
  <PageSection />
</Theme>

Or more simply the following theme classes: bx--white, bx--g10, bx--g90, bx--g100 that would correctly define CSS Custom Properties for children components to inherit from.

Curious what you think of this @janhassel and if anything is missing based on the use-cases you described above.

[joshblack]

@janhassel totally get what you mean from the ergonomics perspective, I'm not sure what the component could be called but if we called it a generic Section component for now we could totally pull something off like:

<Section>
  <p>This renders in the white theme</p>
  <Section>
    <p>This renders in the g10 theme</p>
  </Section>
</Section>

With an optional prop to change the behavior from white to another theme, nested sections would know what theme to swap to based on the context that it is placed in.

---

As per the correct behavior, it'd be great if we could use inline themes but I just posted this message to design to see what they say real quick.

[joshblack]

@janhassel just wanted to circle back, seems like the right-hand side is the preferred solution here btw (theme in theme)

[aagonzales]

In the end, this brings up the question of which approach is the correct one. Should backgrounds always stack to a lighter color in dark themes as shown on the right or should one stick to what one theme provides?

The right side is the correct design intent. The color layering logic does work different between the light and dark themes.

[janhassel]

@joshblack Looking at the new token names @aagonzales shared, maybe <Layer> would be appropriate?
Though I'm wondering: would this be an intermediate solution until full support for CSS custom properties (aka v11) is released or would you prefer context-awareness with the help of explicit components over the use of utility classes?

@aagonzales Thanks for the clarification!

[joshblack]

@janhassel Layer is a tricky one since we also use it for shadows 😞 (or at least we used to). I kind of like Zone as a concept but not sure how inferrable it is 🤷‍♂️

For the release strategy, I definitely think we want this stuff enabled by default for Custom Properties but it would make sense to provide an interim step as you mentioned.

[aagonzales]

On a side note though: Using DataTables within containers with the proposed context-aware approach does not work out-of-the-box since ui-02 and ui-03 are the same color in the dark themes, meaning that all dividing lines would disappear from a DataTable.

We have actually been working on updating our design tokens for "v11." We initially were intending to build out a structure to better support the "light" variants in each theme and address some of these layering issues you have pointed out (we were calling that solution the "alt" tokens). BUT if we can implement this "inline theming" then we can rethink the new tokens with that in mind.

[janhassel]

Thanks a lot for sharing this link! I'd be very interested in the planning for future token usage and theming approaches and can probably spare a bit of time to try a few things out / explore some options. From my experience so far, color tokens and correct theming are points where I oftentimes see designers and developer struggle and I'd love to help ideate a better structure around them.

[aagonzales]

Yeah we'd love to hear any thoughts you have on them! I'm in the process of writing up an issue to explain the new proposal token set (not final yet still open to changes) and illustrate the logic. I'll share it with you when I'm done with that.

I've heard from several people how much designers and dev struggle with understanding the tokens which was a big push making them more user friendly the next round. They are still such a new concept and every company seems to do them slightly differently.

I think our theming structure and varying color logic also adds a layer of complexity to our tokens that make this a very interesting problem to work on. Also the fact that design tokens are harder to understand also makes it harder to get feedback on in general so again I'd love to hear anything you have thoughts on!

[jnm2377]

@janhassel not sure if you've seen this discussion #7743. It's related to the issue you bring up here, and @aagonzales proposes 2 solutions.

[janhassel]

Ah, thanks @jnm2377! Haven't been following the discussion going on over there. I'll follow up in the other thread 🙂