Change Details

== Background and goal Providing Wikimedia Movement users with global styles from the Design System beyond the technical fundament of the Codex toolkit, the Vue based components and patterns. The [[ https://design.wikimedia.org/style-guide/ | Wikimedia Design Style Guide ]] has rules for things that are not components (basic typographic styles; the grid system fall into this category). We would't want to have components for heading or body text – we'd provide the smallest design decisions for those. This task is about how to handle this in #Codex to expand the use of our design system styles for a much bigger number of Wikimedia teams and users, == Developer notes Based on a collection of notes by @egardner et al: **Evaluate** - Should we provide an optional base-level stylesheet (informed by the appropriate design tokens) that folks can include in their projects whether or not they are using Vue components (or JS at all)? - Is tokens package output as stylesheet variables as a base for a number of other technical solutions (other libraries, MediaWiki core) superior to a stylesheet? Note, that some of those style rules may need to be MediaWiki-aware (for example, a rule for redlink visual styles that targets whatever "missing link" class that the MW parser applies to its output).

== Background and goal This task is inspired by the concept of [[ https://bradfrost.com/blog/post/atomic-web-design/ | Atomic Design ]]. Codex (which can be seen as an implementation of the Wikimedia Design System) currently publishes low-level [[ https://doc.wikimedia.org/codex/main/design-tokens/overview.html | 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. We could provide CSS style-sheets that target basic elements (link tags, headings, paragraphs, etc). We could also 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 redlink visual styles that targets whatever "missing link" class that the MW parser applies to its output). == Next steps [] Decide on our preferred solution (do nothing, LESS mixins only, mixins plus global stylesheet) [] Decide any implementation questions that come from that solution (how to package/distribute styles, how we want to document them, etc) [] Publish this decision as an [[ https://doc.wikimedia.org/codex/main/adrs/overview.html | ADR ]] in the Codex docs

== Background and goal Providing Wikimedia Movement users with global styles from the Design System beyond the technical fundament of the Codex toolkit, the Vue based components and patterns. The [[ https://design.wikimedia.org/style-guide/ | Wikimedia Design Style Guide ]] has rules for things that are not components (basic typographic styles; the grid system fall into this category). We would't want to have components for heading or body text – we'd provide the smallest design decisions for those. This task is about how to handle this in #Codex to expand the use of our design system styles for a much bigger number of Wikimedia teams and users,This task is inspired by the concept of [[ https://bradfrost.com/blog/post/atomic-web-design/ | Atomic Design ]]. == Developer notesCodex (which can be seen as an implementation of the Wikimedia Design System) currently publishes low-level [[ https://doc.wikimedia.org/codex/main/design-tokens/overview.html | 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 Based on a collection of notes by @egardner et al:* **Components**: interactive UI elements that possess both appearance (defined by tokens and styles) as well as behavior (defined by JS). **Evaluate** - Should we provide an optional base-level stylesheet (informed by the appropriate design tokens) that folks can include in their projects whether or not they are using Vue components (or JS at all)?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. - Is tokens package output as stylesheet variables as a base for a number of other technical solutions (other libraries2. 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. We could provide CSS style-sheets that target basic elements (link tags, headings, paragraphs, etc). We could also 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, MediaWiki core) superior to a stylesheet?etc). Note, that some of those style rules may need to be MediaWiki-aware (for example, a rule for redlink visual styles that targets whatever "missing link" class that the MW parser applies to its output). == Next steps [] Decide on our preferred solution (do nothing, LESS mixins only, mixins plus global stylesheet) [] Decide any implementation questions that come from that solution (how to package/distribute styles, how we want to document them, etc) [] Publish this decision as an [[ https://doc.wikimedia.org/codex/main/adrs/overview.html | ADR ]] in the Codex docs