[RFC] Theming

[kaelig]

As all platforms are just about to support their own versions of dark mode, theming is becoming an important part of an efficient design workflow.

Let's talk about how design tokens should handle theming.

Here's a rough draft that essentially mimics how the CSS cascade works:

// Defaults
[
  { name: 'tokenA', value: 'foo' },
  { name: 'tokenB', value: 'bar' },
]

// Overrides for dark mode, loaded subsequently
[
  { name: 'tokenA', value: 'baz' },
]

// Should resolve to:
[
  { name: 'tokenA', value: 'baz' },
  { name: 'tokenB', value: 'bar' },
]

In a design tool, a designer could load and toggle any number of override files in order to get to the target platform (such as: Defaults < Android < Dark mode).

[mathieudutour]

a designer could load and toggle any number of override files

That's one way to think about it: one tokens file per theme, very much like what Theme UI is doing.

Another way would be to have tokens having a value keyed by theme. And so when you define a token, it's only defined in a single place and it's super easy to reason about.

I feel like the first approach makes more sense as an API to pass to an app or a component while the second one is how designers think about tokens and would make a lot more sense in design tools.

[mkeftz]

I like the idea of combining the tokens to produce a single tokenlist. Probably most of all because this could leave the managing of variants outside of the spec!

However, I think there is an issue with how they are combined. Being based on the order they are loaded will give different results based on how the designer loads them. Load Dark, then Android could give a different result to Android, then Dark.

I feel like the first approach makes more sense as an API to pass to an app or a component while the second one is how designers think about tokens and would make a lot more sense in design tools.

In my opinion, a design tool could handle either format and display it in a way that makes sense for the designer. But I do agree the "value keyed by theme" option makes it more human readable.

The issues I have with "value keyed by theme":

• need to define a value for all variants, which makes it less human writeable, bloated and error-prone
• cannot handle multi-dimensional variants. Which value is used if it's Dark and Android?
• cannot handle combined dimensional variants. I want a value for "Dark", "Android", and "Dark & Android". Although this is a less common requirement.

These could be fixed by extending from #1 (comment)

{
  // define all variant dimensions and possible values
  variants: [
    { name: "theme", values: ["light", "dark"] },
    { name: "platform", values: ["web", "ios", "android"]  }
  ],

  tokens: [

    // simple if you don't need theming 
    { name: "token2", value: 3 },

    // only specify values for the variants you want to override, 
    // all others get default "value"
    { 
        name: 'tokenB', 
        value: 'baz',
        variants: [
            {
                theme: 'dark',
                value: 'foo'
            }
        ]
    },

    // can define combined variant values, i.e. Dark and Android
    { 
        name: 'tokenA', 
        value: 'baz',
        variants: [
            {
                theme: 'dark',
                platform: 'android',
                value: 'bar'
            }
        ]
    },
  ]
}

@mathieudutour - you mentioned you found it safer to provide a value for all variants. What makes it safer?
I believe having a base value and only overriding what you need makes it safer and easier to manage. The reason I find this approach safer is if you miss a variant value, you just get the default. Otherwise, you would get a "Not defined" error.

[Kilian]

@mkeftz your approach is more forgiving, so 'safer' in that regard, but @mathieudutour is more explicit, meaning that any bugs caused by referencing something that's not there will be made explicit too. In the context of theming (and tokens in general), does having a fallback make sense? I can think of arguments for both sides so I'm not sure.

I prefer the cascade option with multiple files. Then there's the option of having both dark.tokens and android.tokens overwrites but you can also have a android+dark.tokens override should you need it.

One thing the spec could do is make it easy to cross-reference between these files, so that the android+dark.tokens could do something like this pseudocode:

{
   colors: 'dark.tokens/@colors',
   spacing: 'android.tokens/@spacing',
}

other values like typography would then just live in the default.tokens file loaded previously.

[mathieudutour]

I feel like tokens will need to be split up in different files anyway, but I was imagining it more split by "type" (eg. color, typography, etc.) instead of theme.

So I'm not sure the matrix of variants would really happen: I have a really hard time imagining a token that actually need to be split across a matrix. It's either per "theme" (colors) or per "platform" (typography) but not really both, right?

[Kilian]

A `.tokens` file could be a container, making that split possible. Saying that there is never an overlap between variants is very opinionated and in the case of eg responsive design, colors might be different depending on the ‘size theme’ that could then interfere with a dark mode theme. Or think of a high contrast theme that needs to work with multiple platforms but also itself changes sizings for readability. So I would stay away from thinking of themes as ‘just different platforms and dark mode’ and instead treat them all as equal variants and think of ways they should(n’t) be able to interact.

…

On 26 Jun 2019, at 10:20, Mathieu Dutour ***@***.***> wrote: I feel like tokens will need to be split up in different files anyway, but I was imagining it more split by "type" (eg. color, typography, etc.) instead of theme. So I'm not sure the matrix of variants would really happen: I have a really hard time imagining a token that actually need to be split across a matrix. It's either per "theme" (colors) or per "platform" (typography) but not really both, right? — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

[mkeftz]

So I'm not sure the matrix of variants would really happen

I disagree... sure not for simple themes like "Dark mode". But branding themes are often more complex.
For example, take a look at Seek's Braid DS. Here is one of their token files: https://github.com/seek-oss/braid-design-system/blob/master/lib/themes/jobStreet/tokens.ts
They define font size, space, etc. in the Theme token file. They don't support platform-specific variants yet AFAIK, but if they did add it, it could also contain space tokens.

[mathieudutour]

Indeed, that's a good point.
Thinking a bit more about it, I quite like @mkeftz's proposition here: #2 (comment).

But as mentioned in the other thread (#1 (comment)), while I understand the appeal for a default value + overrides for variants (convenience, conciseness), I think that specifying all the variants makes it more explicit, safer, and makes sure there is only one way to write your file (hence, a lot easier to parse, etc.).
If someone is worried about an combinatorial explosion, they can split their tokens in different files so that only the ones that needs to interact with different variants defines them.

[dbanksdesign]

I do like @mkeftz's proposal as well. I will say we should really focus on the interoperability aspect, and with that being flexible and extensible. There were some comments on usability from a standpoint of writing these, but the tools (Sketch, Figma, Theo, Style Dictionary, etc.) could make those usable abstractions and output the underlying token spec. Does that make sense? So some tools could allow you to write tokens like @mkeftz's proposal, but maybe the underlying token spec is more simple and flexible? (Although, the proposal is pretty simple and flexible already)

[kgcreative]

Hi all! -- no specific company representation here beyond experience and an interest in this topic.

Two things. First,

Regarding variants, I think a way of specifying inheritance can help resolve some of these questions. This would both make it specific, and help resolve collisions.

For example (pseudocode, building off of Kaelig's example)

// Defaults
defaults [
  { name: 'tokenA', value: 'foo' },
  { name: 'tokenB', value: 'bar' },
  { name: 'tokenC', value: 'baz' },
]

// Overrides for Brand A
brandVariantA [
 { name: 'tokenA', value: 'qux' }
]

// Overrides for dark mode
darkMode[
  { name: 'tokenC', value: 'xyz' },
]

// You can then specify a custom variant that specifies order of inheritance
myVariant [
  { name: 'inherits', value: 'defaults' },
  { name: 'inherits', value: 'brandVariantA' },
  { name: 'inherits', value: 'darkMode' },
  { name: 'tokenD', value: 'abc' }
]

// Should resolve to:
[
  { name: 'tokenA', value: 'qux' },
  { name: 'tokenB', value: 'bar' },
  { name: 'tokenC', value: 'xyz' } ,
  { name: 'tokenD', value: 'abc' }
]

And second,

To chime in on branding themes and overrides, a specific use case I don't see mentioned when specificity is discussed is what happens when the variant is a relative value. This is fairly common for me when dealing with responsive design, but not as much with native.

For example, when i'm working with responsive typography, often I want type on a breakpoint to be relative to the base type. This is especially useful if i'm ceding the user control with things like zoom, and I want my units and spacing to stay proportionally the same.

Similarly for color, sometimes I want a value that's darker or lighter than a base hue, but I want the base hue inherited. Again, something fairly trivial to do in code, but endlessly complex in design tools.

This has in the past been a source of frustration with design tools, because I can specify 1.13em on web, but there is no way to do that in my design tool without deriving a computed value and locking it in place.

Same with color. I can use tint/shade functions to darken or lighten a hue on web, inheriting a particular value, but in other contexts, i need to derive a computed value in order to simulate it for my design tool.

It means if I change my mind about the base font size, for example, my design tool doesn't reflect the change in real time. I have to manually edit all my styles.

[c1rrus]

Excellent points. The lack of support for relative length units like em or rem in many design tools irks me too.

Thinking of a standardised token format, I'd suggest it should support such units (or at least some equivalent thereof).

Perhaps if a tool that reads token files does not support relative units internally, it should convert to a unit it does understand (e.g. by substituting 16px for 1rem) as part of the parsing process. It's a lossy conversion, but for many uses it should be acceptable.

The question becomes what the behaviour should be when such a tool subsequently writes out any updates or additions to the token file?

• Does it simply (over)write with pixel values? That would be annoying since you end up losing the original rem value
• Does it reverse whatever conversion it did when it read the file (e.g. divide by 16). But then what happens for any new values that are being added? How would it know a new px value should be converted to rem? The author may want to preserve that as px.

Perhaps a sensible compromise would be:

• the tool remembers which token values it had to convert when it read the file. When writing them back out, even if those values were modified, it converts back to the original format. So, for example an em value would remain an em value, even if the tool doesn't really support ems internally
• any newly added tokens are simply written out in whatever format the tools does support (e.g. px)

If an author wishes to convert those, they need to do that themselves afterwards. Either manually or perhaps with the help of some other tool. At least this way they only need to do so once.

[ddamato]

One of the approaches that I use within CSS is to have a proxy in between the root variables (think a color palette) and the parts of the component to which they are applied (think applying a value to a CSS property).

:root {
    --color-red--500: #e51c23;
    --color-red--600: #dd191d;
}

[theme="brand"] {
    --backgroundColor-buttonCritical--pressed: var(--color-red--500);
}

[theme="wild"] {
    --backgroundColor-buttonCritical--pressed: var(--color-red--600);
}

.my-danger-button:active {
    background-color: var(--backgroundColor-buttonCritical--pressed);
}

In this way, the selection of the token to use is done by determining the intent of the color instead of the specific value. When selecting a theme, the new proxy is loaded in, reading from the available palette. If a decision is made to change all values of critical button backgrounds in a particular theme, it's done without finding all the instances.

While this is probably less of an issue within design tools where components are created as reusable symbols and their values are assigned at the design system maintainer level. I can expect newer components not yet included in the system to require some guidance in determining what color (or any token for that matter) to use instead of just picking any red so that it aligns with a provided system or theme.

[NateBaldwinDesign]

Hi there 👋 ! I'm particularly interested in the issue of theming and token authoring. This is one problem that is seemingly simple but can become incredibly complex. There are a few thoughts that I have regarding this issue:

1. Definition of "Theme"
2. Abstracting contexts for token flexibility
3. Philosophical use of overrides
4. Token definition vs. tooling

Definition of "Theme"
I believe some clear definitions may be helpful prior to having deeper discussion into theming. For some folks, "theme" refers to the color palette used. For others, a "theme" refers to the entirety of the design language itself (think parent companies that have vastly different brands using the same core components).

There's value in recognizing that for each type of token a user defines (color, spacing, typography, etc), there is the possibility of having relative "themes"; essentially just different contexts that can be applied to a design language (as mentioned by @mkeftz regarding complexity of brand 'themes' above).

I believe the original comments of this thread assume "theme" to relate to "color themes". If that is the case, I would recommend using that language with the assumption that there may also be "scale themes", or "typographic themes" which designers may combine into unique design languages.

The rest of my comments are under the umbrella of "color themes"

Abstracting contexts for token flexibility
What @ddamato illustrates above is exactly where I believe there's value in approaching the issue of themes. There should be abstractions in tokens that allow for global context (such as color palettes), relative context (such as semantically aliasing tokens to common uses), shared contexts (such as common groups of tokens that are represented in multiple different components) and explicit context (such as defining a button's tokens for a button only). Although the shared contexts layer is not always needed depending on implementation.

Global context (at least for Adobe's design system Spectrum) is where users define the hard values that they wish to use. This has been tremendously helpful in allowing us to combine color theme and scale independently. Users can define only the color values for each theme in separate files, thus allowing contextual and explicit aliases to only be written once. ie:

// light.js
   'gray-100': 'rgb(245, 245, 245)';

// dark.js
   'gray-100': 'rgb(50, 50, 50)';

// colorAliases.js
   'background-color-default': 'gray-100'

// sideNavigation.js
   'background-color: 'background-color-default'

Explicitness in errors (such as "Dark.js does not have token 'gray-100'") is fine in my opinion. It helps designers to ensure there's parity in the applied philosophy behind their design system, even though it is bound to them in some ways. Although this can be mitigated. For example, if we don't have gray-100 in dark.js, you should be able to specify in the alias layer what you would like instead. For example:

// colorAliases.js
   'background-color-default': {
        'light': 'gray-100',
        'dark': 'some-other-color'
    }

Philosophical use of overrides
Regarding the discussion on overrides for themes, it comes down to the question of what is a default for any given thing? The idea of a color palette having a "default value" is very unusual and will result in very bizarre outputs that will create confusion for designers -- especially if some themes have colors that are very similar to the "default" (design may overlook or not even see that there is an error).

Overriding makes sense when there is a sensible default, such as default states of a component. The notion of overrides in terms of defining state-related color changes, or variant-related color changes is 100% appropriate.

But when it comes to global-level tokens, I'm in the camp of throwing an error. Theming (for both color and all other types of theming) can become very complex, and "defaulting" to a particular value could be more problematic than just throwing an error. For example, Brand A has a theme that is overridden by Brand B. Brand A is vibrant in color, and Brand B is a more muted B2B theme. If a color token defaults to the vibrant Brand A color rather than throwing an error, the result would be highly undesirable.

Token definitions vs Tooling
I believe token standardization can happen agnostic of tooling. Tools can be built to do any number of things, and the standard should not be predisposed to assumptions about problems a tool may have to solve. Relativity in tokens is a must-have in my opinion. Many platforms support relative values, and their use in a design system is tremendously beneficial. Many (if not most/all) design decisions made by systems designers revolve around relativity... so even when a designer says "give this item 32px height", sometimes what they're really saying is "this item has the same height as the base type line height".

If tokens can be defined as relationships (wherever needed), that will help designers to codify the gestalt of their design aesthetic into every detail of their system in a much more manageable way.

[ddamato]

In terms of "defaults", I like to be prescriptive for the theme. Even if we have a primary brand theme, it is not based on default values, it's based on values specific for the theme. I think the "default" is there for when a theme fails. In the case of the web, perhaps it's better to have a default in to ensure the page is readable as the theme loads in.

.my-danger-button:active {
    background-color: var(--backgroundColor-buttonCritical--pressed, '#f00');
}

The theme for the components may have failed in loading, so we fallback to the #f00 which isn't part of any "theme", it's the default value. It's certainly possible that no change is detected; as in --backgroundColor-buttonCritical--pressed's value could be #f00.

In the case of overriding, I think that's less of a design token issue and more of a permissions issue. Design tokens are shared values for a managed design system; if you don't want to use those values, then you are simply deciding on different values. However, if the tool's permissions say you must use these tokens only (with some leeway in approved places), then I think that's a separate topic. I think what's being asked for here is a method of accessing predetermined values in design tools as well as custom values.