Page MenuHomePhabricator

[EPIC] Make it easier to use Codex, improve designer and developer experience
Closed, InvalidPublic




We are on the cusp of wider use of the Codex library. In addition to documentation and infrastructure necessary for easy usage of any library, Codex has some oddities that will require some extra work to provide clear documentation and seamless usage of the library. In order to aid in adoption of Codex, we should consider how to make its use painless and easy.


As a developer user of Codex, I want to be able to quickly install the library and start effectively using components, icons, and design tokens.

As a developer user of Codex within MediaWiki, I want to be able to quickly install the library and start effectively using components, icons, and design tokens.

As a developer user of Codex within MediaWiki, I want to be able to easily test new releases or the main branch of Codex with my local MediaWiki instance.

As a MediaWiki designer, I want to be able to easily use Codex for my MediaWiki-specific designs.

Making it easier to use Codex would have impact in several ways:

  • Increased and faster adoption of Codex and the current design system, leading to greater consistency for our users and faster deprecation of legacy libraries
  • Increased buy-in to Codex, which may lead to more contributions to the library from people outside the Design Systems Team
  • Increased developer velocity and satisfaction, which is one of the main goals of the library
  • Potential use of Codex, which includes advanced accessibility, usability, and internationalization support, outside of the Wikiverse, leading to a more accessible internet

Proposed solutions

Use the latest release branch for the canonical live docs site

Status: To do, see T311097

Currently, the canonical live docs site is built on the main branch, which contains all merged work, including work which has not yet been part of a release. This has already caused confusion, because anyone working with the latest release in MediaWiki may see documentation on the site that does not yet apply with the version of Codex they're working with. We need to use the latest release branch, and change the canonical link to or something similar.

Document types and constants on the Codex docs site: ✓ done

Status: ✅ Done, see T300154

Currently, there is no way for a reader of the Codex docs site to get any information about types and constants that we use in the library. This is a major problem for components with props whose type is either a TypeScript type or a constant. The user sees the type or constant name, but has no way of getting information about the shape of those props. We must provide this information to the user if they're going to be able to effectively use that component.

Document component mixins

Status: To do, see T317160

We've decided to share some visual styles via Less mixins (like for links). We need to document these mixins on the docs site somehow so people know how to use them.

Add a class to the <html> element with the current Codex version

Status: To do, see T317162

We've already run into issues when making style changes in Codex that require simultaneous changes in an application that uses it. Add a class to the <html> element in MediaWiki with the current codex version would allow applications to write styles that target a specific version, helping to avoid collisions like this in the future.

Enable easier use of local Codex version for local MediaWiki development

Status: To do, see T314507

When doing local MediaWiki development, sometimes the developer will want to use a version of Codex other than the one provided in MediaWiki. For example:

  • Testing a new release before updating
  • Testing the main branch to gain access to unreleased work

Right now you can manually copy the built Codex library files into the proper place within MediaWiki core, but this is a pain, and we should provide an automated way to do this since it will be a commonly needed thing for MediaWiki developers. It's worth noting that this was a pain point with OOUI.

Document (and export) Codex composables

Status: To do, see T295186

We've written several reusable composition utility functions, some that pertain specifically to working in a MediaWiki context, that could be useful for Codex users, who will mostly be MediaWiki users. We should consider exporting them and documenting them on the docs site.

Avoid duplicate loading of Codex packages

Status: To do, see T310553

We created a special package, @wikimedia/codex-search, that contains TypeaheadSearch and its dependencies so that this package could be used within Vector to avoid including any unnecessary components there for the sake of performance. However, this means that if the entire @wikimedia/codex package is loaded on a page that also contains the Vector search bar, both libraries will be loaded, which means some code will be loaded twice. We should figure out how to avoid this.

Make README files NPM-appropriate

Status: To do, see T301730

Our README files are currently written in a way that refers to the whole of Codex, and not self-contained individual packages. This could be confusing when they're read in isolation, like on the NPM page for a package. We should rewrite these files to ensure that they're clear in any context.

Develop recommendations for how to set up unit tests

Status: To do, see T316415

Setting up unit tests for Vue components in MediaWiki skins and extensions is complicated. The ones that currently use Codex have more or less converged on a standard approach, but this approach is not well documented and could be improved. We should create clear guidelines for how to set up unit tests for Vue components in MW code, and how to deal with MW-specific and Codex-specific quirks.

Use same code style throughout repo and documentation

Status: Doing, see T320361

Ensuring that we use the same code style guidelines across the repo including Markdown documentation.

Help with code styling

We're currently relying only on ESLint/Stylelint.
We might want to ``use .editorconfig~~ (done ✓) and/or reconsider Prettier.

Enable documenting and document Stylelint configuration

Status: Doing, see T322710

With expanding Stylelint configuration it's important to share thinking behind it.

Provide non-TypeScript code examples

Status: To do, see T324375

It's important that the code examples in our documentation are easy to use for users who are not using TypeScript, which right now is almost all of them.

Event Timeline

ldelench_wmf renamed this task from Make it easier to use Codex to [EPIC] Make it easier to use Codex.Sep 15 2022, 5:52 PM
Volker_E renamed this task from [EPIC] Make it easier to use Codex to [EPIC] Make it easier to use Codex, improve designer and developer experience.Oct 31 2022, 4:23 AM

Recent Stylelint v15 has deprecated numerous stylistic rules, leaving those to projects like Prettier. So the addition of Prettier comes closer from my POV.

ldelench_wmf subscribed.

The Design Systems team is removing the majority of our "tracking" tasks like this one.
Open subtasks have been moved to the Codex Adoption column of the Codex workboard.