Codex

Appearance

Packages ​

@wikimedia/codex ​

This package contains Vue components – as building blocks for complex user interfaces. These components are written for Vue 3, and do not work with Vue 2. Documentation for individual components can be found in the “Components” section. For example, the documentation for CdxButton is at “Button” page.

Exports ​

The components package exports the following things:

  • Vue components. These are named CdxFooBar (e.g. CdxButton, CdxTextInput)
  • Composables, which are functions designed to be used with the composition API. These are named useFooBar (e.g. useComputedDirection, useModelWrapper).
  • TypeScript type definitions used for component props. These don't follow any particular naming pattern, but always start with a capital letter (e.g. ButtonType, HTMLDirection)
    • Note that the Icon type, which is used by some components, is not exported here. It lives in the icons package instead.

Files ​

Releases of the components package contain the following files:

  • codex.js: CommonJS build. Suitable for use within MediaWiki.
  • codex.umd.js: UMD build of Codex. Suitable for inclusion via a plain script tag or CDN.
  • codex.mjs: ES module build of Codex, which uses ES6 import and export syntax.
  • codex.style.css: Styles for all components, for use in left-to-right (LTR) languages
  • codex.style-rtl.css: Styles for all components, for use in right-to-left (RTL) languages. For more information on right-to-left support, see the section on bidirectionality
  • index.d.ts: Entry point for TypeScript type information; the actual types are defined in various .d.ts files in the src/ directory

@wikimedia/codex-icons ​

This package contains icons that can be used with the components from the Vue components package, or in other contexts. More detailed information can be found in the the icon documentation.

Because the icons package is large, and most applications use a relatively small subset of all icons, web applications should not send the entire icon package to the browser. Instead, use a bundler that performs tree shaking (i.e. extracting only those icons used in the application) or some other technique that minimizes the number of unused icons being sent to the browser.

Exports ​

The icons package exports the following things:

  • Icons, which are SVG strings or objects wrapping SVG strings. These are named cdxIconFoo (e.g. cdxIconAlert, cdxIconArrowNext). See the list of all icons for a complete list of icon names.
  • Utility functions for working with icon objects. These are used by the Icon component in the components package, but can also be used by any other code that needs to work with icons. To distinguish them from icons, the names of these functions do not start with cdxIcon (they are named resolveIcon and shouldIconFlip).
  • TypeScript type definitions for the Icon type and related types

Files ​

Releases of the icons package contain the following files:

  • codex-icons.mjs: ES module build, which uses ES6 import and export syntax.
  • codex-icons.js: CommonJS build. Suitable for use in NodeJs.
  • codex-icons.json: JSON file with all icon strings and objects, to facilitate use of the icons in languages other than JavaScript. This is the file that MediaWiki uses.
  • index.d.ts: Entry point for the TypeScript type information; refers to icons.d.ts, types.d.ts and util.d.ts for the actual type definitions

@wikimedia/codex-design-tokens ​

This package contains design tokens, which are style variables that can be used to write styles consistent with the Codex design system. This is mainly useful for people who develop their own components and want their appearance to be consistent with Codex.

The components package also uses these tokens internally for styling, but using the components package does not require installing the tokens package.

Files ​

Releases of the tokens package contain the following files:

  • theme-wikimedia-ui.css: The tokens as CSS variables (e.g. --color-placeholder: #72777d;)
  • theme-wikimedia-ui.less: The tokens as Less variables (e.g. @color-placeholder: #72777d;)
  • theme-wikimedia-ui.scss: The tokens as SASS variables (e.g. $color-placeholder: #72777d;)
  • theme-wikimedia-ui.json: A JSON structure with detailed data about each token