# Sistema de design Codex

## Prévia da interface do sistema de design Codex

Pesquise entre três exemplos originais, inspecione um resultado, feche-o ou experimente uma consulta sem correspondências.

## Referência de design do sistema de design Codex

@wikimedia/codex 2.7.0: CSS nativo e referência oficial atual de tokens/componentes. A prévia autônoma usa a rota exclusiva de CSS documentada; a largura do conteúdo e o layout do painel de resultados são escolhas da aplicação.

### Papéis tipográficos

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| font-family-base | sans-serif | Papel base de documento/controles. |
| font-family-heading-main | Linux Libertine, Georgia, Times, Source Serif 4, serif | Papel especial para o primeiro título, com alternativas locais. |
| font-size-small / medium / large | 0.875rem / 1rem / 1.125rem | Texto complementar, texto padrão e texto maior. |
| line-height-medium | 1.625rem | Token de altura de linha para componente/recurso. |
| line-height-content | 1.625 | Papel sem unidade para conteúdo gerado pelo usuário. |
### Espaçamento

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| spacing-25 / 50 / 75 | 4px / 8px / 12px | Relações compactas. |
| spacing-100 / 150 / 200 | 16px / 24px / 32px | Ritmo padrão do layout. |
| spacing-30 | 5px | Exceção documentada para o preenchimento vertical padrão dos controles. |
| spacing-horizontal-button | 12px − 1px | Considera a borda do botão. |
### Janela de visualização e controles

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| Mobile / tablet minima | 320px / 640px | Limites da janela de visualização. |
| Desktop / desktop-wide minima | 1120px / 1680px | Limites de janelas de visualização maiores. |
| Button small / medium / large | 24px / 32px / 44px minimum | Use large quando o contexto de toque justificar; tamanhos obtidos da documentação de Button. |
### Valores alternativos compilados para as cores padrão

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| color-base | #202122 | Texto padrão legível. |
| color-progressive | #36c | Cor progressiva de ação; não é um status para todos os registros. |
## Guia completo do sistema de design Codex

Um guia prático para escolher, aplicar e avaliar este sistema em uma interface real.

Orientações completas, um ponto de partida para a implementação e links para o código-fonte.

## Rotas do sistema de design Codex exclusivas de CSS e Vue

### Selecione a implementação necessária

> Codex fornece componentes Vue e estruturas de componentes documentadas e exclusivas de CSS. A demonstração interativa escolhe a segunda opção: seu controle de busca usa exatamente as classes de wrapper, campo de texto e botão à direita documentadas por Codex, com um script local da aplicação que filtra resumos de três artigos originais. O exemplo separado em Vue mostra as importações equivalentes do pacote.

Uma busca exclusiva de CSS não se transforma em um combobox preditivo só por se parecer com um. Este exemplo envia uma consulta e exibe uma lista de resultados. Ele não usa o padrão ARIA listbox nem afirma implementar TypeaheadSearch.

Consulte a especificação de apoio

## Tipografia do sistema de design Codex para leitura

### Mantenha distintos os papéis do conteúdo e dos controles

O token font-family-base resolve para sans-serif; a pilha de fontes sans-serif do sistema disponível é um papel separado. Codex também oferece um papel serif heading-main com base em Linux Libertine e alternativas como Georgia, Times e outras. A prévia usa um título de artigo serifado e controles sans-serif sem baixar fontes.

A referência abaixo separa font-size-medium, com 1rem, de line-height-medium, com 1.625rem. O valor sem unidade line-height-content é destinado a conteúdo gerado por usuários; ele não é uma instrução geral para substituir a altura de linha interna de todos os componentes. Deixe os controles nativos de entrada e botão CSS manterem suas próprias métricas.

Consulte a especificação de apoio

## Espaçamento e pontos de interrupção do sistema de design Codex

### Use a escala nomeada e suas exceções

Codex spacing-100 corresponde a 16px, spacing-150 a 24px e spacing-200 a 32px. A escala também inclui exceções explícitas: spacing-30 corresponde a 5px e dá suporte ao preenchimento vertical dos controles com altura padrão de 32px. Arredondar todos os espaçamentos para uma grade de 8px eliminaria uma decisão documentada para o componente.

O exemplo deixa a lista de resultados com largura total abaixo de 640px, seguindo o limite documentado para tablets. A largura máxima de leitura de 56rem foi definida pela aplicação. O ponto de interrupção para desktop é 1120px e o de desktop amplo é 1680px; esses limites descrevem categorias de largura da janela de visualização, não uma grade automática fornecida a todas as aplicações.

Consulte a especificação de apoio

## Cores e funções de ação do sistema de design Codex

### Progressive não é um azul decorativo genérico

Codex diferencia a ação do peso do botão. Uma ação progressive avança um processo, enquanto o peso primary identifica a ação principal na visualização. Um botão neutro normal é adequado para pesquisar neste índice local; um controle quiet pode limpar a pesquisa sem competir com os resultados.

O CSS compilado contém cores alternativas para suas propriedades personalizadas, incluindo a cor do texto base #202122 e progressive #36c. A prévia usa o componente nativo CSS para esses estados. O fundo claro do painel de resultados faz parte do layout da aplicação, não é um novo token de status inventado para Codex.

Consulte a especificação de apoio

## Anatomia de SearchInput do sistema de design Codex

### Una o campo de entrada e o botão de forma intencional

A estrutura que usa apenas CSS exige .cdx-search-input--has-end-button na raiz, um .cdx-search-input__input-wrapper, um .cdx-text-input com seu modificador de ícone inicial e um botão com .cdx-search-input__end-button. Sem esses contêineres, a geometria de união e o alinhamento do ícone se perdem.

O rótulo visível identifica o escopo da pesquisa. O elemento span do ícone é decorativo e fica oculto para as APIs de acessibilidade. O formulário trata a tecla Enter e a ativação do botão com um único listener de envio; a contagem é anunciada por uma região de status polida após a atualização dos resultados. Um campo vazio restaura todos os exemplos locais.

- Use SearchInput para encontrar conteúdo em uma página.

- Use TypeaheadSearch quando forem necessárias sugestões de navegação preditiva.

- Use Lookup para escolher uma opção como valor de um formulário.

Consulte a especificação de apoio

## Resultados e leitura detalhada do sistema de design Codex

### Preserve o ponto de leitura

Cada resultado tem um título identificado, uma breve descrição original e um botão que abre o painel de leitura local. O painel é uma composição da aplicação, não um Dialog de Codex: permanece no fluxo normal do documento, não tem fundo modal e não restringe o foco.

Ao abrir um exemplo, o foco passa para o título do painel. Ao fechá-lo, o foco retorna ao botão que o abriu. Uma nova pesquisa fecha o detalhe anterior e recalcula a contagem de resultados, para que um artigo desatualizado nunca pareça fazer parte de uma nova consulta. Uma consulta sem resultados exibe um texto explicativo visível e uma ação explícita para limpar a pesquisa.

Consulte a especificação de apoio

## Direção e comportamento de entrada no sistema de design Codex

### Planeje para idiomas além do inglês

A documentação do componente apresenta exemplos da esquerda para a direita e da direita para a esquerda. Codex é usado em um ecossistema multilíngue de conhecimento; por isso, o layout da aplicação deve usar espaçamentos lógicos inline/block, em vez de presumir que todos os ícones e ações de leitura ficam à esquerda. O layout personalizado do exemplo usa margin-inline e padding-inline quando a direção é relevante.

A pesquisa neste exemplo só é executada após o envio. Isso evita tratar o texto intermediário da composição de IME como uma consulta concluída. Um recurso de preenchimento automático em produção exigiria tratamento de entrada compatível com composição, cancelamento assíncrono e um modelo correto de interação com o menu; o exemplo local que usa apenas CSS não afirma oferecer nenhum desses recursos.

Consulte a especificação de apoio

## Integre e amplie o sistema de design Codex

### Fixe a versão da biblioteca e gerencie a lógica dos resultados

O pacote verificado é @wikimedia/codex 2.7.0 e disponibiliza dist/codex.style.css como entrada de estilos. A demonstração que usa apenas CSS não precisa do runtime do Vue, pois todos os seus controles são elementos nativos de HTML e o pequeno script local gerencia a filtragem e o estado do painel de leitura. A variante para Vue importa CdxSearchInput e CdxButton quando é útil gerenciar o estado pelo framework.

O pacote de código é licenciado sob GPL-2.0-or-later, e a licença acompanha os recursos locais. Os exemplos não copiam a identidade visual nem o conteúdo de artigos da Wikipédia. Antes de conectar um endpoint de pesquisa real, implemente separadamente o tratamento de falhas de rede, carregamento e respostas desatualizadas, em vez de reaproveitar o estado local de resultados vazios com outro nome.

1. Instale o pacote com a versão fixada ou copie sua folha de estilos junto com a licença.

2. Renderize a estrutura documentada que usa apenas CSS ou use os componentes Vue exportados.

3. Adicione a lógica de consultas e resultados na aplicação, preservando a semântica da pesquisa.

4. Verifique o foco do teclado e os layouts estreitos com conteúdo traduzido real.

Consulte a especificação de apoio

## Exemplos de componentes do sistema de design Codex

### Pesquisa com rótulo visível usando apenas CSS

Estrutura documentada de contêineres e envio nativo do formulário.

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

Referência de código

### Composição de pesquisa em Vue

Importações reais de Codex e estado em Vue; a saída local da consulta enviada ilustra os limites da integração.

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

Referência de código

### Exemplo completo independente

O documento completo inclui layout, controles e inicialização. Extraia o arquivo de exemplo indicado para obter os recursos do fornecedor no caminho relativo exato e, em seguida, disponibilize-o por 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>
```

Referência de código

- Baixe o exemplo completo em Fontes. O README informa o comando exato para iniciá-lo localmente.

- Mantenha os caminhos do fornecedor relativos a este documento; o arquivo inclui todos os recursos usados nesta prévia.

## Configuração de agente para o sistema de design Codex

### Ponto de partida para implementação

A folha de estilos nativa foi verificada localmente na prévia independente. O código Vue é um exemplo de integração separado, não o runtime dessa prévia. O ZIP completo do exemplo funcional, disponível em Sources, também fornece as dependências exatas da prévia e o documento completo. Extraia o arquivo, execute python3 -m http.server 8080 nesse diretório e abra http://localhost:8080/wikimedia-codex.html. Não abra exemplos baseados em módulos usando 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';
```

### Um prompt para seu projeto

```
Crie um índice de conhecimento local com SearchInput e botões de Codex 2.7.0 que usem apenas CSS. Mantenha os contêineres documentados do botão final, um rótulo de pesquisa explícito e o envio nativo do formulário. Exiba a contagem de resultados, uma mensagem para consultas sem resultados e uma ação para limpar a pesquisa. Abra os detalhes dos resultados em linha, mova o foco para o título e, ao fechar, devolva-o ao botão que iniciou a ação. Não alegue oferecer TypeaheadSearch nem semântica modal. Use as funções oficiais de tipografia e espaçamento, identificando a largura do conteúdo como uma escolha da aplicação.
```

## Fontes e escopo do sistema de design Codex

Exemplo independente de OpenDesign com resumos originais. Nenhum conteúdo ou identidade da Wikipédia foi copiado. Os controles de CSS apenas usam elementos nativos de Codex; a filtragem da pesquisa e o painel de leitura em linha são código da aplicação.

- Visão geral de Codex Entrada oficial do sistema de design da Wikimedia.

- Acessar Codex Recursos disponíveis de design e desenvolvimento.

- Guia de estilos Orientações visuais, de conteúdo e interação.

- Baixar o exemplo completo funcional ZIP com HTML completo, dependências locais CSS/JavaScript, licenças incluídas e instruções exatas de inicialização. Não é necessário executar uma etapa de compilação.

## Recursos relacionados ao sistema de design Codex

### Agriculture sistema de design

Crie transações de serviço mais longas com o espaçamento concreto, as propriedades responsivas e o modelo de status TaskList da AgDS. Experimente um fluxo de preparação cuja etapa de revisão só é liberada quando todos os pré-requisitos estão concluídos.

### Alberta sistema de design

Use os componentes web nativos e os tokens de design publicados da Alberta para criar uma lista completa de preparação, com opções acessíveis, progresso derivado e feedback de revisão transparente.

### Amsterdam

Use o contrato real de Switch de código aberto da Amsterdam, com um tema neutro completo, rótulos acessíveis e preferências de leitura aplicadas imediatamente.


- [Referência de implementação](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)
- [Consulte a especificação de apoio](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [Consulte a especificação de apoio](https://doc.wikimedia.org/codex/latest/design-tokens/font.html)
- [Consulte a especificação de apoio](https://doc.wikimedia.org/codex/latest/design-tokens/spacing/)
- [Consulte a especificação de apoio](https://doc.wikimedia.org/codex/latest/components/demos/button.html)
- [Consulte a especificação de apoio](https://doc.wikimedia.org/codex/latest/components/overview.html)
- [Consulte a especificação de apoio](https://doc.wikimedia.org/codex/latest/using-codex/)
- [Referência de código](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [Visão geral de Codex Entrada oficial do sistema de design da Wikimedia.](https://doc.wikimedia.org/codex/latest/)
- [Acessar Codex Recursos disponíveis de design e desenvolvimento.](https://doc.wikimedia.org/codex/latest/using-codex/accessing-codex.html)
- [Guia de estilos Orientações visuais, de conteúdo e interação.](https://doc.wikimedia.org/codex/latest/style-guide/overview.html)