Design Systems Team/WMDE-WMF task force decisions

Overview
A task force consisting of Designers and Developers across WMF and WMDE met each day between October 4, 2021 and October 7, 2021 to make decisions and collaborate on a shared component library which was decided to be called Codex. This task force emerged from the Design Systems Team/Vue.js Developer Summit 2021 and the Design Systems Team/Vue.js Design Workshop 2021; each of these earlier events happened in August, 2021. The workshop and summit resulted in these decisions including the decision to create a task force to make decisions about the shared component library.

Codex
The new library will be a monorepo named Codex, inspired by the term for an ancient book. Codex will be a toolkit for building user interfaces within the Wikimedia Design System. The monorepo will include packages for:


 * 1) Documentation, including design token visualization and component demos
 * 2) Design tokens
 * 3) Vue components

The repository will be housed in Gerrit, although we may eventually move it to GitLab.

Design Tokens
Design tokens will be formatted in JSON, rather than a technology-specific format, so we can support many formats moving forward. Codex will use Style Dictionary to convert the tokens into various formats for use.

Tokens will be organized into three layers:


 * 1) Base: these are primitive visual styles, e.g.
 * 2) Alias: these values express design intent, e.g.
 * 3) Component: these are component-specific values, which should be the exception: most values used on the component-level should be alias tokens

TypeScript
Code in the Vue components package will be written natively in TypeScript. We explored the idea of writing type definitions in JSDoc comments, but decided to prefer the more popular and well-documented TypeScript approach.

We will create documentation to help library developers learn TypeScript and to document solved problems (especially related to using TypeScript with Vue).

CSS processing
Styles in Codex will be written in native CSS, without a pre-processor, and with PostCSS for CSS transformations. This decision is tentative while we explore how feasible it is in terms of the features we want and the browser coverage we must provide.

Demo tool
Codex will use VitePress as its demo tool for documentation, design token visualization, and Vue component demos. This decision is tentative while we explore the maintenance costs of using a lightweight tool (versus a feature-heavy tool like Storybook). If we determine that the maintenance costs outweigh the benefits (faster, fewer dependencies, better demonstration of Vue components, more focus on documentation), we will revert back to Storybook