Page MenuHomePhabricator

Make Codex Color page less confusing in dark mode
Open, MediumPublic

Description

The Codex Color page begins with a note that some colors differ between light and dark mode, and that using design tokens ensures the right color will be used automatically. While this is a noble goal, in practice it’s still not uncommon to have to refer to the underlying hex codes; two use cases I’ve encountered several times are:

  1. Creating or reviewing Gerrit changes that replace hard-coded colors with design tokens, and checking whether the token matches the old hard-coded value or not.
  2. Creating or reviewing on-wiki changes that prepare a template, gadget or similar for dark mode by using the var( --token-name, #abcdef ) pattern, and checking whether the fallback matches the token value.

In both cases, if you’re looking at the Codex Color page in dark mode, you’ll be seeing the “wrong” token values there, and will create bad changes, be confused, and/or waste your time before realizing your mistake. This has happened to me at least four or five times now, and I’ve also seen it happen to others, e.g. @Nemoralis here on Commons. IMHO, experience clearly shows that the note at the top of the page is not enough to prevent this mistake from happening again and again, and we should find a better way to make the page less of a footgun.

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald Transcript

My suggestion would be to always make the page show both versions of the color token. The demo could be limited to just the “current” color, and the corresponding value could also be highlighted or shown more prominently than the alternative version, but IMHO shoving it in people’s faces like this is the best way to ensure that they’ll notice there are two versions of the token and they need to make sure to pick the right one.

stjn subscribed.

I agree that two colours should be either always listed or listed in night mode. See also T381433: Codex docs should have a ‘Copy as CSS’ button on my suggestion to solve these mistakes for good.

CCiufo-WMF triaged this task as Medium priority.Jan 20 2025, 7:15 PM
CCiufo-WMF moved this task from Inbox to Needs Refinement on the Design-System-Team board.
CCiufo-WMF added a project: Design.
CCiufo-WMF subscribed.

I can see how this can end up being a bit of a footgun. This page could start to get really messy if we show both versions of each color though, not to mention we'd need to do this on some of the other token pages as well. I'm not ruling it out though. I'd be interested in exploring other ways to better inform users that the colors and values they are seeing are based on the current color mode, or providing a more direct way to toggle/compare between modes.