Page MenuHomePhabricator

Distribute design system styles as part of Codex
Closed, ResolvedPublic5 Estimated Story PointsSpike


Background and goal

This task is inspired by the concept of Atomic Design.

Codex (which can be seen as an implementation of the Wikimedia Design System) currently publishes low-level design tokens and high-level JS components (which are built on top of these tokens). This task is a proposal to add a new "intermediate" level to be distributed as part of our library: styles. Here's how these levels would fit together:

  • Tokens: values representing individual design decisions
  • Styles: groupings of tokens that implement a defined visual style for some element
  • Components: interactive UI elements that possess both appearance (defined by tokens and styles) as well as behavior (defined by JS).

Each level builds on what comes below it, but each one could also be used independently. Tokens can be consumed by developers building UIs in other platforms (iOS/Android for example). Components are of course used to build UIs for various features. By releasing a set of style resources as part of Codex (CSS stylesheets, LESS mixins, or something similar), we can support two important use-cases:

  1. Enable users to apply global visual styles that are independent of any single component: typographic rules, responsive breakpoints, grid systems, link styles, etc.
  2. Support users who need to provide non-JS interfaces for whatever reason (fallback UI, performance needs, etc) so that they can easily align their HTML UIs with the design system. Server-rendered form inputs, buttons, cards, etc. would appear visually identical to their Vue-based analogues.

Potential implementation

There are several ways we could do this:

  • Provide CSS style-sheets that target basic elements (link tags, headings, paragraphs, etc).
  • Provide LESS mixins that would collect a group of tokens together (colors for various link states, for example) but leave the consuming developer responsible for targeting.
  • LESS mixins could also be used internally (using a button mixin to style the CdxButton component, etc).

Note, that some of those style rules may need to be MediaWiki-aware (for example, a rule for “Red Link” visual styles that targets whatever "missing link" class that the MW parser applies to its output).

Next steps

  • Decide on our preferred solution:
    • Codex will provide users with some LESS mixins that correspond to global visual styles and certain simple components (buttons, links, text inputs, others TBD). These LESS mixins will contain all necessary style rules and tokens, but they will not make any assumptions about which elements on the page should be targeted. That decision can be made by the consumer.
    • We will decide which Codex components will get a LESS mixin implementation on a case-by-case basis; this will be a limited subset of the Codex JS components (though there will also be a few elements like Links that will only be implemented as LESS mixins).
  • Decide any implementation questions that come from that solution (how to package/distribute styles, how we want to document them, etc).
    • Published LESS mixins will need to be documented appropriately in the Codex Docs site
    • We may want to provide a CSS stylesheet that applies all Codex global styles to the base elements on the page
  • Publish this decision as an ADR in the Codex docs
  • Create sub-tasks for any necessary follow-up work

Event Timeline

From T314086#8120027:

I personally would defer from this approach and rather offer Codex tokens (via the Codex library in MediaWiki for example) being able to be consumed independently from technical framework.
A stylesheet makes already a number of assumptions, like selectors used, that would be more problematic to implement, to maintain and hinders adoption.

Codex tokens have a number of advantages:

  • They can be applied anywhere including non-stylesheet based environments like apps, or more easily in different stylesheet flavors (CSS, pre-processors)
  • They are simpler centrally maintainable
  • In pre-processors/build steps, they're only output when used, which is a huge performance advantage

And @egardner's response taking on some comments by @Catrope in a private chat:

My concern is that there may be cases where multiple tokens need to be used together to achieve the correct visual style – for example links need multiple colors for all the various states, etc. If end-users must track down all the correct tokens one-by-one to create the correct style on their end, it creates opportunities for inconsistencies to creep in.

Maybe distributing LESS mixins (something @Catrope had suggested originally) would be a good solution here – then we can still avoid making assumptions in terms of selector rules, but we can package a group of tokens together to make things easier on the consumer. Need a button? Just drop in the "button" mixin. Same goes for basic text styles, links, and (eventually) responsive layout rules.

I think mixins can be a good choice, but will also be the exception and not the rule. Moreover they also need to consume Codex tokens to fully align with our design system in the making.

Based on team discussion today, I'm going to promote this task into a sub-task of T314082: Design System Infrastructure Capabilities Scoping. Let's decide how we want to proceed with this work (and what the priority should be) in the near future, as part of the team's roadmap.

egardner renamed this task from Distribute design system global styles as part of Codex to Distribute design system styles as part of Codex.Aug 4 2022, 6:20 PM
egardner updated the task description. (Show Details)
Restricted Application changed the subtype of this task from "Task" to "Spike". · View Herald TranscriptAug 16 2022, 4:20 PM

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

[design/codex@main] [WIP] Parametric Button LESS mixin

We discussed this in yesterday's engineering enclave meeting. It sounds like we have a consensus on providing at least some public LESS mixins to consumers of Codex. For some components it will make sense to provide a LESS version that can be used without JS (for example, wanting to display a consistently-styled button or text input on something like a login page, where we want to keep things as simple as possible). For other components it probably will not make sense to provide a no-JS version. This will need to be decided on a case-by-case basis.

This approach will also be useful for global visual styles – headings, typography, grids, etc. These things don't really need JS components. Codex Links (T313507: [SPIKE] Create scope for Link MVP) will be another good use-case for this approach.

By providing the styles as LESS mixins, we allow the consumer to choose which elements they should apply to. LESS is available everywhere in MediaWiki so there should be no barriers to using this in production. In the future, we may also provide a basic CSS stylesheet that applies global visual styles to base elements (all headings, body text, links, etc). But this can be decided later and we should have a clear use-case in mind before we create such an asset.

One follow-up question is: how will we document which LESS "components" are available and how to use them? We will probably want to create a new section of the Codex docs site to provide this information. This should be handled in a follow-up task.

September 1, 2022 Review Session:

  • Engineering enclave take-away - okay with concept of distributing less mix-ins
    • compiles down to CSS but is it's own language
    • can compose style rules, decoupling the idea of a link or button from where the design is going to go (aka markups, css, etc.)
  • Up to other people how they will apply to what they are building
  • this solution can be very incremental
    • only do this for a small subset of global visual styles
  • Codex is a bunch of pre-built components, but if you have other things that are floating or not part of an existing component they can grab reusable styles
  • designers would not have to do any extra work, this is purely at the engineering level.
  • Part of reason why we raised concern around links, is that tempting way to deal with this is to apply universal standards, because we use elements in different ways and would limit flexibility
  • operate at a global page level
  • what this is about in terms of what we are delivering:
        • consists of tokens
        • a collection of visual styles (made up of tokens) that when combined together have a unique meaning/value - which would be this work
      • component
    • Potential items that would fall into this: buttons, links, grids

Next Steps & Action Items:

    • Come up with name "Codex visual styles"
    • Publish ADR - Detail what is the process to add another "Codex visual style"
      • start with javascript component
      • then DST reviews and identifies if this may want to implement as a "html" + "CSS-only"
    • Implementation for Links
  • We could do a quick patch for links - add a link component to demo page and note that this is not a JS feature
  • Spin out future tasks for:
    • documentation

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

[design/codex@main] docs: ADR 04 - Visual styles as Less mixins

We should also think about how to expose these Codex internal mixins in MediaWiki.
One of the issues of the past was that MediaWiki core provided its mixins and OOUI duplicated them internally again. From my current reading that would be also the case now, but in three places.

The Grid implementation seems like a really tempting candidate for mixins.

Change 829079 merged by jenkins-bot:

[design/codex@main] docs: ADR 04 - Visual styles as Less mixins

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

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

From my point this is ready for sign-off.
Further mixin work is done in respective tasks and patches or do you want to keep it open for the parametric Button mixin in order to have 1 example implementation @egardner?

Change 831947 merged by jenkins-bot:

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

ldelench_wmf set the point value for this task to 5.Sep 19 2022, 3:35 PM

I think this is basically done – we have a task in the works for the Link component, which is the first concrete thing that will come out of this decision.

There are also tasks to improve the docs site to make it easier to introduce non-Vue "component" pages.

Going to go ahead and close this since the ADR was included in the last Codex release.

Change 827603 abandoned by Eric Gardner:

[design/codex@main] [WIP] Parametric Button LESS mixin


This work has been superseded by and the CSS-only components project more generally.