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.

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

In T309050#8342963, @egardner wrote:

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.

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.