Codex

Codex is the frontend development toolkit used for implementing the Wikimedia Design Style Guide in code. As a software package, Codex includes UI components built in JavaScript (Vue.js), design tokens to store data for design values, and user-facing documentation. Codex components include wide-ranging support for internationalization, global usage and web accessibility by default.

Version used in MediaWiki
MediaWiki currently uses version 0.1.0-alpha.6 of Codex. Refer to the documentation for this version for an accurate reference of what components and features are available for use in MediaWiki. The main Codex documentation site tracks the development branch, and some things documented there may not have been released yet.

Codex Alpha
Alpha is the current version of Codex. Its main purpose is for testing and soliciting feedback from engineers and designers, and is not recommended for use in production.

Alpha Testing
The Abstract Wikipedia team tested Codex Alpha in March 2022 and tracked their experience via a diary study under the following user scenarios:


 * I am a designer who is being trained on how to use the design system in Figma
 * I am a designer who is adding instances of existing Codex components to my project in Figma
 * I am a developer who is adding existing Codex components to my project for the first time (these can be any components that design added instances of in Figma)
 * I am a developer who is writing tests that check if Codex components are working as expected in my project
 * I am supporting my team to implement the design system (Figma and Codex) into our workflow

All participants interacted directly with the Design Systems Team during the testing period and spent half or less than half of their time using the Design System while split between other project commitments. As a result of the study, we revisited our processes, documentation and strategy for onboarding teams to the design system and Codex during our offsite in April 2022. A key piece of criteria to move beyond Alpha Testing is to ensure that users can onboard seamlessly to the design system without the need for ongoing 1:1 support, which will not always be available as the team scales to additional projects. Design systems training for designers across WMF will also be critical part of the success and adoption of the design system as well, as designers play a key role in advocating for and integrating systems-thinking into product development from a design-first perspective.

Codex Beta
The Beta version of Codex is fully-tested and considered stable enough for use in production on MediaWiki. The Design Systems Team will be coordinating with product teams across Wikimedia to identify projects to collaborate on and the FY2022-23 Roadmap will be updated as projects are added. Teams should expect to discover some bugs along the way, but there will be a process in place for testing and QA to greatly reduce risk.

Note that the release of Codex Beta is not tied to the deprecation of a UI library; this work should be considered as separate targets/milestones for the Design Systems Team and partnering teams.

Requirements for Codex beta.1 release (pending)


 * There is a process in place for end-to-end QA of Codex components. This doesn't have to be fully automated, but should provide full coverage.
 * The first version of "Contribution Guidelines" is complete and users have clear pathways collaborate with, contribute to, and utilize the design system.
 * There is a published "Code of Conduct" for interacting with the Design Systems Team and acting as a contributor to Codex.
 * Design tokens identified for FY2021-22 are complete in Figma and codified in Codex, which open a pathway for designers to fully contribute to the design system.

Subscribe in Phabricator to track the status of the tasks above: Upgrade Codex to Beta version

Using Codex components in MediaWiki and extensions
Codex is included in MediaWiki, and is made available through the  ResourceLoader module. To use Codex components in your code, add  to your module's dependencies, then import the components you need as follows: You can then pass these components to the   option of your component, and use them in your component's template. Remember that kebab-case is required in templates, so you have to use  for CdxButton,   for CdxTextInput, etc.

Example
Example of a simple block form using the CdxButton and CdxTextInput components from Codex: Example of the module definition (in  format):

Using Codex icons in MediaWiki and extensions
For performance reasons, there is no  ResourceLoader module containing all the icons from Codex. Such a module would be large and wasteful, since most users of Codex only need a handful of the 200+ icons. Instead, ResourceLoader provides a way for modules to embed the icons they need, by defining a package file as follows: These icons can then be imported in  files as follows: For more information about how to use these icons once you've imported them, see the Codex documentation on icons.

Example
Example of the same block form as above, but with an icon added: Example of the ResourceLoader module definition: