Codex/fr

Codex is the design system for Wikimedia – visit the official documentation site.

Le paquet logiciel Codex comprend des outils de conception pour stocker les valeurs de conception, des composants d'interface utilisateur construits en JavaScript (Vue.js) et uniquement avec CSS, ainsi qu'une suite d'icônes. Ces outils comprennent un vaste support pour l'internationalisation, l'utilisation globale et l'accessibilité web par défaut.

Cette page détaille comment utiliser Codex dans MediaWiki. You may also want to read the more general documentation about how to.



Les paquets Codex dans MediaWiki


Version actuelle
MediaWiki utilise actuellement la version 0.20.0 de Codex. De nouvelles versions sont publiées toutes les 2 semaines (voir le pour la cadence de sortie et toutes les versions).

Paquets
Les paquets suivants de Codex sont disponibles sur MediaWiki :


 * 1)   &mdash; Ce paquet contient des jetons de conception dans divers formats, y compris les variables Less et JSON.
 * 2)   &mdash; Ce paquet contient des composants d'interface utilisateur (UI) construits avec Vue 3 ou en tant que composants CSS uniquement.
 * 3)   &mdash; Ce paquet contient un ensemble d'icônes.

Il convient de noter qu'il existe actuellement un quatrième paquet &mdash;. Il s'agit d'un sous-ensemble du paquet, contenant seulement le composant TypeaheadSearch et ses styles. Avec la version 0.20.0 il est devenu obsolète et son code a été transformé et placé dans le paquet. Il a été créé seulement pour servir Vector 2022 et améliorer les performances, il ne doit être utilisé que là et va cesser d'exister au fur et à mesure que la division du code sera disponible.



Utilisation générale de Codex dans MediaWiki
Check out the CodexExample extension for sample use of its components, design tokens, and icons in a MediaWiki extension.

The code examples on the Codex documentation web site all have two versions, labeled "NPM" and "MediaWiki". In MediaWiki core, skins and extensions, you have to use the "MediaWiki" versions of these examples; the "NPM" examples won't work, because some things work slightly differently in MediaWiki. Also read the sections on this page that go into more detail about how to use Codex design tokens, components, and icons in MediaWiki.



Utiliser la version locale de Codex dans votre instance locale MediaWiki
Sometimes it can be helpful to use your 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.


 * 1) Build your local Codex library by running   in the root directory of your Codex repository.
 * 2) 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. To copy:
 * 3) *  package, which contains Codex components:
 * 4) *  package, which contains Codex components:
 * 5) *  package:
 * 6) *  package:



Utiliser les jetons de conception Codex
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).



Avantages des jetons de conception
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.



Utilisation des jetons de conception Codex dans MediaWiki et ses extensions
You can use the design tokens in a  file (or in a   block in a   file) by importing. 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:

Note that the examples on the Codex documentation site import the tokens from, but this does not work in MediaWiki. Instead, you should import  as shown in the example above.



Jetons à valeurs relatives
Tokens that express distances generally use absolute values in, while tokens that express sizes generally use relative values in. 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  is set to   (which is 20px at a font size of 16px), while in Vector 2022 and Vector legacy it's set to (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.



Utiliser les composants de Codex Vue 3


Pour commencer
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.



Utiliser les composants Codex dans MediaWiki et les extensions
Codex is included in MediaWiki, and is made available through the  ResourceLoader module. To use Codex components in your code, add  to your module's dependencies, then import the components you need as follows: You can then pass these components to the  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  for CdxButton,   for CdxTextInput, etc.

Exemples
Example of a simple block form using the CdxButton and CdxTextInput components from Codex: Exemple de définition de module (dans le format ) :



Utiliser les icônes Codex


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



Utiliser les icônes Codex dans MediaWiki et les extensions
Pour des raisons de performance, il n'y a pas de module ResourceLoader  contenant toutes les icônes de Codex. Un tel module serait énorme et coûteux, car la plupart des utilisateurs de Codex n'ont besoin que d'une poignée de ces 200 icônes. Au lieu de cela, ResourceLoader fournit un moyen pour les modules d'intégrer les icônes dont ils ont besoin, en définissant comme suit un fichier de paquet : Ces icônes peuvent ensuite être importées dans les fichiers  comme suit : Pour plus d'informations sur la façon d'utiliser ces icônes une fois qu'elles ont été importées, voir la documentation de Codex sur les icônes.

Exemples
Exemple du même bloc formaté comme ci-dessus, mais avec une icône ajoutée :

Exemple de définition du module ResourceLoader : Dans cet exemple,  est un fichier d'initialisation qui démarre le composant , comme documenté avec ici.



Utiliser les mixins Codex Less
Certaines fonctionnalités de Codex sont mises en œuvre à l'aide de mixins Less. Par exemple, le composant Link est un mixin Less plutôt qu'un composant Vue, et l'utilisation d'icônes dans les composants CSS seulement nécessite d'utiliser un mixin Less (voir aussi la documentation ci-dessous pour l'Codex ).

L'utilisation des mixins Codex Less dans MediaWiki et les extensions fonctionne de manière très similaire à l'utilisation des jetons de conception : il suffit d'importer, ce qui rend tous les mixins Codex disponibles, ainsi que les jetons de conception.

Exemple de fichier Less utilisant un mixin : Notez que les exemples du site de documentation de Codex importent les jetons de  et ensuite le mixin pertinent de  mais cela ne fonctionne pas dans MediaWiki. Au lieu de cela, vous devez importer  comme indiqué dans l'exemple ci-dessus.



Utiliser le composants Codex uniquement CSS
Certains composants Codex ont des versions CSS seulement qui fonctionnent sans JavaScript. Vous pouvez vérifier qu'un composant possède une version CSS uniquement en recherchant ce composant dans la documentation de Codex, et voir s'il existe une section appelée version CSS uniquement. Par exemple, le composant Bouton possède une telle section. Cette section de documentation contient des exemples de l'apparence du HTML de ce composant.

Pour utiliser un composant CSS uniquement, procédez comme suit :


 * Générer le HTML du composant comme l'indique sa documentation
 * Charger le module, en utilisant
 * Certains composants nécessitent le chargement de styles supplémentaires au travers des mixins Less. Si vous en avez besoin, créez votre propre module ResourceLoader avec les styles requis, et chargez-le avec  aussi bien

<span id="Simple_example">

Exemple simple
<span id="Complex_example">

Exemple plus complexe
Dans  : Dans  : Dans  :

<span id="Migrating_from_MediaWiki_UI_to_Codex">

Migrer de l'interface utilisateur MediaWiki vers Codex
Lorsque vous remplacez l'interface utilisateur obsolète de MediaWiki par Codex, il est recommandé d'utiliser les composants CSS uniquement du paquet, ou dans certains cas les jetons   et les mixins Less à la place.

Veuillez consulter l'article Migrer l'interface utilisateur MediaWiki pour les informations détaillées.

<span id="Codex_release_cadence">

Fréquence de diffusion de Codex
Une nouvelle version de Codex est diffusée un mardi sur deux. Le jour où la nouvelle version est créée, nous fournissons également un correctif du noyau MediaWiki pour utiliser cette nouvelle version. Comme nous le faisons le mardi, la mise à jour du noyau sera déployée la semaine suivante (la prochaine fois que le train de déploiement est réactivé). Vous pouvez voir tous les labels Codex sur Gerrit ou un calendrier des labels sur GitHub. Pour plus d'informations sur ce qui est contenu dans chaque version, voir le journal des modifications.

Voir aussi le Calendrier des versions de l'équipe des systèmes de conception

<span id="Where_to_find_the_latest_version_of_Codex">

Où trouver la dernière version de Codex
Le site officiel de documentation est maintenant basé sur la dernière version de Codex (qui est celui du noyau de MediaWiki).