Système de design Codex.

Routes du système de design Codex, exclusivement CSS et Vue

Choisissez l’implémentation dont vous avez besoin

Codex fournit des composants Vue et documente des structures de composants exclusivement CSS. L’exemple interactif opte pour cette dernière approche : son champ de recherche utilise exactement les classes de conteneur, de champ texte et de bouton final documentées par Codex, tandis qu’un script local de l’application filtre trois résumés d’articles originaux. L’exemple Vue distinct présente les importations de packages équivalentes.

Une recherche exclusivement CSS ne devient pas une combobox prédictive simplement parce qu’elle lui ressemble. Cet exemple soumet une requête et affiche une liste de résultats. Il n’utilise pas le modèle ARIA listbox et ne prétend pas implémenter TypeaheadSearch.

Consultez la spécification associée

Système de design Codex : typographie adaptée à la lecture

Distinguez les rôles du contenu de ceux des contrôles

Le jeton font-family-base correspond à sans-serif ; la pile de polices sans empattement du système relève d’un rôle distinct. Codex propose également le rôle serif heading-main, fondé sur Linux Libertine, avec Georgia, Times et d’autres polices de remplacement. L’aperçu utilise une police à empattement pour le titre de l’article et des polices sans empattement pour les contrôles, sans télécharger de polices.

La référence ci-dessous distingue font-size-medium, à 1rem, de line-height-medium, à 1.625rem. La valeur sans unité line-height-content est destinée au contenu généré par les utilisateurs ; elle ne signifie pas qu’il faut remplacer systématiquement la hauteur de ligne interne de chaque composant. Laissez aux éléments natifs input et button de CSS leurs propres métriques de contrôle.

Consultez la spécification associée

Système de design Codex : espacements et points de rupture

Utilisez l’échelle nommée et respectez ses exceptions

Dans Codex, spacing-100 vaut 16px, spacing-150 vaut 24px et spacing-200 vaut 32px. L’échelle comprend aussi des exceptions explicites : spacing-30 vaut 5px et permet le remplissage vertical des contrôles pour atteindre la hauteur par défaut de 32px. Arrondir chaque espacement au multiple de 8px effacerait une décision documentée concernant les composants.

Dans l’exemple, la liste de résultats occupe toute la largeur sous 640px, conformément au point de rupture documenté pour les tablettes. Sa largeur maximale de lecture, fixée à 56rem, est un choix propre à l’application. Le point de rupture pour les ordinateurs de bureau est de 1120px et celui pour les grands écrans de bureau, de 1680px ; ces seuils définissent des catégories de fenêtres d’affichage et ne correspondent pas à une grille fournie automatiquement à chaque application.

Consultez la spécification associée

Système de design Codex : rôles des couleurs et des actions

La couleur progressive n’est pas une simple décoration bleue

Codex distingue le type d’action du poids du bouton. Une action progressive fait avancer un processus, tandis que le poids principal désigne l’action dominante dans sa vue. Un bouton neutre de poids normal convient à la recherche dans cet index local ; un contrôle discret permet de l’effacer sans détourner l’attention des résultats.

Le fichier CSS compilé contient des couleurs de remplacement pour ses propriétés personnalisées, notamment la couleur du texte de base #202122 et la couleur progressive #36c. Pour ces états, l’aperçu utilise le CSS natif du composant. L’arrière-plan pâle du panneau de résultats relève de la mise en page de l’application et ne constitue pas un nouveau jeton de statut de Codex.

Consultez la spécification associée

Système de design Codex : structure de SearchInput

Associez soigneusement le champ et le bouton

La structure exclusivement CSS exige .cdx-search-input--has-end-button sur l’élément racine, un .cdx-search-input__input-wrapper, un .cdx-text-input avec son modificateur start-icon et un bouton doté de .cdx-search-input__end-button. Sans ces conteneurs, la géométrie de l’ensemble et l’alignement de l’icône sont perdus.

Le libellé visible précise le périmètre de la recherche. Le span de l’icône est décoratif et masqué aux API d’accessibilité. Le formulaire gère la touche Entrée et l’activation du bouton avec un seul écouteur de soumission ; après la mise à jour des résultats, le nombre est annoncé dans une zone de statut polie. Un champ vide rétablit tous les exemples locaux.

• Utilisez SearchInput pour rechercher du contenu sur une page.
• Utilisez TypeaheadSearch lorsque des suggestions de navigation prédictives sont nécessaires.
• Utilisez Lookup pour choisir une option comme valeur d’un formulaire.

Consultez la spécification associée

Système de design Codex : lecture des résultats et des détails

Permettez aux lecteurs de reprendre là où ils en étaient

Chaque résultat comporte un titre explicite, une brève description originale et un bouton qui ouvre le panneau de lecture local. Ce panneau est une composition propre à l’application, et non un Dialog de Codex : il reste dans le flux normal du document, n’a pas de fond modal et ne bloque pas le déplacement du focus.

L’ouverture d’un exemple place le focus sur le titre du panneau. Sa fermeture renvoie le focus au bouton qui l’a ouvert. Une nouvelle recherche ferme le détail précédent et recalcule le nombre de résultats, afin qu’un ancien article ne semble pas faire partie de la nouvelle requête. En l’absence de résultat, un texte explicatif s’affiche avec une action explicite pour effacer la recherche.

Consultez la spécification associée

Orientation et comportement des entrées du système de conception Codex

Prévoir les langues autres que l’anglais

La documentation des composants présente des exemples de gauche à droite et de droite à gauche. Codex s’inscrit dans un écosystème de connaissances multilingue. La mise en page de l’application doit donc utiliser des espacements logiques inline/block, plutôt que de supposer que chaque icône et chaque action de lecture se trouvent à gauche. La mise en page personnalisée de l’exemple utilise margin-inline et padding-inline lorsque le sens dépend de la direction.

Ici, la recherche ne se lance qu’à la validation. Cela évite de traiter le texte intermédiaire composé par un IME comme une requête terminée. Une autocomplétion destinée à la production nécessiterait une gestion des entrées compatible avec la composition, l’annulation des requêtes asynchrones et un modèle d’interaction de menu adapté. L’exemple local utilisant uniquement CSS ne prétend délibérément offrir aucune de ces fonctionnalités.

Consultez la spécification associée

Intégrer et étendre le système de conception Codex

Épingler la bibliothèque et gérer la logique des résultats

Le package vérifié est @wikimedia/codex 2.7.0, dont la feuille de style est dist/codex.style.css. La démo utilisant uniquement CSS n’a pas besoin du runtime Vue : ses commandes sont toutes des HTML natifs, et un petit script local gère le filtrage et l’état du panneau de lecture. La variante Vue importe CdxSearchInput et CdxButton lorsque la gestion de l’état par le framework est utile.

Le code fourni est sous licence GPL-2.0-or-later, qui accompagne les ressources locales. Les exemples ne reprennent ni l’identité de Wikipedia ni le contenu de ses articles. Avant de connecter un véritable point de terminaison de recherche, prévoyez un traitement distinct des erreurs réseau, du chargement et des réponses obsolètes, plutôt que de réutiliser l’état local sans résultat sous un autre nom.

1. Installez le package épinglé ou copiez sa feuille de style avec la licence.
2. Reproduisez la structure documentée utilisant uniquement CSS ou utilisez les composants Vue exportés.
3. Ajoutez la logique des requêtes et des résultats dans l’application, tout en préservant le comportement de recherche.
4. Vérifiez le focus clavier et les mises en page étroites avec du contenu réellement traduit.

Consultez la spécification associée

Exemples de composants du système de conception Codex

<form id="article-search" role="search">
  <label for="query">Find an example article</label>
  <div class="cdx-search-input cdx-search-input--has-end-button">
    <div class="cdx-search-input__input-wrapper">
      <div class="cdx-text-input cdx-text-input--has-start-icon">
        <input id="query" class="cdx-text-input__input" type="search">
        <span class="cdx-text-input__icon cdx-text-input__start-icon" aria-hidden="true"></span>
      </div>
    </div>
    <button type="submit" class="cdx-button cdx-search-input__end-button">Search</button>
  </div>
</form>
<p id="result-count" role="status"></p>

<script setup>
import { ref } from 'vue';
import { CdxSearchInput, CdxButton } from '@wikimedia/codex';
import '@wikimedia/codex/dist/codex.style.css';
const query = ref('');
const submitted = ref('');
function search() { submitted.value = String(query.value).trim(); }
</script>
<template>
  <form role="search" @submit.prevent="search">
    <CdxSearchInput v-model="query" aria-label="Find an example article" />
    <CdxButton action="progressive" weight="primary" type="submit">Search</CdxButton>
  </form>
  <p role="status">Submitted query: {{ submitted || 'All examples' }}</p>
</template>

<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Codex knowledge search</title><link rel="stylesheet" href="vendor/codex-2.7.0/codex.style.css"><style>*{box-sizing:border-box}body{font:16px/1.625 sans-serif;color:#202122;margin:0}main{max-width:56rem;margin:auto;padding:32px 24px}h1{font:normal 32px/1.3 Georgia,serif;border-bottom:1px solid #a2a9b1;padding-bottom:12px}h2{font-size:20px;margin:0 0 8px}label{display:block;font-weight:700;margin-bottom:8px}.top{font-size:14px;color:#54595d}.result{padding:24px 0;border-bottom:1px solid #c8ccd1}.result p{margin:8px 0 16px}.tools{display:flex;align-items:center;gap:16px;justify-content:space-between}.reading{padding:24px;background:#f8f9fa;border:1px solid #a2a9b1;margin-block:24px}.reading h2:focus{outline:2px solid #36c;outline-offset:4px}small{display:block;margin-top:32px;color:#54595d;font-size:14px}[hidden]{display:none!important}@media(max-width:639px){main{padding:24px 16px}.tools{align-items:stretch;flex-direction:column}.result .cdx-button{width:100%}}
</style><main><p class="top">Independent knowledge index · Codex CSS-only</p><h1>Explore the example collection</h1><p>Find an original topic summary and open its reading panel. This small index runs entirely in your browser.</p><form id="article-search" role="search">
  <label for="query">Find an example article</label>
  <div class="cdx-search-input cdx-search-input--has-end-button">
    <div class="cdx-search-input__input-wrapper">
      <div class="cdx-text-input cdx-text-input--has-start-icon">
        <input id="query" class="cdx-text-input__input" type="search">
        <span class="cdx-text-input__icon cdx-text-input__start-icon" aria-hidden="true"></span>
      </div>
    </div>
    <button type="submit" class="cdx-button cdx-search-input__end-button">Search</button>
  </div>
</form>
<p id="result-count" role="status"></p><div class="tools"><p id="empty" hidden>No matching topics. Try “river” or clear the search.</p><button type="button" class="cdx-button cdx-button--weight-quiet" id="clear">Clear search</button></div><div id="results"></div><section class="reading" id="reading" hidden><h2 id="reading-title" tabindex="-1"></h2><p id="reading-text"></p><button type="button" class="cdx-button" id="close">Close reading panel</button></section><small>Original example content. Wikimedia Codex 2.7.0 controls; application-owned results and inline panel. No external search request.</small></main><script>
const data=[{title:'River observation notes',text:'A field notebook can record water level, weather and observation time together. Repeated observations from the same location help readers compare conditions without confusing a new measurement with a changed method.',summary:'Organising repeated observations at a river station.'},{title:'Community archive descriptions',text:'An archive description records what an item is, when it was created and how it relates to other items. A clear description distinguishes an original document from a later copy and identifies uncertain dates without hiding that uncertainty.',summary:'Describing original documents and their context.'},{title:'Garden seed collection',text:'A seed record can distinguish the plant name, collection date and storage method. Keeping those attributes separate makes it easier to compare batches, while a free-text note preserves observations that do not fit a controlled field.',summary:'Keeping plant, date and storage information readable.'}];let opener;const results=document.querySelector('#results'),query=document.querySelector('#query'),reading=document.querySelector('#reading'),count=document.querySelector('#result-count');function render(){reading.hidden=true;results.replaceChildren();const found=data.filter(d=>(d.title+' '+d.summary).toLowerCase().includes(query.value.trim().toLowerCase()));count.textContent=found.length+' example topics';document.querySelector('#empty').hidden=found.length>0;for(const d of found){let a=document.createElement('article');a.className='result';let h=document.createElement('h2');h.textContent=d.title;let p=document.createElement('p');p.textContent=d.summary;let b=document.createElement('button');b.type='button';b.className='cdx-button';b.textContent='Read '+d.title;b.onclick=()=>{opener=b;document.querySelector('#reading-title').textContent=d.title;document.querySelector('#reading-text').textContent=d.text;reading.hidden=false;document.querySelector('#reading-title').focus()};a.append(h,p,b);results.append(a)}}document.querySelector('form').onsubmit=e=>{e.preventDefault();render()};document.querySelector('#clear').onclick=()=>{query.value='';render();query.focus()};document.querySelector('#close').onclick=()=>{reading.hidden=true;opener?.focus()};render();
</script></html>