Design System Team/Announcing Codex 1.0

The Design System Team is excited to announce the release of Codex 1.0!

What is Codex?

Codex is the new design system for Wikimedia. Over the past 2 years, the Design System Team and contributors from the Wikimedia Foundation, Wikimedia Deutschland, and the volunteer communities have collaborated to create a centralized design system to serve Wikimedia projects. Codex provides more equitable experiences for all Wikimedia movement participants, and makes it easier and faster to design and build consistent user interfaces. With Codex, we aim to enable more people to contribute to the mission.

Codex provides a library of design tokens, user interface components, and catalog of icons to use with these components. Through the Codex Figma libraries, designers can reuse these shared components, tokens, and assets in their designs. For developers, Codex provides components built with Vue.js, as well as some CSS-only components that do not require JavaScript to use.

Codex is already being used for Wikifunctions, Vector 2022, the Growth mentor dashboard and impact module, the New Pages Feed, MediaSearch, NearbyPages, QuickSurveys, and ReadingLists. Projects currently under development using Codex include Accessibility for reading and the Incident Reporting System.

Codex provides a set of core components that cover a wide range of Wikimedia user interface needs, but does not necessarily provide equivalents of all components in OOUI. If you find that a component you were expecting to use is missing, please talk to the Design System Team and we'd be happy to help you. We strongly encourage contribution to Codex, in line with our vision of being a collaborative project guided by stewardship.

Why 1.0 now?

The Design System Team has been working towards this milestone for a number of months now. Based on early feedback, we’ve already made improvements to the developer experience of using Codex, like providing ready-to-go example repos of using Codex in a MediaWiki extension and changing our code snippets in the doc site for easier copy-paste into non-TypeScript and MediaWiki-specific projects.

We also dedicated significant time and effort ensuring accessibility of Codex components and assets conform to WCAG 2.1 AA and other standards, and plan to engage with groups like the American Foundation for the Blind for further improvements.

We’ve been consolidating various design resources (like the design style guide) into Codex so there is a single source of truth for Wikimedia front-end development and design standards. This is to clarify Codex’s role not just as a UI library, but as the design system for Wikimedia.

Who should use Codex?

Everyone! Some foundational elements like design tokens can and should be used in all Wikimedia software going forward. Most of the MediaWiki code that uses the older pre-token variables from mediawiki.ui has already been migrated to use the Codex tokens instead. The Codex wiki documentation has more information about using design tokens (and other elements) in MediaWiki.

At this time, Codex components are most suitable for client-side features that don't have complex requirements for non-JavaScript support, or for server-rendered interfaces that don't need much interactivity. Features requiring both high interactivity and the need to support users without JavaScript will need to create separate implementations of the feature using CSS-only components and using Vue components. The Design System Team has explored solutions that would allow a single Vue implementation to support both non-JavaScript and JavaScript users in the future.

Gadget and user script developers who would like to use JavaScript for interactivity cannot reliably use Codex at this time. However, this is something the Design System Team is looking to provide a solution for in the future. Further details and feedback is welcome on Phabricator.

Eventually, we intend for Codex to mostly replace other user interface libraries in the Wikimedia ecosystem, like OOUI and jquery.ui. Over time, we hope this will make the design of features and the developer experience less fragmented across the projects. We encourage people who want to make their code more maintainable and use modern tools now and in the future to consider migrating existing projects to Codex. For new projects, we strongly recommend building with Codex from the beginning. This will ensure you get the best and latest in design and engineering resources and tools, accessibility compliance, and multilingual and internationalization support.

Next steps

The Design System Team is here to assist you in evaluating whether Codex is suitable for your project and can help you put together a migration plan for existing codebases.

Those who wish to get started with Codex can visit the documentation site. To get more detailed information about using Codex in MediaWiki, you can visit the Codex project wiki page. For a general list of resources, you can visit our team wiki page.

Again, if you have any questions, feedback, or would like assistance from the Design System Team, come talk to us!