Page MenuHomePhabricator

Mark deprecated legacy design tokens loud and clear
Closed, ResolvedPublic

Assigned To
Authored By
Volker_E
Jun 3 2022, 1:58 AM
Referenced Files
F35546683: image.png
Oct 4 2022, 5:41 PM
F35546680: image.png
Oct 4 2022, 5:41 PM
F35538844: image.png
Sep 29 2022, 2:49 AM
F35538819: image.png
Sep 29 2022, 2:49 AM
F35423992: Screenshot 2022-08-11 at 17.34.23.png
Aug 11 2022, 3:39 PM
F35423983: Screenshot 2022-08-11 at 17.32.16.png
Aug 11 2022, 3:39 PM
F35384434: image.png
Aug 2 2022, 6:17 PM
F35346200: Screenshot 2022-07-27 at 15.49.04.png
Jul 27 2022, 4:09 PM

Description

Background

Current Codex token demo pages show all tokens including legacy tokens in an equal quality presentation.

image.png (490×1 px, 76 KB)

That low-tone might confuse our consumers and mislead them when applying tokens.

Possible solution

Using a visual element such as a "warning" tag could be helpful.

Screenshot 2022-07-27 at 15.49.04.png (252×791 px, 172 KB)

User experience improvements and criteria for done

  • Mark legacy tokens clearly and loudly as such.
  • Put 'deprecated' tokens at bottom of tokens list.

Event Timeline

After a quick design discussion, we agreed that using a visual element such as a "warning" tag could be helpful:

Screenshot 2022-07-27 at 15.49.04.png (252×791 px, 172 KB)

On a side note, I'm not able to see any deprecation notes currently in the demo site. Was that screenshot taken from the live demo?

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

[design/codex@main] tokens, demos: Mark deprecated tokens loud and clear

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

It makes more sense to have this labelled “deprecated” because we're gonna have a number of non-legacy deprecations looking forward.
That's an example of the proposed patch:

image.png (1×1 px, 164 KB)

@Volker_E I wonder if these legacy/deprecated tokens could simply be hidden in the demo as we hide the optional tokens (being visible just the decisions and just the non legacy/deprecated tokens).

@Volker_E if they can't be hidden, then I would use a Regular text with #AC6600 color.

About the "deprecated" name, not sure if this name it's the best option since we would be showing deprecated tokens in the demo and users could be confused.

@Volker_E I wonder if these legacy/deprecated tokens could simply be hidden in the demo as we hide the optional tokens (being visible just the decisions and just the non legacy/deprecated tokens).

The reason for not hiding them is that we also need to expose users with former decisions in order to inform about progress and also visualize the old ones. For example in the case of opacities, it's reasonable to have those listed as they are so widely used and necessary in non-Codex environments like OOUI to have icons aligned to our component guidelines.
It's also good practice at Wikimedia to not use deprecated things and with the comment we guide fellow devs to speed up updating old interfaces with new replacement tokens. “Deprecated” is the common term here.
It seems more productive to show them and mark them, than to hide them.

On the styling, we can make them non-bold, I was under the impression that deprecation is more important than anything else in this case. But with the warning styling it makes sense.
On #ac6600, our messages use black text on light yellow background for warnings, I'd use the same style…?

Have updated the latest patch with non-boldened warning message and a prefix of the comment.

I also like the combination of #ac6600 against the light yellow background (#FEF6E7), but unfortunately this wouldn't present enough contrast for normal text (4.2:1).

I think the terminology and reasons to display the label are justified, and would just make a nitpicky visual suggestion: should we make the deprecated labels similar in shape to the code value "chips"? That'd mean applying a padding of 4 and 8px, and a border radius of 2px to them. (This also contributes to make them more prominent)

The reason for not hiding them is that we also need to expose users with former decisions in order to inform about progress and also visualize the old ones. For example in the case of opacities, it's reasonable to have those listed as they are so widely used and necessary in non-Codex environments like OOUI to have icons aligned to our component guidelines.

@Volker_E as you comment, these deprecated tokens are more from non-Codex environments so it doesn't have sense to me to find more deprecated tokens than normal tokens in this (and others) Codex demos. I think Codex demo should show the tokens that we want to use, and maybe inform in a subtle way that we have other legacy/deprecated tokens. The problem is that currently the deprecated tokens are at the same level and also they are more than the new ones.

@bmartinezcalvo Keep in mind, that we will use deprecated Codex tokens for projects outside Codex Vue components and patterns, as in OOUI (and use the Figma legacy tokens in OOUI Figma library as well possibly). So having them here fulfills several needs:

  • Ensuring all design decisions (normal and legacy ones) are found in a prominent place in order for designers and devs to look at the same thing when referring to a legacy token
  • Having a deprecation note on what this token should be transformed into
  • Visually showing the deprecated tokens, which simplifies work for designers/QA folks when verifying a token transformation patch

I'd suggest to move forward with this first approach right now (clarifying the open design questions on the deprecation label), it is already a strong improvement over the status quo and we can pull in more people for the question of showing or not showing deprecated tokens.

Change 819660 merged by jenkins-bot:

[design/codex@main] tokens, demos: Mark deprecated tokens loud and clear

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

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

[design/codex@main] tokens: Put deprecated tokens always at bottom

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

Volker_E renamed this task from Mark legacy design tokens loud and clear to Mark deprecated legacy design tokens loud and clear.Aug 4 2022, 3:54 PM
Volker_E updated the task description. (Show Details)

Change 820467 merged by jenkins-bot:

[design/codex@main] tokens, demos: Put deprecated tokens always at bottom

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

As already mentioned in the patch, it all looks good. All deprecated tokens are grouped at the bottom of their respective pages or groups in the visualization tables, which gives them less relevance. They're also clearly distinguishable thanks to the new label. There are, though, a couple of potential improvements we might want to consider:

  • We should find a way to prevent the following overlap between the "deprecated" label and the value:

Screenshot 2022-08-11 at 17.32.16.png (259×729 px, 36 KB)

  • There might not be a way around this due to technical reasons, but deprecated tokens are not always displayed as a group at the bottom because deprecated base tokens are displayed on top of component tokens in the composed tables:

Screenshot 2022-08-11 at 17.34.23.png (884×1 px, 118 KB)

(Pinging @Volker_E for visibility)

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

[mediawiki/core@master] Update Codex from v0.1.0-alpha.9 to v0.1.0-alpha.10

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

Change 823725 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.1.0-alpha.9 to v0.1.0-alpha.10

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

Hey @Volker_E. Regarding the first point in my comment above, we could consider placing the label inside the 'name' cell instead of inside the 'value' cell in the tokens table. This could help prevent the label from partially covering the tokens' values in some occasions. Let me know if I should create a separate task to capture that, so this one can move ahead in the board.

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

[design/codex@main] docs: Reposition deprecation “tag” of design tokens

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

Fair point, would it possibly be better to put it at bottom left now…? Still strong emphasis, while name is first thing you read.

image.png (622×1 px, 104 KB)

Or we put it directly underneath the name, but it's becoming more noisy like that…

image.png (596×1 px, 102 KB)

My patch above applies former.

(The position in the first example is not perfected yet, should be on one line with the Copy button vertically)

(The position in the first example is not perfected yet, should be on one line with the Copy button vertically)

The update solves the issue and looks fantastic :)

Change 836324 merged by jenkins-bot:

[design/codex@main] docs: Reposition deprecation “tag” of design tokens

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

It's not clear to me what to expect @EUdoh-WMF to check here or if it's a task that should jump directly to Product sign-off.
Possibly checking a few places like box-shadow tokens if there are still overlaps, or how it behaves (bonus item) on increased user font size – although we haven't had any requirements defined yet.

@Volker_E you are right about the overlap. This one is when I increased the zoom to 400% and above.

image.png (1×1 px, 152 KB)

I think to avoid this overlap (in extreme cases), one of your ideas would be functional, even if you mentioned it being quite noisy. What do you think? @SaraiSan

image.png (1×2 px, 638 KB)

Thanks @EUdoh-WMF, good to have that captured. As this issue is first visible at 300% zoom level (the 7th of 9 zoom in levels) and the copy button is still functional. The solution is less noisy than the directly after token name one and it's a high edge case, I pledge for moving forward with the found solution.

Volker_E claimed this task.
Volker_E added a subscriber: DAbad.

Became part of Codex in v0.1.0-alpha.10. Repositioning following in next release, but as minor change no blocker for resolving.

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

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

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

Change 849191 merged by jenkins-bot:

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

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