Page MenuHomePhabricator

Tokens: Consider whether decision tokens should depend on one another
Open, MediumPublic


Right now, when we produce Codex design tokens in our various formats, every "decision token" that gets exported is independent from the others. We also organize our tokens according to CSS properties generally. This means that we tend to have a lot of duplicated values in the final output.

For example, the Wikimedia UI theme of Codex (the default theme) defines its "progressive" color as #36c. This value appears 14 separate times in the LESS version of our tokens.

@color-progressive: #36c;
@color-progressive--focus: #36c;
@background-color-progressive: #36c;
@background-color-progressive--focus: #36c;
@background-color-input-binary--checked: #36c;
@border-color-progressive: #36c;
@border-color-progressive--focus: #36c;
@border-progressive: 1px solid #36c;
// ...etc

Similar things happen for base color, destructive color, etc.

Now that we are introducing alternate color modes (which override certain color values), I think that it is worth asking whether this method of organization is desirable.

I would argue that supporting night mode and other related customizations would be easier and less error-prone if we made it so that some tokens derived from others in the final output (not just in the token source files).

The "progressive" color is intended to be #36c across all these different CSS properties. Why not introduce a set of "master" tokens that represent the main palette of colors, which other tokens would derive from? Having to keep track of a large number of variables which are separate but which have an implied connection to one another is not great for an authoring experience.

The Bulma design kit follows such an approach to support theming (both in SASS and in CSS). We may want to consider introducing something similar in Codex.

Acceptance Criteria
  • DST engineers and designers discuss what behavior Codex should have here
  • Document it (ADR?) and file any necessary follow-up tasks

Event Timeline

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

[design/codex@main] tokens: consolidate references

I should note that if we choose to do this, implementation would require re-organizing our tokens somewhat (designating one of the decision tokens as the primary source for the "progressive" color, another for the "destructive" color, another for base font size perhaps, etc). Then we'll need to implement a custom version of StyleDictionary's outputReferences feature that can understand the distinction between option tokens and decision tokens.

CCiufo-WMF triaged this task as Medium priority.Apr 1 2024, 4:58 PM