Defining "design token" from a "technical" perspective

[lukasoppermann]

Hey,

I think it would be very important for the standardisation process to define what we within the community group would define as a design token. This has influence on the specs for the format #1 and possibly other specs as well.

It will potentially also influence how tools would export and implement design tokens. I for example, am thinking about this because I am work working on a figma plugin for design tokens.

It may seem clear at first, but I tripped about the following aspects and there are probably more.

Single value entities

We can probably agree that any single value design property can be a design token.
Examples: (using css as an easy to show example)

--color-primary: #40FFBA;
--color-spacer: 16px;
--typescale-xxs: .5rem;

Multi-Value entities

There are properties like shadows or gradients that have more than one value.
The question is if the combined property is a design token or if only the indivisible aspects are design tokens:

Examples combined:

--gradient-success: linear-gradient(90deg, rgba(32,223,26,1) 0%, rgba(95,240,12,1) 54%, rgba(221,255,0,1) 100%);

Examples separated:

--gradient-success-angle: 90deg;
--gradient-success-stop-1-color: rgba(32,223,26,1);
--gradient-success-stop-1-position: 0%;
--gradient-success-stop-2-color: rgba(95,240,12,1);
--gradient-success-stop-2-position: 54%;
--gradient-success-stop-3-color: rgba(221,255,0,1);
--gradient-success-stop-3-position: 100%;

When working as a designer one would normally see the entire gradient or the shadow / elevation as a key aspect. E.g. for this card I used elevation-small. I don't know if this may be different for developers.

Multi-property entities (e.g. styles)

When working for example with text-styles there are different properties like font-size and font-family that make up a style. I would assume only the individual properties to be design tokens and the combination to be styles. Is this something we can agree on?

Examples design tokens

--font-family-sans: Roboto;
--font-size-large: 54px;
--font-style-italic: italic;
--line-height-small: 120%;

Examples style (?)

--display-headline-font-family: var(--font-family-sans);
--display-headline-font-size: var(--font-size-large);
--display-headline-line-height: var(--line-height-small);

[samwilliscreative]

Your example of styles using previously defined tokens is exactly how I have been creating tokens for my headings too. I have followed this pattern through to other components too, such as buttons and cards that share a global border-radius token:

--border-radius-sm: 12px;

--card-border-radius: var(--border-radius-sm);
... with other card specific tokens

--button-border-radius: var(--border-radius-sm);
... with other button specific tokens

In terms of the gradient and shadows, I have been keeping each part of the property as a single token, such as your seperated example, but then creating a complete token from those.

--var-1: foo;
--var-2: bar;
--var-3: biz;

--complete-var: var(--var-1) var(--var-2) var(--var-3)

[lukasoppermann]

Hey @samwilliscreative if this is a typical case, maybe it would make sense to define lower level design tokens or single value design tokens and composed design tokens.

Alternatively this could be defined as design tokens for single values and styles for composed ones.

Of course, we do have to also differentiate if a "shadow" is one token (is it more like a color, something you use as a whole) or is it more like a text style (a composed value of individual tokens that may be used in different places as well).

[Kingdutch]

Just to ensure parallel discussions are tied together. The discussion around theming already had some discussion around using options for what is here named "lower level design tokens" and using choices for what you call "single value design tokens": #2 (comment)

Looking at the images in the linked comment, composed design tokens could be a level between choices and the components themselves.

[lukasoppermann]

Thanks @Kingdutch, as far as I can see the theming topic is mostly about referencing design tokens in other design tokens.

E.g. the choice primary-color is referenced in the option interactive-background.

Both choices and options are what I called "single value design tokens" (which of course is not a name I would actually use but just to clarify).

But I think this does not really answer the points above. Does this make sense @Kingdutch or did I miss something?

Looking at the images in the linked comment, composed design tokens could be a level between choices and the components themselves.

I think using the naming I use above styles would be the in-between, correct? A style could for example be a combination of button background color and button text color.

[nesquarx]

It makes sense to have multi valued tokens, I'm using one to combine a --radius-default-shadow, --color-default-shadow and opacity-default-shadow tokens to define a -default-shadow token but at some point we need to see that we're not just replicating our css style blocks in the token structure. IMO the necessity of tokens is for abstraction more than encapsulation - but using it for contextual encapsulation works too.

Edit: As is referred to as groups here

[kevinmpowell]

@lukasoppermann thanks for kicking off this thread. The Format group has already had several conversations about the types of tokens you mention. One thing we've come around to is that CSS shorthand properties are a feature of a particular context: CSS.

As we think about tokens more broadly, and supporting additional contexts (iOS, Android, Design tooling), we're discussing whether or not the source syntax of tokens should have any knowledge of a context like CSS, or if that should be something that's applied during a transformation process to CSS. We're still discussing this, so it's great to see what the community is thinking about.

[lukasoppermann]

Hey @kevinmpowell, thanks for reaching out. I feel the RFC format topic has grown quite broad so that a lot if things get lost within the many, many lines of text. 😁 As this is a very important questions I think it deserves a separate place, especially since I think it may only be related but not completely included in the format standard. (Technically, so far at least, a token could be of any type and kind.)

Concerning shorthands & knowledge of context

I agree with that tokens (being in their nature technology agnostic) should have NO knowledge of the context.

I am more concerned with the mental model around tokens. As a designer a token I use in e.g. Figma would be shadow-small once this is setup up as a style I am normally not concerned with the particular details of how the blur is or how git the shadow is. In a designers mental model the shadow as a whole would thus be a token.
From a developers point of view this may be different (it may depend on the technology they are used to, but it may also not).

I think this mental model is what we can and should still standardise and form.

Do I make sense? 🙃

[kevinmpowell]

As a designer a token I use in e.g. Figma would be shadow-small once this is setup up as a style I am normally not concerned with the particular details of how the blur is or how git the shadow is. In a designers mental model the shadow as a whole would thus be a token.
From a developers point of view this may be different

I think what you're saying is one person's definition of the term "token" may be very different from another person's definition of the term "token."

That is something we've found very true thus far in our discussions. We're working toward defining that and getting on the same page as a group of editors. What you've raised here about the distinction between multi-value and single-value tokens is an important aspect of that.

I agree the RFC Issue has gotten very broad. I'll bring this up at the next editors meeting. I think separate discussion threads for the community around some facets of the format may make sense at this point.

@donnavitan @dbanksdesign @c1rrus @ChucKN0risK @zackbrown

[lukasoppermann]

I think what you're saying is one person's definition of the term "token" may be very different from another person's definition of the term "token."

Exactly! 👍

I agree the RFC Issue has gotten very broad. I'll bring this up at the next editors meeting. I think separate discussion threads for the community around some facets of the format may make sense at this point.

That would be great. Thank you. 🙏

If I can help with that in any way please let me know.

[phun-ky]

@lukasoppermann sorry for coming late to the party, only found out about this community a couple of days ago. But, here I am.

Yes, a token can be single or multi value, but that depends on the detail levelling or context. Shorthand vs longhand will also come to play here. The technical aspect of a specc (css) can be changed / broken, and browsers can interpret shorthands differently.

Take gradients for example, in some occasions you just want the start / stop pattern predefined, or only the color, or only a group in the gradient, or event whole stacked gradients. How can a design token spec take this into consideration?

I think the spec needs to allow for both levels of control.

Another example could be box-shadow (CSS); you can have a token for the direction of a shadow (light direction), the hardness and the blur. Also, a specific color only used for shadows. That color token can again be a composite of a color and an opacity.

For me, it feels like it's getting out of hand. In my use case, in regards of shadows, we've predefined shadows as a whole, combining every attribute into one token. Makes it easier, not many "loose parts". KISS and all that.

[jina]

Closing this thread because we have implemented a glossary since, which can be added to over time. https://www.designtokens.org/glossary/