Codex: Difference between revisions

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.

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

The following Codex packages are available in MediaWiki:

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

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

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 color tokens demo).

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.

You can import the design tokens directly into your Less file or <style> block via a relative import path. Please note that these instructions will change: the Design Systems Team is currently working to improve importing the tokens so you will not need to use a relative path in the future. See T325237 for more information.

The design tokens are currently available only as Less variables. The file is located in core/resources/lib/codex-design-tokens/theme-wikimedia-ui.less. The example below demonstrates importing the Less variables version of the tokens into a Vue component inside a MediaWiki extension.

<style lang="less">
// Inside 'core/extensions/MyExtension/resources/App.vue'.
@import ( reference ) '../../../resources/lib/codex-design-tokens/theme-wikimedia-ui.less';

.my-extension-class {
    background-color: @background-color-progressive;
}
</style>

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

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 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"
            @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: ''
    },
    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"
	]
}

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 sections below that go into more detail about how to use Codex components and Codex icons in MediaWiki.

<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 = [
    // ...
];

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

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 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": "ResourceLoaderCodexModule::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.

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

See also: Design Systems Team/Release Timeline

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