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:
- Enable users to apply global visual styles that are independent of any single component: typographic rules, responsive breakpoints, grid systems, link styles, etc.
- 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