Codex/Release Timeline/2.0

The Design System Team (DST) is preparing to release the next major version of Codex, the design system for Wikimedia. Codex has evolved significantly since the first major version release in late 2023: expanding the toolkit with a number of new components, tokens and icons, introducing alternative color modes, adding a proper i18n system, refactoring components to be compatible with native browser validation, supporting the creation of PHP implementation of the component library, refreshing the documentation, and (finally) getting a unique logo. With the upcoming introduction of a revised typography scale and customizable font modes along with a handful of other breaking changes, DST has determined this to be an appropriate time for another major version release.

Timeline

DST plans to first release a release candidate (rc) of version 2.0.0 that will include all known breaking changes. It is only anticipated that one rc version will be released, but if major issues are discovered, there will be additional rc releases until the build is considered stable enough to be the official major version.

Version	Release Date	MediaWiki Deployment
v2.0.0-rc.1	April 29, 2025	Week of May 5, 2025
v2.0.0	May 13, 2025	Week of May 19, 2025

Breaking changes

Codex 2.0 will include a number of breaking changes that need to be addressed in downstream code to avoid compatibility issues. These are detailed in full below along with guidance on how to prepare for the release.

Change to Less design tokens that affects calculations

Codex provides a set of design tokens as Less variables that are used within MediaWiki and beyond. Certain categories of design tokens will now reference CSS custom properties (CSS variables) rather than raw values. (Note that this change also affects the Sass distribution.)

This means that the relevant preprocessor variables will no longer work in Less functions (like unit()) and may require the use of the CSS calc() function to work in basic calculations. The affected token categories are:

• font-size
• line-height
• size-icon

Note that accent-color, color, background-color, filter, opacity-icon, mix-blend-mode, and box-shadow-color tokens also reference CSS custom properties and already need similar handling to work in calculations.

If you use any tokens in these categories:

• Do not use these tokens in any Less or Sass functions.
• When using any of these tokens in mathematical operations, or setting them to a negative value, use the CSS calc() function.

Examples

/* Do not do this; it will break the Less compiler. */
font-size: unit( @font-size-medium, em );

/* Do not use a negative sign. */
margin-left: -@size-icon-medium;
/* Instead, use `calc()` and multiply by -1. */
margin-left: calc( @size-icon-medium * -1 );

/* Do not do mathematical operations on these tokens without `calc()`. */
width: @size-icon-medium + ( 2 * @spacing-100 );
/* Instead, use `calc()`. */
width: calc( @size-icon-medium + ( 2 * @spacing-100 ) );

Removal of Lookup prop

The Lookup component's initialInputValue prop will be removed. Instead, define a ref and pass it into Lookup via the new inputValue prop. Reference the example below or the component documentation.

<template>
	<cdx-lookup
		v-model:selected="selection"
		v-model:input-value="inputValue"
		:menu-items="menuItems"
	></cdx-lookup>
</template>

<script>
import { defineComponent, ref, computed } from 'vue';
import { CdxLookup } from '@wikimedia/codex';
import vegetableItems from './data.json';

export default defineComponent( {
	name: 'LookupWithInitialSelection',
	components: { CdxLookup },
	setup() {
	    // Create a ref with the initial selection.
		const selection = ref( 'Q81' );
		// Create a ref with the initial input value.
		const inputValue = ref( 'carrot' );

		const menuItems = computed( () => vegetableItems.filter(
			( item ) => item.label.includes( inputValue.value )
		) );

		return {
			selection,
			inputValue,
			menuItems
		};
	}
} );
</script>

Removal of types

The following types will be removed:

• DialogAction: replace with ModalAction. The interface has not changed; only the name.
• PrimaryDialogAction: replace with PrimaryModalAction. The interface has not changed; only the name.

Removal of deprecated icons

The following icons have been renamed:

• cdxIconFullScreen: replace with cdxIconFullscreen
• cdxIconNoWikiText: replace with cdxIconNoWikitext
• cdxIconWikiText: replace with cdxIconWikitext

Visual changes

With the exception of some interfaces in MonoBook detailed below, readers and editors should not experience any major visual changes as part of this release.

Codex components and interfaces that use Codex design tokens may look slightly different but any changes should be either negligible or improvements. Some potentially noticeable visual changes include:

• Dialog titles have increased in size.
• Spacing between binary inputs within groups has reduced.
• Padding in non-inline Messages has reduced.

The changes to the typography scale will be visible to readers only once Codex font modes are incorporated into the font preferences features of Vector 2022, which will happen at a later time (tracked in T391891).

A complete picture of the testing effort prior to release is documented in T386298.

MonoBook

After Codex 2.0, Codex components will use Codex font-size tokens for typographic consistency, which are in rem units (meaning they reference the browser font size, not the base font size of the skin). This change will be more visible when Codex components are used in a skin with a smaller base font size, like MonoBook. To minimize the difference, we will implement the small font mode in MonoBook so Codex components are based around a 0.875rem (14px) font size (refer to T392253 to track that work).

Expected changes when using the MonoBook skin include the following:

• Only text within Codex components will change size. Article text, editing interfaces, and everything else not built with Codex will not be affected.
• Text within components will use Codex font-size tokens and will therefore become larger. In the case of MonoBook, this means that medium-size text will go from 12.7px to 14px. Other text sizes (smaller text, headings) will scale in a similar fashion.
• Some components that are currently out of sync with the type scale, like Accordion (see the special page screenshots below) will now follow the type scale and appear more consistent with the rest of the interface. In the Accordion example, the Accordion title will go from being 16px to 14px.
• Items like text inputs, menus and menu items, checkboxes and radios, buttons, etc. will not change size. Only their internal text will change size.

The table below shows some examples of affected interfaces.

Interface	Current	After 2.0	Notes
Login form			Message icon, inputs, and button stay the same size. Message, field label, input, and button text moves from 12.7px to 14px.
Special page with Codex form			Message icon, inputs, radios and checkboxes, and menus stay the same size. Message, field label, input text moves from 12.7px to 0.875rem/14px. Accordion title text becomes smaller/consistent with the rest of the interface.