Design System Team/Migration to Codex

Codex is intended to eventually replace OOUI, jQuery UI, and any other user-interface libraries in use in Wikimedia code. This page explains how and in which phases the Design System Team plans to do and foster this migration.

Desired final state

All new features, and features under active development, are built with Codex. Most features that are in maintenance mode have been migrated to Codex. Some code still uses OOUI, in cases where the benefits of migration don't outweigh the effort required, but ideally those cases are rare. jQuery UI and other user-interface libraries are removed completely.

High-level migration plan

Phase 0: Build out necessary components and infrastructure (we are here)

The Design System Team is currently focused on building out Codex enough so that it can be used to develop new projects, building the infrastructure teams need to use Codex (e.g. server-side rendering), and clarifying policies regarding when Vue can be used. Some projects already use Codex, and the Design System Team supports teams who want to use Codex, but it's not yet feasible for all new development to use Codex.

Phase 1: All "greenfield" new development uses Codex

Once Codex is usable for most projects, the Design System Team plans to focus on enabling new development first, because every new project that is started using something other than Codex creates more migration debt that will need to be paid down in the future. The Design System Team will provide support to projects that use Codex, and will work with them to create or upstream new components they might need.

Phase 2: Existing code under active development is migrated

Most development work involves existing non-Codex code. Even new initiatives are often about adding new features to an existing code base (e.g. DiscussionTools for the Editing team, the newcomer homepage for the Growth team, Vector or MobileFrontend for the Web team). To enable these kinds of efforts to use Codex, some of the underlying code will need to be migrated to Codex first. This can happen incrementally, alongside new development.

Phase 3: Other code is migrated as appropriate

For code that isn't under active development, we'll need to decide whether to migrate it, when it makes sense to do that, and who should do it (generally, the team that owns it, with support from the Design System Team, but some of this code doesn't have an owner). To evaluate whether it makes sense to migrate something, we'll weigh the benefits (UI consistency, automatic benefit from future improvements to Codex, better maintainability in the future) against the effort that would be required, and consider how much the code is used by users and how much future maintenance work we think will be done. We may decide not to migrate something if it would take a lot of work, or if it's something obscure that is barely used and hasn't been touched in years.

Migration resources

View the guide on migrating from MediaWiki UI

Other migration guides to help developers migrate code to Codex are intended to be developed in the future.