Codex

Group:	Design Systems Team
Start:	August 2021
Team members:	Anne Tomasevich, Bárbara Martínez Calvo, Chris Ciufo, Eric Gardner, Lauren de Lench, Nat Hillard, Roan Kattouw, Sarai Sánchez, Volker E.

Codex is the design system for Wikimedia. To learn more, visit the official documentation site. This page covers the Codex software package.

The Codex software package includes design tokens to store design values, user interface components built in JavaScript (Vue.js) and only with CSS, and a suite of icons. These tools include wide-ranging support for internationalization, global usage and web accessibility by default.

This page documents how to use Codex in MediaWiki. You may also want to read the more general documentation about how to use Vue.js in MediaWiki.

Codex packages in MediaWiki[edit]

Current version[edit]

MediaWiki currently uses version 0.11.0 of Codex. New versions are released every 2 weeks (see the Release Timeline for release cadence and all versions).

Packages[edit]

The following Codex packages are available in MediaWiki:

@wikimedia/codex-design-tokens: This package contains design tokens in various formats, including Less variables and JSON.
@wikimedia/codex: This package contains UI components built with Vue 3 or as CSS-only components.
@wikimedia/codex-icons: This package contains a set of icons.

Read below to learn how to use these packages in MediaWiki.

General use of Codex in MediaWiki[edit]

Check out the CodexExample extension for sample use of Codex components, design tokens, and icons in a MediaWiki extension.

Differences between Codex documentation and MediaWiki usage[edit]

The Codex documentation includes code examples that show how to use each component. These examples will not work in MediaWiki, because they use import/export, TypeScript types, and self-closing tags. The table below summarizes the differences between what is shown in the Codex documentation, and what must be used instead in MediaWiki. Also read the section on this page that go into more detail about how to use Codex design tokens, components, and icons in MediaWiki.


When the Codex docs say this	Code in MediaWiki must use this instead
<cdx-progress-bar /> <cdx-icon :icon="cdxIconAlert" />	<cdx-progress-bar></cdx-progress-bar> <cdx-icon :icon="cdxIconAlert"></cdx-icon>
import { CdxButton } from '@wikimedia/codex'; import { defineComponent, ref } from 'vue';	const { CdxButton } = require( '@wikimedia/codex' ); const { defineComponent, ref } = require( 'vue' );
import { cdxIconAlert } from '@wikimedia/codex-icons';	const { cdxIconAlert } = require( './icons.json' ); // The icons.json package file must be defined // in the ResourceLoader module definition. // See the section on icons below.
export default defineComponent( { // ... } );	// @vue/component module.exports = { // ... };
// Codex examples use TypeScript, which include // type imports like this: import { CdxSelect, MenuItemData } from '@wikimedia/codex'; // And type annotations like this: const menuItems: MenuItemData[] = [ // ... ];	// TypeScript is not used in MediaWiki // Remove type imports and type annotations const { CdxSelect } = require( '@wikimedia/codex' ); const menuItems = [ // ... ];
@import '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less'; @import '@wikimedia/codex-design-tokens/mixins/link.less';	/* This imports all Codex tokens and mixins: */ @import 'mediawiki.skin.variables.less';

Using your local version of Codex in your local MediaWiki instance[edit]

Sometimes it can be helpful to use your local version of Codex in your local MediaWiki instance, in order to test new features or changes in Codex that have not yet been released and included in MediaWiki core. We hope to eventually automate this, but until we have that capability, you can do this manually by copying the dist files from the Codex packages into `resources/lib` in core.

Build your local Codex library by running npm run build-all in the root of your Codex repository.
Copy the parts of Codex that you need into your MediaWiki core repository. All of the examples below assume that you use a Unix-like system (e.g. Linux or macOS), your Codex repo and your core repo live in the same directory, and that you are working from the core directory:
1. To copy the @wikimedia/codex package, which contains Codex components: cp ../codex/packages/codex/dist/codex* resources/lib/codex/
2. To copy the @wikimedia/codex-design-tokens package: cp ../codex/packages/codex-design-tokens/dist/*.less resources/lib/codex-design-tokens/
3. To copy the @wikimedia/codex-icons package: cp ../codex/packages/codex-icons/dist/codex-icons.json ../codex/packages/codex-icons/dist/codex-icon-paths.less resources/lib/codex-icons

Using Codex design tokens[edit]

Design tokens are the smallest stylistic pieces of our design system. Learn about Codex design tokens in the official documentation and see demos of available tokens (for example the color tokens demo).

Benefits of using design tokens[edit]

All visual aspects of the design system, such as colors, typography, spacing, and sizes are defined with tokens. They provide a central source of truth for these design elements, which can then be used across multiple platforms and applications, here MediaWiki skins and extensions. By using design tokens, designers and developers can ensure consistency in the look and feel of their digital products. For example, instead of hard-coding a specific color value in multiple places within a website or app, a design token for that color can be created and used throughout the system. In the final stage of tokens architecture, all Codex tokens should be used exclusively for style properties in MediaWiki core, skins and extensions. A change like a color replacement will be easily reflected everywhere.

Design tokens help streamline the design and development process, increase efficiency, and maintain visual consistency throughout a project.

Using Codex design tokens in MediaWiki and extensions[edit]

You can use the design tokens in a .less file (or in a <style lang="less"> block in a .vue file) by importing mediawiki.skin.variables.less. MediaWiki uses the skin variables system to distribute Codex tokens.

The values of these token variables differ by skin. The default Codex theme is currently used in MinervaNeue, and a modified version of the default theme for a smaller base font size (see also the section about relative values below) is used in Vector 2022 and Vector legacy. All other skins currently use fallback values defined in mediawiki.skin.defaults.less; these values are still under development.

Example of a Less file using the Codex design tokens:

/* In 'extensions/MyExtension/resources/extension.stylesheet.less': */
@import 'mediawiki.skin.variables.less';

.my-extension-class {
    /* `@background-color-base` is one of the design tokens provided by Codex. */
    background-color: @background-color-base;
}

Note that the examples on the Codex documentation site import the tokens from '@wikimedia/codex-design-tokens/..., but this does not work in MediaWiki. Instead, you should import 'mediawiki.skin.variables.less' as shown in the example above.

Tokens with relative values[edit]

Tokens that express distances generally use absolute values in px, while tokens that express sizes generally use relative values in em. Tokens with relative values are designed to be used in a context where the font size is the default font size for the skin. In MinervaNeue the default font size is 16px; in Vector 2022 and Vector legacy it's 14px. Tokens with relative values are set such that they come out to the same pixel value in all skins. For example, in MinervaNeue @size-icon-medium is set to 1.25em (which is 20px at a font size of 16px), while in Vector 2022 and Vector legacy it's set to1.42857em(which is 20px at a font size of 14px).

In most cases, the skin will set the right font size for you, but if you encounter issues with relative values producing the wrong size (typically a fractional number of pixels rather than a round number, e.g. 22.857px instead of 20px), check if the parent element's font size is different from the skin's base font size.

Using Codex Vue 3 components[edit]

Getting started[edit]

See the official docs to learn more about the available Vue 3 components, including demos and usage information (for example, see the Button component demo). Note that code samples from these demos will not work in MediaWiki—see below for more information.

Using Codex components in MediaWiki and extensions[edit]

Codex is included in MediaWiki, and is made available through the @wikimedia/codex ResourceLoader module. To use Codex components in your code, add @wikimedia/codex to your module's dependencies, then import the components you need as follows:

const { CdxButton, CdxTextInput } = require( '@wikimedia/codex' );

You can then pass these components to the components 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 <cdx-button> for CdxButton, <cdx-text-input> for CdxTextInput, etc.

Example[edit]

Example of a simple block form using the CdxButton and CdxTextInput components from Codex:

<template>
    <div class="mw-block-form">
        {{ $i18n( 'block-target' ) }}
        <cdx-text-input v-model="username"></cdx-text-input>
        <cdx-button
            type="primary"
            action="destructive"
            :disabled="!isUsernameSet"
            @click="blockUser"
        >
            {{ $i18n( 'ipb-submit' ) }}
        </cdx-button>
    </div>
</template>

<script>
const { CdxButton, CdxTextInput } = require( '@wikimedia/codex' );

// @vue/component
module.exports = exports = {
    components: {
        CdxButton,
        CdxTextInput
    },
    data: {
        username: ''
    },
    computed: {
        isUsernameSet() {
            return this.username !== '';
        }
    },
    methods: {
        blockUser() {
            // ...
        }
    }
};
</script>

Example of the module definition (in extension.json format):

"ext.myExtension.blockform": {
	"packageFiles": {
		"init.js",
		"BlockForm.vue"
	},
	"messages": [
		"block-target",
		"ipb-submit"
	],
	"dependencies": [
		"@wikimedia/codex"
	]
}

Using Codex icons[edit]

Getting started[edit]

Visit the official docs site for information about the icon system and a list of all icons.

Using Codex icons in MediaWiki and extensions[edit]

For performance reasons, there is no codex-icons 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:

{
    "name": "icons.json",
    "callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
    "callbackParam": [
        // List the icons your module needs here, e.g.:
        "cdxIconArrowNext",
        "cdxIconBold",
        "cdxIconTrash"
    ]
}

These icons can then be imported in .vue files as follows:

const { cdxIconArrowNext, cdxIconBold, cdxIconTrash } = require( './icons.json' );

For more information about how to use these icons once you've imported them, see the Codex documentation on icons.

Example[edit]

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

<template>
    <div class="mw-block-form">
        {{ $i18n( 'block-target' ) }}
        <cdx-text-input v-model="username"></cdx-text-input>
        <cdx-button
            type="primary"
            action="destructive"
            @click="blockUser"
        >
            <cdx-icon :icon="cdxIconBlock"></cdx-icon>
            {{ $i18n( 'ipb-submit' ) }}
        </cdx-button>
    </div>
</template>
<script>
    const { CdxButton, CdxTextInput } = require( '@wikimedia/codex' );
    const { cdxIconBlock } = require( './icons.json' );
</script>

Example of the ResourceLoader module definition:

"ext.myExtension.blockform": {
	"packageFiles": {
		"init.js",
		"BlockForm.vue",
		{
			"name": "icons.json",
			"callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
			"callbackParam": [
				"cdxIconBlock"
			]
		}
	},
	"messages": [
		"block-target",
		"ipb-submit"
	],
	"dependencies": [
		"@wikimedia/codex"
	]
}

In this example, init.js is an init file that mounts the component with Vue.createMwApp(), as documented here.

Using Codex Less mixins[edit]

Some Codex functionality is implemented using Less mixins. For example, the Link component is a Less mixin rather than a Vue component, and using icons in CSS-only components requires using a Less mixin (see also the documentation for using CSS-only components below).

Using Codex Less mixins in MediaWiki and extensions works very similarly to using design tokens: simply import 'mediawiki.skin.variables.less', which makes all Codex mixins available, as well as the design tokens.

Example of a Less file using a mixin:

/* In 'extensions/MyExtension/resources/extension.stylesheet.less': */
@import 'mediawiki.skin.variables.less';

.my-extension-class {
    a {
        .cdx-mixin-link-base();
    }
}

Note that the examples on the Codex documentation site import the tokens from '@wikimedia/codex-design-tokens/...' and then the relevant mixin from '@wikimedia/codex/mixins/...'but this does not work in MediaWiki. Instead, you should import 'mediawiki.skin.variables.less' as shown in the example above.

Using CSS-only Codex components[edit]

Some Codex components have CSS-only versions that work without JavaScript. You can check if a component has a CSS-only version by looking up the component in the Codex documentation, and seeing if there is a section named "CSS-only version". For example, the Button component has such a section. This documentation section contains examples of what the HTML for that component looks like.

To use a CSS-only component, do the following:

Output the HTML for the component as shown in the component's documentation
Load the codex-styles module, using addModuleStyles()
Some components require loading additional styles through Less mixins. If you need this, create your own ResourceLoader module with the required styles, and load it with addModuleStyles() as well

Simple example[edit]

// Get an OutputPage object
$out = $this->getOutput();
// Output the HTML
$out->addHTML(
    '<button class="cdx-button cdx-button--action-progressive cdx-button--weight-primary">' .
    $this->msg( 'message-for-button-label' )->escaped() .
    '</button>'
);
// Load the codex-styles module
$out->addModuleStyles( 'codex-styles' );

Complex example[edit]

In SpecialFoo.php:

// Get an OutputPage object
$out = $this->getOutput();
// Output the HTML
$out->addHTML( <<<HTML
    <div
        class="cdx-text-input cdx-text-input--has-start-icon"
    >
        <input class="cdx-text-input__input" type="text" />
        <span
            class="cdx-text-input__icon cdx-text-input__start-icon mw-special-foo-input-icon"
        ></span>
    </div>
HTML
);
// Load the codex-styles module and our own styles module
$out->addModuleStyles( [ 'codex-styles', 'ext.specialfoo.styles' ] );

In extension.json:

{
    "ResourceModules": {
        "ext.specialfoo.styles": {
            "styles": [
                "SpecialFoo.less"
            ]
        }
    }
}

In SpecialFoo.less:

/* This imports all Codex design tokens and mixins */
@import 'mediawiki.skin.variables.less';

.mw-special-foo {
    /* ... other styles ... */
    
    &-input-icon {
        .cdx-mixin-css-icon( @cdx-icon-search );
    }
}

Codex release cadence[edit]

A new version of Codex is released every other Tuesday. On the day the new release is created, we also submit a patch to MediaWiki core to use that new release. Since we do this on Tuesdays, the update to core will be deployed the following week (the next time the deployment train runs). You can view all Codex tags on Gerrit or a tag timeline on GitHub. For more information about what is contained in each release, see the changelog.

Last release: 2023-02-14
Next release: 2023-02-28

Where to find the latest version of Codex[edit]

The official docs site is now based on the latest release of Codex (which is the one in MediaWiki core).