Design System Team/WMDE-WMF task force decisions
This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on the information here being up-to-date. |
Overview
editA 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 System Team/Vue.js Developer Summit 2021 and the Design System 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.
Task force Schedule
edit| Monday Oct 4th 14:00-16:00, 16:30-18:30 | Design tokens (4 hours) |
| Tuesday Oct 5th 14:00-16:00, 16:30-18:30 | Name the shared library (30 min)
TypeScript (1.5 hours) CSS preprocessor (2 hours) |
| Wednesday Oct 6th 14:00-16:00 | Demo tool (1 hour)
Planning out implementation (1 hour) |
| Thursday Oct 7th 14:00-16:00 | Implementation and hand offs |
Decisions
editCodex
editThe 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:
- Documentation, including design token visualization and component demos
- Design tokens
- Vue components
The repository will be housed in Gerrit, although we may eventually move it to GitLab.
Design Tokens
editDesign 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:
- Base: these are primitive visual styles, e.g.
color-accent-50: "#36c" - Alias: these values express design intent, e.g.
background-color-progressive: color-accent-50 - Component: these are component-specific values, which should be the exception: most values used on the component-level should be alias tokens
TypeScript
editCode 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
editStyles 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. Update: we have decided to go back to using Less for reasons covered in this comment.
Demo tool
editCodex 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