Design Systems Team

Mission
In collaboration with Wikimedia Foundation teams, partners and volunteers, the Design Systems Team develops an overarching strategy for frontend design and engineering across Wikimedia. This includes building and maintaining a design system platform for wikis that provides shared services of tools and guidelines for building user interfaces in an efficient, scalable, and equitable way.

This work supports audiences that are critical to developing new knowledge experiences by ensuring that they are successful in creating, maintaining, and extending frontend features across Wikimedia with consistency and ease.

Vision
Provide a comprehensive, reusable, extensible way to design and build frontends on Wikimedia platforms by following a universal Design Style Guide and a shared development kit that codifies the visual and experience principles and guidelines in a library of user-interface (UI) components.

Current state of frontend development
 * Many user-interface libraries used by different teams and projects
 * Redundant effort for designers and engineers
 * Inconsistent designs
 * Inconsistent standards for contribution
 * Challenging to onboard
 * UIs depend on coupled backend logic

Ideal future-state of frontend development
 * Less feature redundancy
 * Consistent user experience across all Wikimedia projects
 * Accessible and multilingual by default
 * Standardized browser and device support
 * Faster onboarding
 * Faster software upgrades
 * Systems thinking: teams make an impact outside of immediate focus area

Wikimedia Design System and Codex UI Library
The Wikimedia Design System is the place where all of the components and patterns that designers use to create products are systematically organized, in such a way that they are easy to find, modify and create new parts. The design system is grounded in a set of principles and guidelines designed with for consistency, efficiency, web accessibility and internationalization by default.

Codex is the frontend development toolkit used for implementing the Wikimedia Design Style Guide in code. Codex provides engineers with UI components that are built in JavaScript (Vue.js), with design tokens to store data for design values, and user-facing documentation.

Frontend Technology
Wikimedia's medium-term Platform Evolution plan set out to prioritize modern engineering practices, performance, and ease-of-use for contributors of varying experience levels. As a result, the Design Systems Team organized the Vue.js Developer Summit 2021 which led to the decision to adopt Vue.js as the official programming framework for MediaWiki.

Contribution Guidelines
We welcome contributions from everyone! There are several ways to contribute:


 * Adding or commenting on tasks in our project management system, Phabricator (links below)
 * Contributing to the design process
 * Suggesting new components and design tokens
 * Writing and submitting code
 * Reviewing code
 * Updating and expanding library documentation

Contributions to Codex are covered by the Code of Conduct for Wikimedia technical spaces.

How to stay up-to-date
To keep all those interested in using or contributing to Codex up-to-date on topics of design, development, roadmaps, and releases, the Design Systems Team will:


 * Use Phabricator to publicly track the work, giving others the opportunity to subscribe to tasks, add comments, or claim tasks.
 * Keep our team page up-to-date with information about our work and how to contact us
 * Include release notes with every release and send minor and major release summaries out to the following mailing lists:
 * Wikitech-l, list for discussing the technical aspects and organization of the Wikimedia projects
 * design.public, list for discussing design updates
 * Document technical decisions about the library in Codex's architecture decision record (ADR) section.

Task tracking
Tasks are tracked in Phabricator. We use three different Phabricator workboards:


 * Design-Systems-Team: used to triage, sort, prioritize, and refine tasks that the Design Systems team and contributors will work on.
 * Design-Systems-Sprint: used to track active works-in-progress from Research > Design > Development > Testing > Release. As a contributor, you are welcome to track your work related to the Design System on this board as well—just remember to keep the task in the appropriate column that reflects its status.
 * Codex: used to indicate that a task is related to Codex. We do not track task status here.

How do I know the status of something?
Check the Codex, Design-Systems-Team, and Design-Systems-Sprint workboards in Phabricator to see if a task exists for that work (for detailed Phabricator search tips, visit this page). If so, the task will be in the column that represents its current status. If not, you can create a task (see below) or contact us (see the Design Systems Team page on mediawiki.org)

How do I request a feature?
You are welcome to create new tasks with the #Codex and #Design-Systems-Team tags. New tasks will go into our "Needs Triage (Incoming Requests)" column and will be triaged regularly. Please remember that Codex is maintained by a nonprofit—we won't be able to meet all feature requests, and it might take time to get to your request.

To request a new component, please fill out the [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?title=%5BComponentName%5D%3A%20Add%20%5BComponentName%5D%20component%20to%20Codex&description=%23%23%20Background%0D%0A%0D%0A%2F%2FNOTE%3A%20%20When%20creating%20a%20component%20task%2C%20please%20try%20to%20fill%20out%20the%20entire%20Background%20section.%20The%20rest%20of%20the%20task%20description%20can%20be%20populated%20later.%2F%2F%0D%0A%0D%0A%23%23%23%20Description%0D%0A%0D%0A%2F%2FAdd%20a%20brief%20description%20of%20this%20component%2F%2F%0D%0A%0D%0A%23%23%23%20User%20stories%0D%0A%0D%0A%2F%2FAdd%20at%20least%20one%20user%20story.%2F%2F%0D%0A%0D%0A%23%23%23%20History%0D%0A%0D%0A%2F%2FDescribe%20or%20link%20to%20prior%20discussions%20related%20to%20this%20component%2F%2F%0D%0A%0D%0A%23%23%23%20Known%20use%20cases%0D%0A%0D%0A%2F%2FDescribe%20known%20use%20cases%20for%20this%20component%2C%20including%20the%20project%2C%20team%2C%20and%20timeline%2F%2F%0D%0A%0D%0A%23%23%23%20Existing%20implementations%0D%0A%0D%0AThese%20artifacts%20are%20listed%20for%20historical%20context.%20The%20figma%20spec%2C%20linked%20below%2C%20is%20the%20source%20of%20truth%20for%20the%20new%20component.%0D%0A%0D%0A**Wikimedia%20community%3A**%0D%0A-%20**Design%20style%20guide%3A**%20%2F%2Fadd%20%5B%5B%20https%3A%2F%2Fdesign.wikimedia.org%2Fstyle-guide%2Findex.html%20%7C%20Design%20Style%20Guide%20%5D%5D%20link%2C%20if%20applicable%2F%2F%0D%0A-%20**OOUI%3A**%20%2F%2Fadd%20the%20relevant%20OOUI%20widget%20name(s)%20here%2C%20if%20applicable.%20See%20%5B%5B%20https%3A%2F%2Fdoc.wikimedia.org%2Foojs-ui%2Fmaster%2Fdemos%2F%3Fpage%3Dwidgets%26theme%3Dwikimediaui%26direction%3Dltr%26platform%3Ddesktop%20%7C%20OOUI%20demos%20%5D%5D.%2F%2F%0D%0A-%20**Vue%3A**%20%2F%2Fadd%20any%20existing%20Vue%20implementations%2C%20if%20applicable.%20See%20%5B%5B%20https%3A%2F%2Fwww.mediawiki.org%2Fwiki%2FVue.js%23Projects_using_Vue.js%20%7C%20Projects%20using%20Vue.js%20%5D%5D.%2F%2F%0D%0A%0D%0A**External%20libraries%3A**%0D%0A-%20%2F%2FAdd%20links%20to%20any%20examples%20from%20external%20libraries%2F%2F%0D%0A%0D%0A---%0D%0A%0D%0A%23%23%20Codex%20implementation%0D%0A%0D%0A%23%23%23%20Component%20task%20owners%0D%0A%0D%0A-%20Designer%3A%20%2F%2Fadd%20the%20main%20designer's%20name%2F%2F%0D%0A-%20Developer%3A%20%2F%2Fadd%20the%20main%20developer's%20name%2F%2F%0D%0A%0D%0A%23%23%23%20Open%20questions%0D%0A%0D%0A-%20%2F%2FList%20any%20current%20open%20questions%20here%2F%2F%0D%0A%0D%0A%23%23%23%20Design%20spec%0D%0A%0D%0A%2F%2F%20Once%20a%20component%20spec%20sheet%20has%20been%20created%20in%20Figma%2C%20remove%20the%20note%20stating%20that%20the%20spec%20is%20missing%20and%20link%20to%20the%20spec%20below.%20%2F%2F%0D%0A%0D%0AA%20component%20spec%20sheet%20has%20not%20been%20created%20yet.%0D%0A%0D%0A%7C%20Component%20spec%20sheet%20%7C%0D%0A%0D%0A%23%23%23%23%20Anatomy%0D%0A%0D%0A%2F%2FDesigner%20should%20list%20the%20structure%20and%20properties%20of%20the%20component.%2F%2F%0D%0A%0D%0A%23%23%23%23%20Style%0D%0A%0D%0A%2F%2FDesigner%20should%20list%20the%20visual%20features%20of%20the%20component.%2F%2F%0D%0A%0D%0A%23%23%23%23%20Interaction%0D%0A%0D%0A%2F%2FDesigner%20should%20list%20interaction%20specifications.%2F%2F%0D%0A%0D%0A%23%23%23%23%20Documentation%0D%0A%0D%0A%2F%2FDesigner%20should%20describe%20how%20the%20component%20should%20be%20documented%2C%20including%20configurable%20and%20standalone%20demos.%2F%2F%0D%0A%0D%0A---%0D%0A%0D%0A%23%23%20Acceptance%20criteria%0D%0A%0D%0A%23%23%23%20Minimum%20viable%20product%0D%0A%0D%0AThis%20task%20covers%20the%20minimum%20viable%20product%20(MVP)%20version%20of%20this%20component.%20MVP%20includes%20basic%20layout%2C%20default%20states%2C%20and%20most%20important%20functionality.%0D%0A%0D%0A**MVP%20scope**%0D%0A-%20%5B%5D%20%2F%2FList%20all%20parts%20of%20the%20MVP%20scope%20for%20this%20component%2F%2F%0D%0A%0D%0A**Design**%0D%0A-%20%5B%5D%20Design%20the%20Figma%20spec%20sheet%20and%20add%20a%20link%20to%20it%20in%20this%20task%0D%0A-%20%5B%5D%20Update%20the%20component%20in%20the%20%5BFigma%20library%5D(https%3A%2F%2Fwww.figma.com%2Ffile%2FKoDuJMadWBXtsOtzGS4134%2F%25E2%259D%2596-Codex-components%3Fnode-id%3D1891%253A4420%26viewport%3D287%252C338%252C0.28).%20%2F%2FThis%20step%20will%20be%20done%20by%20a%20DST%20member.%2F%2F%0D%0A%0D%0A**Code**%0D%0A-%20%5B%5D%20Implement%20the%20component%20in%20Codex%0D%0A%0D%0A%23%23%23%20Future%20work%0D%0A%0D%0A-%20%2F%2FIf%20applicable%2C%20list%20future%20work%20that%20should%20be%20done%20for%20this%20component%20after%20the%20MVP%20is%20implemented%20as%20part%20of%20this%20task.%20You%20should%20open%20new%2C%20standalone%20tasks%20for%20all%20future%20work.%2F%2F&projects=Codex new component task template].

How do I follow Design System ongoing work?
Create a Phabricator account and add yourself as a subscriber to a task to get notified when updates are made.

How do I contribute to a task?
Great! Create or claim a task as soon as you decide to work on it. This will help avoid overlapping, duplicate, or conflicting work. If you're creating a task, add as much detail as you can about the scope of the task: for example, what needs to be completed before the task can be considered "done"?

Team

 * Anne Tomasevich, Senior Software Engineer
 * Bárbara Martínez Calvo, Senior User Experience Designer
 * Christopher Ciufo, Senior Product Manager
 * Eric Gardner, Senior Software Engineer
 * Lauren de Lench, Senior Technical Program Manager
 * Nat Hillard, Senior Engineering Manager
 * Roan Kattouw, Principal Software Engineer
 * Volker E., Lead User Experience Engineer, Design System and Readers Web


 * Sarai Sánchez, User Experience & Product designer (team member from Wikimedia Deutschland)

Frequently Asked Questions (FAQs)
Please visit Design Systems Team/FAQs.

History of user-interface libraries and frameworks in MediaWiki
There have been several attempts for providing consistent user-interface features over the 20 years of MediaWiki (MW).

The first “skin”, Monobook was added in MW 1.3 (2004), and featured a first technical design document.

All of the following “libraries” were either part of MediaWiki core itself or deployed together.

jQuery was introduced in 2009 and with MW 1.16, jquery.ui was added around the same time as the Vector skin in order to provide a new and improved editing interface. It started with dialog component for the 2010 wikitext editor. While it was not announced as a standard user-interface library, it became part of several extensions in connection to the 2010 wikitext editor, such as CodeMirror and CodeEditor. Wikidata was intentionally built with jquery.ui due to a lack of standardization. Its simplicity also became popular with gadget authors. The 2010 wikitext editor, but also PageTriage are still widely-used extensions. jQuery.ui was deprecated in MW 1.29 for OOUI.

Development until this time was mainly driven by technical and feature-specific needs. Design standards were not enforced Foundation-wide. That is the background of yet another framework, Backbone, being chosen for PageTriage back then.

MediaWiki UI was initially created by the Design team in 2013 (project title “Agora”), and mainly focused on simple form elements and the MobileFrontend, user login form, and Flow extension. It aimed for being a Bootstrap equivalent, but for MediaWiki. At that time, OOUI was seen as too complex to adapt from its desktop-first origin, and too large in size to be usable for the new mobile Wikipedia architecture. Its CSS class-based approach quickly hit limitations with higher complex components (e.g. date picker, but also editing interfaces) and also faced critique for providing abilities for misuse in gadgets/user scripts which would provide more user experience and consistency problems in the long run.

OOUI (“object-oriented user-interface”) had originally been designed around a specific product, VisualEditor, in 2011, following modern coding practices at the time with its object-oriented JavaScript paradigm. It became a separate library in 2013 and was decided to become the default library at the Foundation in 2014. Later, the Product Design team had been assigned to generalize it further and adapt it for mobile use. From 2016 on, development was focused to be fully in sync with the principles of the the Design Style Guide (formerly “WikimediaUI Style Guide”) in its default theme “WikimediaUI”. The Design Style Guide also came into place in late 2016.

Through all of this the Web evolved. In 2020 with new technology and architecture requirements and abilities for modern Web, the Foundation began working on new user-interface library based on Vue.js. Read more about the motivations and requirements that lead to Vue.js in the underlying RFC. The initial project and scope was for the Desktop Improvements project. Part of this work was an important user-experience improvement in an high-visibility area, the new TypeaheadSearch component. The first prototypical library WVUI (“Wikimedia Vue UI”) was centered around the goal of bringing this component to production.

Participants from front-end teams across the Foundation and from Wikimedia Deutschland came together at the Vue.js Developer Summit 2021, organized by the Design Systems Team (DST). The summit aimed to decide on a number of architectural considerations, such as which version of Vue to build upon, and how to deal with IE 11 support or the use of Typescript and design tokens. It has resulted in a joint agreement for a new multi-team effort driven by DST, including findings and code from WVUI.