# Sistema di progettazione Codex

## Anteprima dell’interfaccia del sistema di progettazione sistema di design Codex

Cerca tre esempi originali, esamina un risultato, chiudilo oppure prova una query senza corrispondenze.

## Riferimento di progettazione del sistema di progettazione sistema di design Codex

@wikimedia/codex 2.7.0 nativo CSS e riferimento ufficiale aggiornato per token e componenti. L’anteprima autonoma usa il percorso documentato solo CSS; la larghezza del contenuto e il layout del pannello dei risultati sono scelte dell’applicazione.

### Ruoli tipografici

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| font-family-base | sans-serif | Ruolo di base per documenti e controlli. |
| font-family-heading-main | Linux Libertine, Georgia, Times, Source Serif 4, serif | Ruolo speciale per il titolo principale, con fallback locali. |
| font-size-small / medium / large | 0.875rem / 1rem / 1.125rem | Testo di supporto, testo predefinito e testo più grande. |
| line-height-medium | 1.625rem | Token di interlinea per componenti e funzionalità. |
| line-height-content | 1.625 | Ruolo senza unità per i contenuti generati dagli utenti. |
### Spaziatura

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| spacing-25 / 50 / 75 | 4px / 8px / 12px | Spaziature compatte. |
| spacing-100 / 150 / 200 | 16px / 24px / 32px | Ritmo standard del layout. |
| spacing-30 | 5px | Eccezione documentata per il padding verticale predefinito dei controlli. |
| spacing-horizontal-button | 12px − 1px | Tiene conto del bordo del pulsante. |
### Viewport e controlli

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| Mobile / tablet minima | 320px / 640px | Limiti del viewport. |
| Desktop / desktop-wide minima | 1120px / 1680px | Limiti del viewport più ampi. |
| Button small / medium / large | 24px / 32px / 44px minimum | Usa large quando il contesto touch lo richiede; le dimensioni sono tratte dalla documentazione di Button. |
### Fallback dei colori predefiniti compilati

| Nome / regola | Valore / configurazione | Utilizzo |
| --- | --- | --- |
| color-base | #202122 | Testo predefinito leggibile. |
| color-progressive | #36c | Colore per le azioni che fanno avanzare un processo; non è uno stato generico per ogni elemento. |
## Guida completa al sistema di progettazione sistema di design Codex

Una guida pratica per scegliere, applicare e valutare questo sistema in un’interfaccia reale.

Indicazioni complete, un punto di partenza per l’implementazione e link alle fonti.

## Percorsi solo CSS e Vue del sistema di progettazione sistema di design Codex

### Scegli l’implementazione che ti serve

> Codex offre componenti Vue e strutture documentate dei componenti solo CSS. L’esempio interattivo sceglie la seconda opzione: il controllo di ricerca usa le classi esatte per wrapper, campo di testo e pulsante finale documentate da Codex; uno script locale dell’applicazione filtra tre riepiloghi originali di articoli. L’esempio Vue separato mostra gli import equivalenti del pacchetto.

Una ricerca solo CSS non diventa una combobox predittiva solo perché le somiglia. Questo esempio invia una query e mostra un elenco di risultati. Non usa il pattern ARIA listbox e non dichiara di implementare TypeaheadSearch.

Leggi la specifica di supporto

## Tipografia per la lettura nel sistema di progettazione sistema di design Codex

### Mantieni distinti i ruoli di contenuto e controllo

Il token font-family-base risolve in sans-serif; lo stack di sistema sans-serif disponibile è un ruolo distinto. Codex espone anche un ruolo serif heading-main basato su Linux Libertine, con Georgia, Times e altri fallback. L’anteprima usa un titolo dell’articolo serif e controlli sans-serif senza scaricare font.

Il riferimento seguente distingue font-size-medium, pari a 1rem, da line-height-medium, pari a 1.625rem. Il valore unitless line-height-content è pensato per i contenuti generati dagli utenti; non è un’istruzione generale per sostituire l’interlinea interna di ogni componente. Lascia che input e button nativi di CSS mantengano le proprie metriche di controllo.

Leggi la specifica di supporto

## Spaziature e breakpoint del sistema di progettazione sistema di design Codex

### Usa la scala definita e le relative eccezioni

In Codex, spacing-100 corrisponde a 16px, spacing-150 a 24px e spacing-200 a 32px. La scala comprende anche eccezioni esplicite: spacing-30 è pari a 5px e supporta il padding verticale dei controlli per l’altezza predefinita di 32px. Arrotondare ogni spaziatura a una griglia di 8px cancellerebbe una scelta documentata del componente.

Nell’esempio, l’elenco dei risultati occupa tutta la larghezza sotto i 640px, in corrispondenza del limite tablet documentato. La larghezza massima di lettura, pari a 56rem, è una scelta dell’applicazione. Il breakpoint desktop è 1120px e quello desktop-wide è 1680px; queste soglie descrivono categorie di viewport, non una griglia automatica fornita a ogni applicazione.

Leggi la specifica di supporto

## Colori e ruoli delle azioni nel sistema di progettazione sistema di design Codex

### Progressive non è una decorazione blu generica

Codex distingue l’azione dal peso del pulsante. Un’azione progressive fa avanzare un processo, mentre il peso primary identifica l’azione principale nella vista corrente. Un pulsante neutral normal è adatto per cercare in questo indice locale; un controllo quiet può cancellare la ricerca senza competere con i risultati.

Il CSS compilato contiene colori di fallback per le sue proprietà personalizzate, tra cui il colore del testo di base #202122 e il progressive #36c. Per questi stati, l’anteprima usa CSS nativi dei componenti. Lo sfondo tenue del pannello dei risultati fa parte del layout dell’applicazione, non è un nuovo token di stato di Codex inventato.

Leggi la specifica di supporto

## Anatomia di SearchInput nel sistema di progettazione sistema di design Codex

### Unisci input e pulsante in modo intenzionale

La struttura solo CSS richiede .cdx-search-input--has-end-button sull’elemento radice, un .cdx-search-input__input-wrapper, un .cdx-text-input con il modificatore start-icon e un button con .cdx-search-input__end-button. Se ometti i wrapper, perdi la geometria di unione e l’allineamento dell’icona.

L’etichetta visibile specifica l’ambito della ricerca. Lo span dell’icona è decorativo e nascosto alle API di accessibilità. Un unico listener di invio del form gestisce sia Invio sia l’attivazione del pulsante; dopo l’aggiornamento dei risultati, il conteggio viene annunciato tramite un’area di stato cortese. Se il campo è vuoto, vengono ripristinati tutti gli esempi locali.

- Usa SearchInput per trovare contenuti in una pagina.

- Usa TypeaheadSearch quando servono suggerimenti predittivi per la navigazione.

- Usa Lookup quando occorre scegliere un’opzione come valore di un modulo.

Leggi la specifica di supporto

## Risultati e lettura dei dettagli nel sistema di progettazione sistema di design Codex

### Aiuta il lettore a ritrovare il punto in cui si trovava

Ogni risultato include un titolo identificativo, una breve descrizione originale e un pulsante che apre il pannello di lettura locale. Il pannello è una composizione dell’applicazione, non un Dialog di Codex: resta nel normale flusso del documento, non ha uno sfondo modale e non intrappola il focus.

Quando si apre un esempio, il focus passa al titolo del pannello. Quando lo si chiude, il focus torna al pulsante che l’ha aperto. Una nuova ricerca chiude i dettagli precedenti e ricalcola il conteggio dei risultati, evitando che un articolo non pertinente sembri parte della nuova query. Se non ci sono corrispondenze, viene mostrato un testo esplicativo e un’azione esplicita per cancellare la ricerca.

Leggi la specifica di supporto

## Direzione e comportamento degli input nel sistema di progettazione sistema di design Codex

### Progetta tenendo conto delle lingue oltre all’inglese

La documentazione dei componenti mostra esempi da sinistra a destra e da destra a sinistra. Codex è usato in un ecosistema di conoscenza multilingue: il layout dell’applicazione dovrebbe quindi usare spaziature logiche inline/block, senza presupporre che icone e azioni di lettura si trovino sempre a sinistra. Nel layout personalizzato dell’esempio, margin-inline e padding-inline vengono usati dove la direzione è rilevante.

La ricerca in questo esempio viene eseguita solo all’invio. Così il testo provvisorio della composizione IME non viene trattato come una query completa. Un completamento automatico di produzione richiederebbe una gestione dell’input consapevole della composizione, l’annullamento delle richieste asincrone e un modello d’interazione corretto per il menu; l’esempio locale solo CSS non dichiara di offrire queste funzionalità.

Leggi la specifica di supporto

## Integra ed estendi il sistema di progettazione sistema di design Codex

### Fissa la versione della libreria e gestisci la logica dei risultati

Il pacchetto verificato è @wikimedia/codex 2.7.0 e usa dist/codex.style.css come voce per gli stili. La demo solo CSS non richiede il runtime Vue, perché tutti i controlli sono HTML nativi e il piccolo script locale gestisce il filtraggio e lo stato del pannello di lettura. La variante Vue importa CdxSearchInput e CdxButton quando è utile gestire lo stato tramite il framework.

Il bundle del codice è distribuito con licenza GPL-2.0-or-later, inclusa negli asset locali. Gli esempi non copiano l’identità né i contenuti degli articoli di Wikipedia. Prima di collegare un vero endpoint di ricerca, aggiungi una gestione separata per errori di rete, caricamento e risposte obsolete, anziché rinominare lo stato locale senza risultati.

1. Installa il pacchetto con versione bloccata oppure copia il foglio di stile insieme alla licenza.

2. Visualizza la struttura documentata solo CSS oppure usa i componenti Vue esportati.

3. Collega la logica di query e risultati nell’applicazione, mantenendo la semantica della ricerca.

4. Verifica il focus da tastiera e i layout stretti usando contenuti effettivamente tradotti.

Leggi la specifica di supporto

## Esempi di componenti del sistema di progettazione sistema di design Codex

### Ricerca solo CSS con etichetta visibile

Struttura documentata dei wrapper e invio nativo del modulo.

```
<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>
```

Riferimento del codice

### Composizione di ricerca Vue

Import reali di Codex e stato Vue; l’output della query inviata localmente illustra il confine dell’integrazione.

```
<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>
```

Riferimento del codice

### Esempio autonomo completo

Il documento completo include layout, controlli e inizializzazione. Estrai l’archivio di esempio collegato per ottenere gli esatti asset vendor relativi, quindi avvialo tramite HTTP.

```
<!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>
```

Riferimento del codice

- Scarica l’esempio completo dalla sezione Fonti. Il README indica il comando esatto per avviarlo in locale.

- Mantieni i percorsi vendor relativi a questo documento; l’archivio include tutti gli asset usati da questa anteprima.

## Configurazione dell’agente per il sistema di progettazione sistema di design Codex

### Punto di partenza per l’implementazione

Il foglio di stile nativo è stato verificato localmente nell’anteprima autonoma. Il codice Vue è un esempio d’integrazione separato, non il runtime di quell’anteprima. Il file ZIP dell’esempio completo e funzionante, disponibile in Sources, include anche le dipendenze esatte dell’anteprima e il documento completo. Estrailo, esegui python3 -m http.server 8080 in quella directory, quindi apri http://localhost:8080/wikimedia-codex.html. Non aprire gli esempi basati su moduli tramite file://.

```
npm install @wikimedia/codex@2.7.0
# CSS-aware entry for CSS-only HTML:
# import '@wikimedia/codex/dist/codex.style.css';
# For the Vue example, add Vue to the existing Vue application:
# import { CdxSearchInput, CdxButton } from '@wikimedia/codex';
```

### Un prompt per il tuo progetto

```
Crea un indice di conoscenza locale con SearchInput e pulsanti solo CSS di Codex 2.7.0. Mantieni i wrapper documentati del pulsante finale, un’etichetta di ricerca esplicita e l’invio nativo del modulo. Mostra il conteggio dei risultati, un messaggio in assenza di corrispondenze e un’azione per cancellare la ricerca. Apri i dettagli dei risultati in linea, sposta il focus sul titolo e, alla chiusura, riportalo al pulsante di attivazione. Non dichiarare di implementare TypeaheadSearch né comportamenti modali. Usa i ruoli ufficiali per font e spaziature, indicando che la larghezza del contenuto è una scelta dell’applicazione.
```

## Fonti e ambito del sistema di progettazione sistema di design Codex

Esempio indipendente di OpenDesign con riepiloghi originali. Non vengono copiati contenuti o identità di Wikipedia. I controlli solo CSS sono Codex nativi; il filtraggio della ricerca e il pannello di lettura in linea sono codice dell’applicazione.

- Panoramica di Codex Voce ufficiale al sistema di progettazione Wikimedia.

- Accesso a Codex Risorse disponibili per design e sviluppo.

- Guida di stile Linee guida visive, editoriali e d’interazione.

- Scarica l’esempio completo e funzionante ZIP con HTML completo, dipendenze locali CSS/JavaScript, licenze fornite e istruzioni esatte per l’avvio. Non è necessario alcun passaggio di compilazione.

## Risorse correlate al sistema di progettazione sistema di design Codex

### Agriculture sistema di design

Crea flussi di servizio più articolati con gli spaziature concrete, le proprietà responsive e il modello di stato TaskList di AgDS. Prova un flusso di preparazione in cui il passaggio di revisione si sblocca solo una volta completati i prerequisiti.

### Alberta sistema di design

Usa i componenti web nativi e i token di design pubblicati di Alberta per creare una lista di preparazione completa, con opzioni accessibili, avanzamento derivato e feedback di revisione trasparente.

### Amsterdam

Usa il contratto reale e open source di Switch di Amsterdam, con un tema neutro completo, etichette accessibili e preferenze di lettura applicate immediatamente.


- [Riferimento per l’implementazione](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [Fonte](https://doc.wikimedia.org/codex/latest/design-tokens/font.html)
- [Fonte](https://doc.wikimedia.org/codex/latest/design-tokens/spacing.html)
- [Fonte](https://doc.wikimedia.org/codex/latest/design-tokens/breakpoint.html)
- [Fonte](https://doc.wikimedia.org/codex/latest/design-tokens/color.html)
- [Leggi la specifica di supporto](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [Leggi la specifica di supporto](https://doc.wikimedia.org/codex/latest/design-tokens/font.html)
- [Leggi la specifica di supporto](https://doc.wikimedia.org/codex/latest/design-tokens/spacing/)
- [Leggi la specifica di supporto](https://doc.wikimedia.org/codex/latest/components/demos/button.html)
- [Leggi la specifica di supporto](https://doc.wikimedia.org/codex/latest/components/overview.html)
- [Leggi la specifica di supporto](https://doc.wikimedia.org/codex/latest/using-codex/)
- [Riferimento del codice](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [Panoramica di Codex Voce ufficiale al sistema di progettazione Wikimedia.](https://doc.wikimedia.org/codex/latest/)
- [Accesso a Codex Risorse disponibili per design e sviluppo.](https://doc.wikimedia.org/codex/latest/using-codex/accessing-codex.html)
- [Guida di stile Linee guida visive, editoriali e d’interazione.](https://doc.wikimedia.org/codex/latest/style-guide/overview.html)