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

[design/codex@main] tokens: Clean up deprecation messages

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

For deprecated tokens that are just aliases of non-deprecated tokens, I think it would make the most sense to remove them from Codex completely, and just provide those aliases in wikimedia-ui-base. For deprecated tokens that have unique values (values different from any non-deprecated tokens), I think it should keep them in Codex as deprecated tokens.

I analyzed all 94(!) deprecated tokens, and they fall in three categories:

1. Straightforward aliases: a non-deprecated token with the same value exists. For example, background-color-base--hover is a deprecated token with the same value as background-color-interactive
2. Legacy shorthands: a multi-value token that can be assembled from multiple non-deprecated tokens. For example, border-base is a deprecated token whose value can be constructed by combining border-width-base, border-style-base and border-color-base.
3. Legacy values: there is no straightforward non-deprecated alternative token
   1. Sometimes a replacement non-deprecated token is suggested, but that token has a different value. For example, width-breakpoint-tablet (deprecated) is 720px, but min-width-breakpoint-tablet (its suggested replacement) is 640px
   2. Sometimes a token with the same value exists, but it's not conceptually related. For example, color-base--subtle is #72777d. Its suggested replacement is color-subtle, which is #54595d. There are non-deprecated tokens with the value #72777d (color-placeholder and color-disabled), but they're not clear equivalents.

The 94 deprecated tokens break down as follows:

• 68 in category 1 (straightforward aliases)
• 16 in category 2 (legacy shorthands)
• 10 in category 3 (legacy values). Of these, 6 are in category A (suggested replacement with different value), 1 in B (unrelated token with same value), 1 in both A and B, and 2 in neither

The 10 legacy value tokens are:

@background-color-primary--hover: rgba( 51, 102, 204, 0.1 ); /* Neither A nor B: unique value, no replacement suggested */
@color-base--subtle: #72777d; /* A and B: @color-subtle is #54595d; @color-placeholder and @color-disabled have the same value */
@width-breakpoint-tablet: 720px; /* A: @min-width-breakpoint-tablet is 640px */
@width-breakpoint-desktop: 1000px; /* A: @min-width-breakpoint-desktop is 1120px */
@width-breakpoint-desktop-wide: 1200px; /* A: @min-width-breakpoint-desktop-wide is 1680px */
@width-breakpoint-desktop-extrawide: 2000px; /* Neither A nor B: unique value, no replacement suggested */
@padding-vertical-menu: calc( 4px + 1px ); /* B: @spacing-30 is also 5px */
@font-family-sans: 'Helvetica Neue', 'Helvetica', 'Liberation Sans', 'Arial', sans-serif; /* A: @font-family-sans--fallback is suggested but it's sans-serif */
@line-height-x-small: 1.4285714; /* A: @line-height-small is suggested but it's 1.5714285 */
@line-height-heading: 1.3; /* A: @line-height-xx-small is suggested but it's 1.375 */

I propose we do the following:

• For categories 1 and 2 (straightforward aliases):
  • Delete these from Codex
  • When we use the Codex tokens in wikimedia-ui-base (T318016), we'll add aliases for them in wikimedia-ui-base, e.g:
    • @background-color-base--hover: @background-color-interactive;
    • @border-base: @border-width-base @border-style-base @border-color-base;
• For category 3 (legacy values):
  • Keep these tokens in Codex, as deprecated tokens
  • This means they'll be available in MediaWiki and need default values in mediawiki.skin.defaults.less. But I think that's OK because there's only 10 of them
• For category 3B (legacy value tokens where there's a non-deprecated token with the same value):
  • Consider making these aliases for existing tokens with the same value. This would allow us to also remove these from Codex and move them into wikimedia-ui-base, reducing the number of deprecated Codex tokens to 8.
    • @padding-vertical-menu: @spacing-30;
    • @color-base--subtle: @color-placeholder; (this one doesn't make as much conceptual sense, so we could forego it)

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

[design/codex@main] styles: Replace deprecated tokens with their non-deprecated equivalents

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

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

[design/codex@main] tokens: Remove most deprecated tokens

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

The attached patches implement my proposal. They don't exactly do what the task title asks for, but they solve the same problem: remove 84 of the 94 deprecated tokens from Codex, so they can later be moved into wikimedia-ui-base instead.

Change 892585 merged by jenkins-bot:

[design/codex@main] tokens: Clean up deprecation messages

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

Change 893091 merged by jenkins-bot:

[design/codex@main] styles: Replace deprecated tokens with their non-deprecated equivalents

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

• When we use the Codex tokens in wikimedia-ui-base (T318016), we'll add aliases for them in wikimedia-ui-base, e.g:
  • @background-color-base--hover: @background-color-interactive;
  • @border-base: @border-width-base @border-style-base @border-color-base;

One thing to get further clarification on: Having those deprecated tokens in Codex was providing a visual lookup table in central documentation central. It indeed added 94 tokens to Codex and is causing the other issue with bringing tokens to MediaWiki.

Now, we are outlining the path to remove the deprecated tokens and use aliases in WikimediaUI Base. However, this might create an abstraction problem since the token visualization is a strength of Codex demos.
The last patch removes that visual lookup. Maybe that's fine for most developers. For me, having done a ton of mediawiki.ui, MinervaNeue, OOUI and more variables replacements in the past, it's a point to raise.

In a possible patch replacing background-color-base--hover with background-color-interactive downstream in f.e. MW core's DateTimeInputWidget it's a good helper to have the visual comparison on the token documentation page too.

Have added T331403 for replacing the legacy ones.

Change 893094 merged by jenkins-bot:

[design/codex@main] tokens: Move most deprecated tokens to separate aliases file

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

For some reason the following stayed a draft for too long:
Having those deprecated tokens in Codex was providing a visual lookup table as documentation central. Yes it was adding 94 tokens to Codex, but the visual lookup is essential for the upcoming replacements downstream.
Luckily @Catrope has followed up on this concern and we've got the deprecated WikimediaUI Base aliases still in Codex demos. 👏🏼

Design sign-off done. The new organization moving the deprecated tokens to a separate last section looks good to me.

Just 2 small things:

1. Could we rename this section from "Deprecated aliases in WikimediaUI Base" to just "Deprecated aliases" or "Deprecated tokens"? The current name is too long and we already have the alert indicating that these deprecated aliases are only available in WikimediaUI Base.
2. Why the deprecated breakpoints section name is Width (legacy)? Could we also use "Deprecated" to name this section?

I've already answered 2. in a Slack conv: There are 10 legacy tokens identified that have no 1:1 alias right now. See T331403.

That would be my proposal:

Patch at https://gerrit.wikimedia.org/r/c/design/codex/+/898751

Change 898895 had a related patch set uploaded (by Eric Gardner; author: Eric Gardner):

[mediawiki/core@master] Update Codex from v0.6.2 to v0.7.0

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