New color token layering models

[aagonzales]

Background

Layering color logic

The mental model of how backgrounds layer or stack differs between the light themes (White and Gray 10) and dark themes (Gray 90 and Gray 100).

• The light themes alternates between White and Gray10 when layering.
• The dark themes lighten with every layer Gray100 > Gray90 > Gray80.

Existing problems

No accounting for 3rd+ layer

The existing token structure doesn't account for the adding components onto this third layer.

In Carbon v10 we use a light prop to help with layering components on different ui colors. However, this solutions begins to fail in the dark themes once you get to the third layer The default variant use field-01 and the light variant use field-02

Token names aren't helpful enough in applying color

While our tokens help define what element a color should be applied to, the token name doesn't help much with understanding when or which token within a category to use.

Proposed solutions

• Proposal 1: Layering sets
  • Creating layer sets within each theme. Causes the token list to grow in number but each theme could stand on its own.
• Proposal 2: Inline theming
  • The infamous inline theming concept. Less tokens needed but themes will be dependent on each other and designs will almost always have the need to call an inline theme. See also context aware tokens

[aagonzales]

Proposal 1: Layering sets

This proposal expands on the concept of the "light" variant (adding a third color variant). It bakes the staking model into each of the 4 themes by creating a specific set of tokens to pair witth each layer and the elements that goes on it.

• Token list

How it works:

Layers

Layers are the main backgrounds and canvas areas that stack on top of one another. They are sequential and should always stack in order.

Example: $layer-01 > $layer-02 > $layer-03

Note: I'm only using G100 and G10 for examples but this would apply to all 4 themes

Sets

There are three "sets" of layer tokens. Each layer set has the exact same elements in it but will be assigned a different value according to its layer modal. The tokens are defined by a unique number to group the paired set together.

Example:

Set 1:

• layer-01
• field-01
• border-strong-01

Set 2:

• layer-02
• field-02
• border-strong-02

Using sets

Which number set you use is determined by which layer you are placing components on. If you are building on $layer-01 then you would use the other tokens associated with the-01 naming convention.

Once you've added a new layer to your layout, you would then begin using the next set of tokens.
For example: layer-01 > layer-02 > field-02

Concept example

Product example

---

Consequences:

• UI Shell theming would still need a custom solution as proposed here.
• There would be a third color variant to components in addition to default and 'light' (most likely renamed)

Questions:

• Instead of naming them layers should we call them backgrounds?
• Do all tokens need to fall in a set? A: I think not, I think some could still be universal, like buttons, interactive, icon, text.
• Would each set gets its own state colors (hover, active, selected)? A: probably

[aagonzales]

Proposal 2: Inline theming

Inline theming is the concept of calling one theme while within another theme. The themes are no longer standalone entities (after that first layer) but would need to work together to create a full experience.

• Token list

Note: How inline theming will be built is not defined in this issue (atm). See #7701 for potential solutions.

How it works

Each theme has a background and 1 layer. Any components placed directing on the background color uses the components from its own theme. Once you use a layer component (ie card, tile) the components that go on top of that layer would use an inline theme.

background and layer can be used interchangeably. It mostly depends if “layer” is built into a component. Here the fields on top of the layers are calling and inline theme. The second stacked tile would also be calling an inline theme to change its background.

Zones

The page is divided into "zones" and has a theme assigned to it.

Nested Zone

While some zones are easily sectioned from top to bottom of the page like in the above example, sometimes the zones are stacked on the z coordinated creating layering within a page section.

---

Consequences:

• This would eliminate the need for light variants.
• UI Shell could use the same color tokens as the rest of the components
• Depending on how we implement it we may need to develop the Gray80 theme for layering purposes with Gray90
• Inline theming would eliminate the need for complex layering to be solved with additional tokens like in Proposal 1 and would therefor reduce the number of supported tokens

Questions:

• What consequences would inline theming have on light/dark mode implementations?
• How much work will it take a product team to convert to inline theming. (Any previous instance of a light variant will need to be update).
  • Would we deprecate the light variants in v11`?

[tw15egan]

Another vote for Proposal 2. The only blocker from before was IE11 support, right? By using CSS custom properties it shouldn't be too difficult.

[kingtraceyj]

I'm also leaning towards inline theming. I know that many designers instinctively do this already even without the functionality. I think this concept can solve a couple of different issues and is more intuitive than the first concept. really great work anna!

[mariuszmickiewicz]

1. Would designers need to use three different libraries to design one screen (g100, g90, g80 example)?
2. I'm curious how option 2 will work with theme switching for the whole product?
3. background and layer can be used interchangeably. - Does this mean for the layer sitting above the background I can use layer from the same theme as the background or background from the "next" theme?

[aagonzales]

1. Yes with inline theming designers would need to pull from each of the various separate Sketch libraries.
2. That was one of my questions as well, I'm not sure how technically a light/dark mode would work with inline theming. Maybe a dev can talk to this point. @carbon-design-system/developers
3. The answer is basically either is allowed. Its mostly about where you're drawing your inline theme boundary. I think it also will depending is the layer is a part of a component or not. If it is part of a component then I think it needs to use layer not the next theme's background. They're visually the same thing. We can make some more clear guidance around this though.

[dianasanborn]

Same thought as Tracey above — I feel that some designers instinctively already do this, especially since not all components have light variants (like data table). This does start to change the mental model for how some teams approach the different Carbon themes (for example, within AI Apps we say to primarily design in the Gray 10 theme for consistency, so this now will open it up to now primarily use the two light themes), but that's just an adjustment we'd have to make/learn over time.

Proposal 2 allows for more flexibility, so I'm leaning this way too.

[joshblack]

Such a good write-up! Thanks for taking the time to put this together @aagonzales

My initial reaction is to go down the proposal 2 route, I think it has a couple of advantages for authoring components that are nice. The biggest of which is that a component does not need to be aware of what part of a layout it will be rendered in. It "just works".

In proposal 1, I think from the component authoring perspective it could get annoying to support your component potentially rendering in any of the three layers and authoring it to work that way. (Or at least based on how I understand it, let me know if I'm misunderstanding)

[aagonzales]

You've got the correct understanding of proposal 1. It would add a third rendering.

[tay1orjones]

Proposal 2 is how I naively expected the theming to work when I started using v10 😅 I was surprised to find that input backgrounds were not context aware on modals, etc.

I also think the redlines are much easier to understand. I imagine a developer receiving a layering set redline like the "Product example" you included and them scratching their head a bit initially. Meanwhile the zones example redline is clear as day when you understand the components inside to be context aware.

[aagonzales]

Backstory: Inline theming was actually the modal the new design language in v10 was original designed around which is also probably why you thought that. We just didn't have the technical support for it then which is why we had to build out all the light variants instead.

[tessarodes]

Proposal 2 fits my existing mental model perfectly.

[kaleycoffield5]

I like the inline theming, because this is the way I think about it when designing. Therefore it would be easier for me to continuing communicating to others (dev or design teams) in this way :)

Also for proposal 1, the term "backgrounds" does actually resonate with me more than the term "layers"

[yumeforever]

I'm probably the only one voting for Proposal 01, but let me explain why I think it's the better approach:

• If one of the goals is to make the tokens usage more understandable, I feel like the logic behind Proposal 01 is much more clear
• With Proposal 02 I can see people having to switch between at least 2 Sketch Kits constantly to create the pages, if not 3 if there is a third layer
• But the biggest pain point in my opinion is for automating Dark Mode: the idea is to use the Themes to switch between light and darl, using Gray 100 and Gray 10. How would it work? G90 areas goes to White? And Grey10 to Gray 100? Feel like an unnecessary hurdle to design and development when handing off specs and for the platforms to implement the globally.

[mariuszmickiewicz]

@joshblack I can see how option 2 is very attractive to the developers. In theory it sounds good to designers too, just the practical side of it seems to be a little tricky to me (for the reasons I mentioned above).

Some other things to consider:

• Gray90 is the least used theme — so maybe this is not a big issue — but essentially it will be eliminated as a stand-alone one and only will serve as a layer for gray100, if I perceive option 2 model correctly. In this case maybe we don't even need the full library of components, just the ones which need to react to their layer level.
• Same as above for the new gray80 (adding 5th, full library feels like an overkill).
• We would need a special plugin to be able to switch between the themes (right now Camilo is pretty good for that purpose but it won't be able to handle "logic" we want to have).
• Backward compatibility — this will be a bit tricky anyway, just by the fact that the tokens will change. In the code this can be handled better I guess.

[mariuszmickiewicz]

@joshblack
A question about option 2 and switching themes logic.
If you have mixed zones (let's say ui-shell and right panel are dark) — would you be able to exclude these zones from switching? You most likely won't want to have light ui-shell in the dark theme (if I'm reading your table correctly this would happen).

[aagonzales]

That's a good point @mariuszmickiewicz. Dark mode especially for Shell won't always be 1:1 switch. This will be a very common light/dark switch. Carbon is hoping to start testing this, especially shell this month so hopefully we can get some real examples up to see how it works. I

[aagonzales]

@mariuszmickiewicz I agree the Sketch kits are a concern, especially if we have to make a 5th Gray 80 kit. I think we should do some investigation into this and how we present it in Sketch. I wonder if there's anything we can do to help with this. Maybe we can flesh out Ian Kitchen's Theme plug-in to incorporate a specific light/dark mode switcher logic?

[laurenmrice]

I think that would be smart to utilize Ian's plugin or Camillo to have a light/dark mode option if we go down this route.

[janhassel]

Really good write-up! Thank you, @aagonzales!
Reading through the different concerns here makes me wonder:

I believe that a theme should be standalone for two main reasons:

• Users of the design system (designers and developers) would expect it: if there is a number of themes, it seems that one can choose from them. With proposal 2, only white, g10 and g100 would work though while g90 and g80 are "supporting themes", which cannot be used as a primary theme since they don't support enough layers.
• One really powerful aspect about the abstraction and token system Carbon has in place is the ability to adapt: if I'd need to build a product for a third-party company it should be possible to create a custom theme for them, matching their corporate branding. Defining a few more tokens for extra layers seems a lot more affordable than creating up to three distinct full themes.

@joshblack brings up a big pain point in his response (#7743 (comment)): specifying new components. Though, the simplicity mentioned there (creating the component with one set of tokens and it works across) could also be achieved with a middle-ground. Over in #7701 I explored this initially. What if a designer only specifies their component's colors with non-hierarchical tokens: background, field, border-strong and the component tree takes care of assigning those to the correct level by default?

• The workflow would be the following
  • The designer creates component and specifies only the root-level / flat token names:
    • 
  • The developer implements the component by using the flat token names:
    • var(--cds-background), var(--cds-field), var(--cds-border-strong)
  • By default, the flat tokens are being assigned to layer -01:
    • --cds-background: var(--cds-background-01)
  • Every additional layer re-assigns the variables. This could happen through several techniques, like
    • utility classes (.cds--layer)
    • sass mixins (@include layer)
  • As long as the developers only work work with these flat tokens, their component should always look correct if the element they're placed in emits the correct layer
  • (Side note on the example above: it could even be argued that the field token wouldn't be needed anymore and inputs would just use background which would be layered accordingly. Though it might be helpful to have this "duplicate" for the previously mentioned branding purposes to give more flexibility.)

This would apply the no.1 rule of designing with carbon to color application:

• Don't use absolute colors/type/spacing, use tokens instead! The theme will take care to match everything.
• Don't use absolute layering, use flat tokens instead! The rendering tree will take care to emit the correct layer to it.

Inline theming should still be possible to achieve what @joshblack called the "inverse" theme (#7743 (reply in thread)). For example to have a dark ui shell on a light app or a high contrast moment inside the content. Due to the propagation of css custom properties, all layering logic described above would still work with this.

In summary, this feels like a combination of the two proposals:

• Each theme can stand on its own and has a set of layered tokens
• The correct layer will be applied with some form of zoning
• Designers and developers only need to specify one case / variant
• light prop wouldn't be needed anymore
• UI shell could use default tokens
• Light / dark theme could be switched by changing the primary emitting theme

Let me know if I misunderstood some parts of the proposal and if this makes sense!

[aagonzales]

Is there really only 1 dark theme?

With proposal 2, only white, g10 and g100 would work though while g90 and g80 are "supporting themes", which cannot be used as a primary theme since they don't support enough layers. — @janhassel

Gray90 is the least used theme — so maybe this is not a big issue — but essentially it will be eliminated as a stand-alone one and only will serve as a layer for gray100, if I perceive option 2 model correctly. In this case maybe we don't even need the full library of components, just the ones which need to react to their layer level. — @mariuszmickiewicz

• I'm starting to wonder if there is only one dark theme and if so what are the consequences for the inline theming approach?
• If there is only three (maybe even just 2) theme motifs (ie white, light and dark) then what does that mean to our theme sets?
• Is it really easier to apply correct layering logic with such separated inline themes or is there actually some benefit in terms of understanding applications to keep a level of layering inside each theme (ie keeping in light variants).
• Is it a terminology problem? Are there actually theme sets (White, G10, G80 etc) and theme modes (light mode, dark mode)

[aagonzales]

You guys are right we would never recommend anyone to start with G80. I need to look and see if starting with Gray90 pans out. I like that term "supporting theme" but it does add an interesting level of confusion from a guidance and application perspective.

[kingtraceyj]

I'm wondering how this works if a team is using gray10 or white and needs to call an inverse panel that is the gray 90 theme. i think some components do this in cloud but not 100% sure. maybe it still works. would you use an inverse token and a layer?

[advurechensky]

Hey @aagonzales and IBM team. I would like to thank you for this discussion.
Half year ago I've tried to implement 2-th approach in my design system but faced with one issue.

1. Using 2-th approach you need to think about changing color tokens but visually it isn't clear. For example White theme labels looks as same as labels of the Gray theme. I'm afraid that for designers will be difficult to understand which token they need to use.

2. If I want to create a card (in the example below) as the component, what theme should I place it in? From one side it's the Grey theme, because I use it on Gray background, but from other side my card used components (and color tokens) from the White theme.

@aagonzales @joshblack @yumeforever @mariuszmickiewicz
What do you think? It's very interesting and important for me to hear your opinion