Page MenuHomePhabricator

Clarify technical choice with product team needs for design tokens/variables
Closed, ResolvedPublic


CSS/LESS/post-/preprocessor variables definition or JSON for design tokens to use in apps?

2021 with Vue.js UI component library in the making, it's time to revisit the technological choice.

Foundation history to status quo:
In order to unify our web user-interfaces (UI) accordingly to Wikimedia Design Style Guide, WikimediaUI Base variables as CSS and LESS variables were put into place.

We've decided to go with CSS/LESS variables as LESS is supported by ResourceLoader and variables were already used, but not centralized in 2017. CSS variables were the future-facing choice and CSS post-processors were on the rise too. Wikimedia-Portals is an exemplatory user of CSS.

JSON has been chosen in Salesforce design system as it provides design tokens for native platforms as well.

In the past, Wikimedia Foundation product design has not shared a lot of design “tokens” between web and the native apps, iOS, Android. Neither with newest addition KaiOS. We've set out to follow native human-computer-interaction recommendations of the platform.


  • How is the current usage of something comparable to design tokens in the various platforms?
  • Are there foreseeable future changes to the need?
  • Is this an issue that is worthwhile tackling on higher level?

Event Timeline

Hey @Volker_E to be clear, @schoenbaechler should answer this, then the engineers? Also is this time sensitive?

@JTannerWMF Sorry, I have not seen your answer above until now. Yes, it's time-sensitive, best possible a rough answer until Monday evening next week, hence my direct outreach on Slack channel with @Dbrant's answer.

@AMuigai/@SGautam_WMF and @JMinor/@cmadeo as well please.

Sorry to be late to this conversation, but we're having a bit of a struggle understanding what the ask and implications are.

Are you asking if there is a preference or advantage for adopting design tokens in replacement of CSS for shared style definitions?

Or is the goal so that there will be one source of truth and changes upstream would more easily "go live" into the apps without us having to manually push an update?

From my perspective, I think we're happy to adopt whatever definitions system makes sense at a system level, and having a shared source of reference for mapping from semantic names to colors/styles. But we don't have any capacity to transition to a new system that affects both the native and web renderers, and so I'm not sure how this would actually impact us.

@cmadeo is going to grab some time with you to make sure we understand the ask before we go too opinionated though.

For clarification:
Currently we're providing CSS/Less mirrored stylesheet variables representing the design tokens like our Foundation color palette (CSS example, Less example).

Is there any immediate or strong mid-term benefit for the apps to have those tokens codified in JSON as well?

Thanks, that clarifies things a lot! More meaningful feedback coming soon...

I'm a bit unclear if the suggestion is that we package a JSON file in with the apps, or that the apps download a JSON file dynamically from a server (so that colors can be changed without a release of the app).

Either way, unless we're going to start regularly changing colors, I don't think there is a real advantage to the apps using a JSON version of this. Both iOS and Android have color schemes set up in ways more typical for their platforms. Unless the values are going to be frequently changing, I'm not sure it's worth the overhead (both in code and moving further from platform standards) to have a script turn JSON/CSS into colors for the mobile apps.

That said, we're supportive of platform standardization for MediaWiki. If there are other reasons why it's important for the mobile apps to adopt this style, we're very open to a discussion.

@MattCleinman I don't think that changing colors without a release (and clear notification to users what's happening) could be of strong interest from a product owner perspective. But that's you all to decide.
The question here is more about: Do we, as app team, want to rely on a centralized collection of Wikimedia user-interface fundamental design tokens (colors were just one example, typography would be another)? And if so, do we need JSON format for it to be seamlessly implementable? Or is the current stylesheet way acceptable?

JSON would be an overhead to design system team and would be harder to navigate or even extend by other designers. Apps are the only place currently that I can identify where JSON might have a clear advantage over stylesheet vars/tokens.

Do we, as app team, want to rely on a centralized collection of Wikimedia user-interface fundamental design tokens (colors were just one example, typography would be another)?

If we're able to answer "no", I think we'd go with that.

Of course, the style of the article content within the apps comes via CSS that Product Infrastructure includes - that is out of our hands. What we're talking about is the non-article chrome of the apps.

The chrome of the apps have colors defined in the files linked above. Since the apps can't use CSS/JSON color schemes on their own, it seems like unnecessary overhead to have a script that converts design tokens to a format the apps can use - when instead we can keep those files up to date in the rare times they change.

(I'm unaware of historically difficulties keeping them up to date, but also I'm fairly new to Wikimedia. If there are some historical reasons we don't think the manual option is a good choice, we're happy to discuss.)

[from a Slack thread]
The apps have pretty different ways of specifying/consuming design tokens, so I'm not sure that specifying them in JSON format (and/or pulling them from LESS files) would be useful at the moment. As long as they are described on a well-known Wiki location, that should be sufficient for us. Additionally, each app platform has its own design requirements and constraints that might need to deviate from the prescribed upstream tokens.

Volker_E triaged this task as High priority.Aug 2 2021, 9:00 PM
Volker_E claimed this task.

Thanks @Dbrant, @JMinor and @MattCleinman for your inputs.

With the feedback provided I'll set this to resolved with stylesheet variables to be a sufficient choice for our current and forecasted usage (while assuming that KaiOS is out of the game for higher level tokens usage due its limited technical environment).

Hello @Volker_E, sorry for the late reply on this. You're right about exclusion of KaiOS due to its limited technical environment.

Thanks @SGautam_WMF for that ensuring clarification as well!

While discussing this task and subsequent comment thread with WMDE folks, we wondered whether JSON was being considered here as an output format for design tokens instead of as the raw, portable format in which the system styles would be documented. With the risk of if being redundant, I thought it wouldn't hurt to add a clarifying comment:

What storing design system tokens in JSON allows is being able to obtain several output formats from a single agnostic source. How we do this is in the context of the WiKit design system is by using Style dictionary. This tool allows us to obtain our styles in the needed format (.scss variables in our case), and it could also be used to obtain a styling output that could be used in native platforms directly (see Style dictionary's available output formats). Using a set-up such as this would allow extending the system visual foundations to the apps, without the need to maintain the manual process described in some comments above, plus no custom scripts needed.