Page MenuHomePhabricator

Developer experience feedback on Design Tokens
Open, Needs TriagePublic

Description

Background

I have raised this issue as an action point from a discussion that we had in the engineering enclave on May the 23rd.

Below is my "personal" experience of working on the re-organization of the button states.

"The current division of designs token is not working very well from a development experience point of view. The most problematic layer of the token has been the "codex-components". This seems to be very useful on paper, but its current usage of it turns out to create more headaches than development support.

A few issues that I have encountered while developing the above-mentioned task:

  • Not all button states have a codex-component token: for example @border-color-progressive--hover
  • There is no distinction within the tokens to understand where the token comes from so @border-color-progressive--hover is from codex-base but @background-color-quiet--hover" is from codex-components`
    • Good point. For context, -quiet was inherited from OOUI/WikimediaUI Base. All other tokens in 'codex-components.json' are already applying the component that they are used for in their name. We'll update to -button-quiet accordingly.
  • Sometimes a codex-base token may not align with a component one, so a "progress-base--hover` may need to be overridden in codex-components just because the Progress-base-hover of the button is not the same as the base!
    • VE: Not sure, I understand what's meant here.
  • We try to avoid the creation of many tokens, so if a couple of states share a value we try to reuse it, but this turns out to be not very clean to read in the .vue files. You may find a "hover" in an active state or a "Normal" declaration in the progressive.
    • VE: This is a problematic gap that should not happening with the full tokens nomenclature settled. Modifier tokens should be exclusive to states.
  • The Figma designs are always (until now) being provided with the use of the codex-base, and it is time-consuming to decode what the colour meant at a "codex-component" level.. (lots of Find All)
  • Components could have a very nested level of requirements (eg button-normal-progressive-active). This is quite verbose to define in tokens and can be cleaner and easier to see within a full CSS declaration where.
    • VE: That's not the case anymore with updated color tokens in place T296995
  • We are not making good use of the actual .vue file. These are supposed to include the full scope of the components, and I think we could remove the codex-component and actually declare component-specific token (or more specifically CSS declaration) directly within the component and just call the Codex-base file."
    • VE: As much as this might make sense from a pure developer view, it's important to collect the component tokens in one place in order to see emerging patterns or be clear about the discrepancies of one-offs.

Doc to collect feedback

Event Timeline

On the last point:

  • We are not making good use of the actual .vue file. These are supposed to include the full scope of the components, and I think we could remove the codex-component and actually declare component-specific token (or more specifically CSS declaration) directly within the component and just call the Codex-base file."

That'd be problematic for system reasons. We need to have central points for the tokens in order to visibly have them side by side and identify close-by values, overlaps and gaps. codex-components provides us with this better than having definitions in SFCs, hence T295711: Turn component-specific (SFC) Less variables into Codex design tokens

Design Tokens and their discontents

I just want to second many of @SimoneThisDot's concerns. The developer experience of working with these tokens does not feel great currently. Here is what my typical workflow looks like when developing a new component:

  1. Review the design spec in Figma, looking closely at pixel values, colors, etc. as defined in that file.
  2. Search through the *built LESS variables file* from the tokens and work backwards, trying to find the exact value (8px, a particular color, etc). I use the LESS file because I want to know exactly what I'm getting, but this file is not very legible. There is little differentiation between different types of tokens, and sometimes there are multiple variables in that file that point to the same final value. I take my best guess about which token to actually use. Needless to say this is a cumbersome workflow.
  3. Inside of a Vue SFC, my typical way of working would be to define a set of variables at the top of the <style> block: @tabs-heading-margin-horizontal: @size-100, etc. But this has been discouraged in favor of just referring to the generic token name wherever it gets used (so just use @size-100 everywhere in the rule declarations directly).

Here are some things that I think would improve the situation:

  • It would be good to have a developer-friendly entry into the tokens system that contains only the values that should be referenced in a published component file, but instantiated as LESS variables – just decision tokens, no options, etc.
  • Sometimes the name of a token is misleading. For example, when working on Dialog, I introduced a divider element and first referenced the dedicated divider-color token – but this turned out to be wrong; the "subtle" color token was meant to be used here instead. Calling out these kinds of situations clearly in the Figma specs would be helpful.
  • I would prefer to reference a globally defined token with a meaningful local name in some cases. This makes it easier to understand what is going on without having to jump out of the component file in question – one of the advantages of Vue SFCs, as Simone mentions. A meaningful local name also makes it a lot easier to understand the relationships between values – maybe the margin of one item must offset the size of another, etc., or I'm referencing a value in calc(). Using generic token names obscures meaningful relationships between values within a single component's styles, and if I have to go back and re-factor something it's possible that something will get missed. I understand that we shouldn't just be defining random new *values* here, but I'd like to be able to define a local variable that references a pre-existing token when necessary.

At the end of the day, it should be simple for a developer to implement the correct design values when working on a component without having to understand the whole token system.

Volker_E renamed this task from Current division of Design Token can be missleading while developing to Developer experience feedback on Design Tokens.Oct 28 2022, 8:00 AM
Volker_E added a subscriber: STH.

From size and spacing application patch by @AnneT

I've used these padding [padding-horizontal-base, padding-vertical-base] tokens quite a bit, and they're very handy - are we increasing the burden on developers to remember which tokens should be used for vertical/horizontal padding? Can you remind me of the reasoning behind deprecating the padding tokens?

Change 854133 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] tokens, Button: Rename to `background-color-button-quiet*` tokens

https://gerrit.wikimedia.org/r/854133

Change 854134 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] docs: Expand explanation on component tokens

https://gerrit.wikimedia.org/r/854134

Change 848519 had a related patch set uploaded (by VolkerE; author: Catrope):

[design/codex@main] tokens: Don't output theme tokens in CSS/Less/Sass output

https://gerrit.wikimedia.org/r/848519

Design Tokens and their discontents

Here are some things that I think would improve the situation:

  • It would be good to have a developer-friendly entry into the tokens system that contains only the values that should be referenced in a published component file, but instantiated as LESS variables – just decision tokens, no options, etc.

That comment is already forward-pointing in the patch by @Catrope I've just linked.

  • Sometimes the name of a token is misleading. For example, when working on Dialog, I introduced a divider element and first referenced the dedicated divider-color token – but this turned out to be wrong; the "subtle" color token was meant to be used here instead. Calling out these kinds of situations clearly in the Figma specs would be helpful.

If border-color-divider is not working for a divider component, that's a flag to be shared with the design peers. That surfaces either a problem with the nomenclature misleading or the value applied in the design.

  • I would prefer to reference a globally defined token with a meaningful local name in some cases. This makes it easier to understand what is going on without having to jump out of the component file in question – one of the advantages of Vue SFCs, as Simone mentions. A meaningful local name also makes it a lot easier to understand the relationships between values – maybe the margin of one item must offset the size of another, etc., or I'm referencing a value in calc(). Using generic token names obscures meaningful relationships between values within a single component's styles, and if I have to go back and re-factor something it's possible that something will get missed. I understand that we shouldn't just be defining random new *values* here, but I'd like to be able to define a local variable that references a pre-existing token when necessary.

The major point about design tokens is to have a limited amount of design decisions in a shared vocabulary applied consistently. With every new SFC token invented and, for example, the calculations of base tokens as values, the possible vector of inconsistency increases.
Certain calculations not possible to be simply covered by tokens in context might be the sane boundary for defining SFC tokens. F.e. adding absolute SFC base padding and relative icon size) or recurring values to surface a pattern in an SFC like the size-figure.

At the end of the day, it should be simple for a developer to implement the correct design values when working on a component without having to understand the whole token system.

I understand the sentiment. I will also say, that the tokens are the base design foundation for the system. Closing the gaps and making it simpler to understand are what we're aiming for in this task. But it won't work without some system knowledge.

Change 854133 merged by jenkins-bot:

[design/codex@main] tokens, Button: Rename to `background-color-button-quiet*` tokens

https://gerrit.wikimedia.org/r/854133

Change 854134 merged by jenkins-bot:

[design/codex@main] docs: Expand explanation on component tokens

https://gerrit.wikimedia.org/r/854134

Change 848519 merged by jenkins-bot:

[design/codex@main] tokens: Don't output theme tokens in CSS/Less/Sass output

https://gerrit.wikimedia.org/r/848519

Change 859597 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[mediawiki/core@master] Update Codex from v0.2.2 to v0.3.0

https://gerrit.wikimedia.org/r/859597

Change 859597 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.2.2 to v0.3.0

https://gerrit.wikimedia.org/r/859597

With these latest changes, are all your concerns addressed @egardner and @SimoneThisDot?

Some positive feedback: I've used the spacing tokens a few times and find the scale quite intuitive and the most frequently used values (25 through 200) easy to remember

I've created this spreadsheet to collect here all the feedback. I've created 2 columns to add positive and negative (if anything) feedback and one page for each token. Feel free to edit it.

{F35815494}

Another point collected with legacy font families tokens T322811 was, that comments in option tokens about font decisions building the designer options don't proceed into the output stylesheets. Information for devs only looking at CSS is lost as the decision tokens in the output are missing the comments.

Volker_E updated the task description. (Show Details)

Is this task still active? Simplifying the LESS variables that get exported improved the experience of using tokens for me. Is there anything else actionable here? If not I will close.