# Sistema de design Vant

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

Selecione um destinatário, edite um endereço, valide uma nova entrada e alterne o tema do componente nativo.

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

Variáveis CSS do Vant 4.10.2, lidas da folha de estilos base instalada. A prévia aplica uma substituição original da cor primária teal por meio de ConfigProvider; as funções padrão abaixo permanecem identificadas explicitamente.

### Funções de cor padrão

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --van-primary-color | var(--van-blue) | Alias padrão de ação; azul é #1989fa. |
| --van-success-color | var(--van-green) | Alias de sucesso; verde é #07c160. |
| --van-danger-color | var(--van-red) | Alias de perigo; vermelho é #ee0a24. |
| --van-warning-color | var(--van-orange) | Alias de aviso; laranja é #ff976a. |
| --van-text-color | var(--van-gray-8) | Alias de texto principal; gray-8 é #323233. |
| --van-text-color-2 | var(--van-gray-6) | Alias de texto secundário; gray-6 é #969799. |
| --van-border-color | var(--van-gray-3) | Alias de divisor; gray-3 é #ebedf0. |
| --van-background | var(--van-gray-1) | Superfície da página; gray-1 é #f7f8fa. |
| --van-background-2 | var(--van-white) | Superfície do componente; branco é #fff. |
### Escala de espaçamento

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --van-padding-base | 4px | Pequeno afastamento interno. |
| --van-padding-xs | 8px | Pequeno espaço interno. |
| --van-padding-sm | 12px | Espaçamento interno do item de endereço. |
| --van-padding-md | 16px | Recuo padrão da página. |
| --van-padding-lg | 24px | Recuo da seção. |
| --van-padding-xl | 32px | Recuo amplo da página. |
### Tipografia e forma

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --van-font-size-xs | 10px | Tamanho padrão do texto da interface. |
| --van-font-size-sm | 12px | Tamanho padrão do texto da interface. |
| --van-font-size-md | 14px | Tamanho padrão do texto da interface. |
| --van-font-size-lg | 16px | Tamanho padrão do texto da interface. |
| --van-line-height-xs | 14px | Token correspondente de altura de linha. |
| --van-line-height-sm | 18px | Token correspondente de altura de linha. |
| --van-line-height-md | 20px | Token correspondente de altura de linha. |
| --van-line-height-lg | 22px | Token correspondente de altura de linha. |
| --van-radius-sm | 2px | Raio de canto nomeado. |
| --van-radius-md | 4px | Raio de canto nomeado. |
| --van-radius-lg | 8px | Raio de canto nomeado. |
| --van-radius-max | 999px | Raio de canto nomeado. |
| --van-disabled-opacity | .5 | Opacidade padrão para estado desativado. |
| --van-duration-base | .3s | Duração de transição padrão. |
### Ajustes para lista de endereços e prévia

| Nome / Regra | Valor / Configuração | Uso |
| --- | --- | --- |
| --van-address-list-padding | 12px 12px 80px | O padrão oficial reserva espaço para o botão fixo de adicionar na parte inferior. |
| themeVars.addressListPadding | 12px | Ajuste original, pois esta prévia oculta o botão fixo de adicionar. |
| themeVars.primaryColor | #176b77 | Substituição original da cor primária, mapeada para --van-primary-color. |
| --van-address-list-item-font-size | 13px | Tamanho oficial do texto do endereço. |
| --van-address-list-edit-icon-size | 20px | Tamanho oficial do ícone de edição; não corresponde à área de toque inteira. |
## Guia completo do sistema de design Vant

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.

## Componentes móveis do sistema de design Vant com funções de CSS explícitas

### Componentes móveis com funções de CSS explícitas

> Vant é voltado a interfaces web móveis com Vue. AddressList, Field e CellGroup oferecem linhas compactas de endereço de recebimento e campos de formulário, em vez de uma tabela administrativa para desktop. O fluxo do kit de amostras usa esses componentes nativos e exibe o destino selecionado em um resumo separado.

Por padrão, a função primária é azul por meio de --van-primary-color. Sucesso, perigo e aviso usam variáveis de cor distintas. O exemplo altera intencionalmente a cor primária para #176b77 por meio de ConfigProvider; não apresenta esse tom teal como uma cor oficial da marca Vant. A arte original com textura de papel é decorativa e não representa o estado de nenhum controle.

Consulte a especificação de apoio

## Sistema de design Vant: escala de espaçamento de quatro pixels e tipografia compacta

### Escala de espaçamento de quatro pixels e tipografia compacta

Vant oferece valores de espaçamento de 4, 8, 12, 16, 24 e 32 pixels. Essas são variáveis base reais, não valores inferidos de uma captura de tela. Os itens da lista de endereços usam o token de espaçamento pequeno, enquanto a prévia ao redor acrescenta espaços maiores entre as seções para distinguir o formulário do resumo do pedido.

Os tamanhos de texto nomeados vão de 10 a 16 pixels, com alturas de linha correspondentes de 14 a 22 pixels. O texto do endereço tem uma variável de componente própria de 13px. Um produto para dispositivos móveis pode precisar de texto editorial maior do que esses padrões de controle: o título de exemplo tem tamanho original de 32px, reduzido para 27px no breakpoint da página.

Consulte a especificação de apoio

## Sistema de design Vant: o ID do endereço controla a seleção do botão de opção

### O ID do endereço controla a seleção do botão de opção

AddressList recebe uma lista de registros com id, name, tel, address e isDefault opcional. O valor de v-model identifica o registro escolhido. O resumo é calculado localizando esse ID na lista atual, para que a edição do destinatário atualize o destino exibido imediatamente, sem criar um segundo estado de resumo independente.

O armazém indisponível é passado por disabled-list e recebe uma explicação clara no texto de estado desativado. Ele permanece visível para contextualizar, mas não pode ser selecionado como destino. O selo Default indica o status padrão do registro; é independente da seleção atual e não muda quando outra opção de botão de opção é escolhida.

Consulte a especificação de apoio

## Sistema de design Vant: mantenha o rascunho separado do registro salvo

### Mantenha o rascunho separado do registro salvo

O evento de edição fornece o registro do endereço. O editor copia apenas os campos editáveis para um rascunho reativo e armazena o ID estável separadamente. Cancelar oculta esse rascunho sem modificar o endereço salvo. Salvar substitui o registro correspondente ou adiciona um novo registro local e, em seguida, seleciona esse ID.

O exemplo exibe a edição em linha, abaixo da lista, em vez de abrir uma janela pop-up na parte inferior. Assim, o exemplo completo continua utilizável em um documento incorporado. Vant também oferece AddressEdit para padronizar a entrada de endereços; este exemplo usa Form e Field porque os endereços de amostra evitam deliberadamente pressupor os dados administrativos de uma região específica.

1. Selecione um estúdio e confira o resumo antes de abrir a edição.

2. Altere o destinatário e depois cancele para confirmar que a linha salva não mudou.

3. Abra o editor novamente, salve campos válidos e confira o resumo selecionado.

Consulte a especificação de apoio

## Sistema de design Vant: regras do Field controlam o evento de envio

### Regras do Field controlam o evento de envio

O Form usa validate-trigger="onSubmit". O validador do destinatário remove espaços em branco no início e no fim e exige pelo menos dois caracteres. O validador do telefone aceita uma faixa moderada de dígitos, espaços, parênteses e hífens, com um sinal de mais opcional no início. O validador do endereço exige dez caracteres que não sejam espaços em branco. Essas verificações demonstram o funcionamento; não são uma validação postal nem uma validação universal de números de telefone.

Um Button primário com native-type="submit" envia o formulário nativo. Vant emite submit somente depois que as regras são aprovadas. Os erros aparecem ao lado do Field correspondente, e scroll-to-error leva o campo inválido para a área visível. A prévia também move o foco para o primeiro campo de destinatário ao iniciar a edição. O rascunho é preservado quando a validação falha.

Consulte a especificação de apoio

## Sistema de design Vant: ConfigProvider mapeia valores CamelCase para variáveis CSS

### ConfigProvider mapeia valores CamelCase para variáveis CSS

O objeto theme-vars inclui primaryColor, buttonPrimaryBackground, buttonPrimaryBorderColor e addressListPadding. ConfigProvider mapeia esses nomes para as variáveis --van-* correspondentes. Neste documento isolado, o provedor usa theme-vars-scope="global" para que os aliases declarados na raiz sejam resolvidos em função da função primária alterada. A substituição da função e dos dois valores do botão primário mantém coordenadas a ação nativa e a seleção do botão de opção.

Alternar a propriedade theme entre light e dark atualiza o tema dos componentes de Vant. A página ainda precisa de declarações próprias de fundo e texto que usem as variáveis de tema; definir o provedor, por si só, não aplica estilos a todos os elementos da aplicação. As amostras decorativas de papel mantêm intencionalmente as cores do material nos dois temas.

Consulte a especificação de apoio

## Sistema de design Vant: uma ação móvel fixa exige uma decisão de incorporação

### Uma ação móvel fixa exige uma decisão de incorporação

Por padrão, AddressList reserva oitenta pixels de espaçamento inferior para o botão fixo de adicionar. A prévia define show-add-button como false e apresenta um Button comum no fluxo do documento. Também altera addressListPadding para doze pixels, evitando tanto uma ação fixa sem contexto quanto uma área vazia e inexplicável na parte inferior do exemplo incorporado.

Em telas largas, a lista e o resumo dos materiais formam duas colunas. Abaixo do breakpoint original de 680px, elas ficam empilhadas. A altura nativa de AddressList, definida como 100%, é explicitamente redefinida para auto para que o painel acompanhe seu conteúdo, em vez de se sobrepor à próxima linha da grade. Não se usa uma altura mínima global da área de visualização, permitindo que a página principal dimensione o documento incorporado conforme o conteúdo. Os nomes dos endereços quebram em linhas em telas estreitas, em vez de ampliar a página.

Consulte a especificação de apoio

## Sistema de design Vant: foco visível e resultados locais explícitos

### Foco visível e resultados locais explícitos

A redefinição base de Vant remove os contornos de foco padrão. A folha de estilos da página restaura um anel de foco de três pixels, visível ao navegar por teclado, em botões, campos de entrada, áreas de texto e controles com tab-index. Esse acréscimo é feito no nível da aplicação; não significa que a importação de uma biblioteca, por si só, conclua o trabalho de acessibilidade. O seletor de tema tem um nome acessível e um rótulo visível.

Uma notificação de status registra um salvamento local ou a seleção de um destino. Ela informa explicitamente que nenhuma entrega foi agendada. O exemplo não tem endpoint de checkout, armazenamento nem efeitos externos. Um checkout real precisaria validar o endereço no servidor, verificar a elegibilidade para entrega e apresentar uma revisão final antes da compra.

- Mantenha uma explicação visível para endereços indisponíveis, em vez de removê-los sem aviso.

- Preserve o rascunho após um envio inválido para que a pessoa possa corrigir um campo.

- Descreva se uma ação altera a seleção local ou realmente agenda uma entrega.

Consulte a especificação de apoio

## Sistema de design Vant: importe a localidade e os estilos do componente

### Importe a localidade e os estilos do componente

O SFC completo importa seus componentes localmente. O arquivo de entrada instala o locale em inglês por meio de Locale.use e importa vant/lib/index.css antes da folha de estilos do layout original. O pacote verificado é Vant 4.10.2 com Vue 3; o sufixo .mjs da importação do locale em inglês corresponde ao arquivo ESM instalado.

A prévia independente incorpora seu JavaScript, CSS e a fonte de ícones ao documento. Após preservar a fonte WOFF2 incorporada, ela remove a alternativa WOFF remota não utilizada, para que o exemplo não dependa de uma solicitação de fonte a terceiros. Aplicações de produção devem usar seu próprio empacotador e suas próprias políticas de recursos, em vez de copiar uma URL de demonstração hospedada.

Consulte a especificação de apoio

## Exemplos de componentes do sistema de design Vant

### Seleção de endereço e edição com validação

SFC completo do Vue com AddressList, Form, Field, ConfigProvider e um rascunho controlado.

```
<script setup>
import {ref,reactive,computed,nextTick} from 'vue';
import {ConfigProvider,AddressList,Button,Form,Field,CellGroup,Tag,Switch,NoticeBar} from 'vant';
const list=ref([{id:'studio',name:'Alex Morgan',tel:'+44 20 7946 0101',address:'Studio 4, 18 Paper Street, London',isDefault:true},{id:'workshop',name:'Jules Chen',tel:'+44 20 7946 0122',address:'Workshop B, 52 Clay Road, London'}]);
const disabledList=[{id:'archive',name:'Sam Rivera',tel:'+44 20 7946 0133',address:'Old warehouse, 8 Mill Lane, London'}];
const chosen=ref('studio'),editing=ref(false),editingId=ref(null),notice=ref(''),dark=ref(false),formRef=ref();
const draft=reactive({name:'',tel:'',address:''});
const selected=computed(()=>list.value.find(x=>x.id===chosen.value));
const themeVars={primaryColor:'#176b77',addressListPadding:'12px',buttonPrimaryBackground:'#176b77',buttonPrimaryBorderColor:'#176b77'};
async function edit(item){editingId.value=item?.id||null;Object.assign(draft,item?{name:item.name,tel:item.tel,address:item.address}:{name:'',tel:'',address:''});editing.value=true;notice.value='';await nextTick();formRef.value?.resetValidation();document.querySelector('[name="recipient"]')?.focus();}
function save(){const value={id:editingId.value||`local-${Date.now()}`,name:draft.name.trim(),tel:draft.tel.trim(),address:draft.address.trim()};if(editingId.value)list.value=list.value.map(x=>x.id===editingId.value?{...x,...value}:x);else list.value.push(value);chosen.value=value.id;editing.value=false;notice.value='Address saved in this local preview.';}
function confirm(){notice.value=`Selected ${selected.value.name} at ${selected.value.address}. No delivery was booked.`;}
const nonempty=v=>v.trim().length>=2;
const phone=v=>/^\+?[\d ()-]{7,22}$/.test(v.trim());
</script>
<template><ConfigProvider theme-vars-scope="global" :theme="dark?'dark':'light'" :theme-vars="themeVars"><main class="delivery" :class="{dark}"><header><div><p class="eyebrow">VANT · MOBILE COMMERCE</p><h1>A destination for your sample kit.</h1><p class="intro">Choose a studio, update a recipient or add a local address.</p></div><label class="mode"><span>Dark</span><Switch v-model="dark" size="22px" aria-label="Dark theme" /></label></header><div class="columns"><section class="address-panel" aria-label="Delivery addresses"><div class="section-heading"><h2>Delivery address</h2><Tag plain type="primary">{{list.length}} available</Tag></div><AddressList v-model="chosen" :list="list" :disabled-list="disabledList" disabled-text="Outside the sample delivery area" default-tag-text="Default" :show-add-button="false" @edit="edit" @select="notice=''" /><div class="actions"><Button plain block type="primary" @click="edit()">Add a local address</Button></div></section><aside><section class="kit"><div class="paper-samples" aria-hidden="true"><i></i><i></i><i></i></div><p class="eyebrow">MATERIAL LIBRARY</p><h2>Paper & pigment kit</h2><p>Six paper stocks. Three print finishes. One place to compare them.</p><dl><div><dt>Recipient</dt><dd>{{selected?.name}}</dd></div><div><dt>Destination</dt><dd>{{selected?.address}}</dd></div></dl><Button block type="primary" @click="confirm">Use this address</Button><p class="local-note">Selection only. Nothing is purchased or shipped.</p></section></aside></div><section v-if="editing" class="editor"><h2>{{editingId?'Edit recipient':'Add an address'}}</h2><Form ref="formRef" validate-trigger="onSubmit" label-align="top" scroll-to-error @submit="save"><CellGroup inset><Field v-model="draft.name" name="recipient" label="Recipient" placeholder="Full name" :rules="[{validator:nonempty,message:'Enter at least two characters.'}]" /><Field v-model="draft.tel" name="telephone" type="tel" label="Telephone" placeholder="+44 20 7946 0100" :rules="[{validator:phone,message:'Use 7–22 characters: digits, spaces, +, brackets or hyphens.'}]" /><Field v-model="draft.address" name="address" type="textarea" rows="2" autosize label="Address" placeholder="Building, street and city" :rules="[{validator:v=>v.trim().length>=10,message:'Enter a complete address of at least ten characters.'}]" /></CellGroup><div class="form-actions"><Button type="primary" native-type="submit">Save locally</Button><Button native-type="button" @click="editing=false">Cancel</Button></div></Form></section><NoticeBar v-if="notice" wrapable :scrollable="false" color="var(--van-primary-color)" background="var(--van-background-2)" class="result" role="status">{{notice}}</NoticeBar></main></ConfigProvider></template>
```

Referência de código

- O valor selecionado é um ID de endereço, não uma posição no array.

- O botão fixo para adicionar do AddressList fica oculto; um Button no fluxo do conteúdo abre o editor.

- O envio do Form só é executado depois que os validadores do Field são aprovados.

### Página responsiva e foco visível

O layout dividido original para desktop se adapta a um fluxo de entrega para dispositivos móveis.

```
*{box-sizing:border-box}body{margin:0;background:#f7f8fa;color:#323233}.delivery{padding:32px;max-width:1080px;margin:auto;background:var(--van-background);color:var(--van-text-color)}.delivery.dark{background:var(--van-background);color:var(--van-text-color)}header{display:flex;align-items:flex-start;justify-content:space-between;gap:24px;margin-bottom:32px}.eyebrow{font-size:11px;font-weight:600;letter-spacing:.12em;color:var(--van-text-color-2)}h1{font-size:32px;line-height:1.2;margin:12px 0;max-width:550px}h2{font-size:18px;line-height:24px;margin:0 0 12px}.intro{font-size:15px;line-height:24px;color:var(--van-text-color-2)}.mode{display:flex;gap:8px;align-items:center;font-size:12px}.columns{display:grid;grid-template-columns:1.25fr 1fr;gap:24px}.section-heading{display:flex;justify-content:space-between;align-items:center;padding:0 12px}.section-heading h2{margin:0}.actions{padding:0 12px}.kit{background:var(--van-background-2);padding:24px;border-radius:8px}.kit p{line-height:1.6}.paper-samples{height:130px;position:relative;display:flex;align-items:center;justify-content:center;margin-bottom:24px;background:#e9edef;border-radius:4px;overflow:hidden}.paper-samples i{height:90px;width:90px;background:#d6b59b;box-shadow:0 4px 8px #0001;transform:rotate(-12deg);margin-right:-25px}.paper-samples i:nth-child(2){background:#efdfbe;transform:rotate(2deg)}.paper-samples i:nth-child(3){background:#94adb1;transform:rotate(16deg)}dl{font-size:14px;line-height:20px;margin:24px 0}dl div{display:grid;grid-template-columns:90px 1fr;margin:12px 0;gap:12px}dt{color:var(--van-text-color-2)}dd{margin:0}.local-note{font-size:12px;color:var(--van-text-color-2);margin-bottom:0}.editor{max-width:640px;margin-top:32px}.editor h2{margin-left:16px}.form-actions{display:flex;gap:12px;margin:16px}.result{margin-top:24px;border-radius:8px}button:focus-visible,input:focus-visible,textarea:focus-visible,[tabindex]:focus-visible{outline:3px solid #176b77!important;outline-offset:3px}@media(max-width:680px){.delivery{padding:24px 12px}.columns{grid-template-columns:1fr}header{gap:8px;margin-bottom:24px}h1{font-size:27px}.mode{padding-top:4px}.kit{padding:20px}.paper-samples{height:110px}.van-address-item__name{white-space:normal}}

.delivery .van-address-list{height:auto}
```

Referência de código

- A geometria dos componentes vem de Vant; o breakpoint de 680px da página é uma escolha da aplicação.

- A prévia restaura um anel de foco visível, pois a redefinição base remove os contornos padrão.

## Configuração do agente do sistema de design Vant

### Ponto de partida para implementação

Verificado com Vue 3 e Vant 4.10.2. O exemplo não armazena endereços fora do estado em memória.

```
// Create the project first:
// npm create vite@latest vant-specimen -- --template vue
// cd vant-specimen && npm install
// In a Vite Vue 3 project:
// npm install vant@4.10.2
// Save the complete SFC as App.vue and the supplied layout as style.css.
import {createApp} from 'vue';
import {Locale} from 'vant';
import enUS from 'vant/es/locale/lang/en-US.mjs';
import 'vant/lib/index.css';
import './style.css';
import App from './App.vue';
Locale.use('en-US',enUS);
createApp(App).mount('#app');
// index.html must contain <div id="app"></div>.
// Keep the template index.html and replace its entry with the code above.
// npm run dev
```

### Um prompt para seu projeto

```
Comece pelo seletor de endereços do sample-kit Vant 4.10.2. Preserve o AddressList nativo e o fluxo de edição com Form/Field para adicionar ou modificar um endereço local, incluindo a validação dos campos e o estado do endereço selecionado. Mantenha a configuração de Locale, o módulo en-US, o escopo do tema ConfigProvider e a adaptação do AddressList à altura do conteúdo. Cancelar não deve substituir um endereço existente; após a validação bem-sucedida, atualize apenas a coleção local de endereços. Não afirme que este exemplo, focado apenas em endereços, confirma pagamentos ou horários de entrega.
```

## Fontes e escopo do sistema de design Vant

Vant 4.10.2. Os tokens padrão e as escolhas originais da página são identificados separadamente. Os endereços de exemplo são fictícios; a seleção e a edição permanecem locais.

- AddressList Formato do registro de endereço, seleção e API de lista desativada.

- Form Eventos de envio/falha e regras de validação.

- Campo Composição nativa de campos de formulário.

- ConfigProvider Variáveis do tema e tema escuro.

- Início rápido Configuração de componentes Vue e folhas de estilo.

- Locale Registro do locale em inglês.

- Fonte dos tokens base Cores base, espaçamento interno, tipografia e raios oficiais.

## Recursos relacionados ao sistema de design Vant

### Vuestic UI

Uma folha de avaliação nativa do Vuestic, com predefinições de modo claro e escuro verificadas nas fontes, rótulos de avaliação acessíveis, validação de área de texto, média calculada e um estado salvo que preserva a avaliação concluída.

### Web Awesome

Analise os tokens semânticos reais de Web Awesome em elementos personalizados nativos, incluindo alterações localizadas de raio e espaçamento, estilo do shadow DOM, comportamento de seleção e validação de entrada.

### Ariakit

Ariakit oferece componentes React sem estilo, com estado compartilhado explícito e partes acessíveis que podem ser compostas. Seu combobox separa o texto digitado da seleção confirmada, sendo útil para seletores com busca; o localizador de referências abaixo demonstra essa distinção com resultados agrupados e indisponíveis.


- [Referência de implementação](https://vant-ui.github.io/vant/#/en-US/address-list)
- [Fonte](https://github.com/youzan/vant/blob/main/packages/vant/src/style/var.less)
- [Fonte](https://vant-ui.github.io/vant/#/en-US/address-list)
- [Consulte a especificação de apoio](https://vant-ui.github.io/vant/#/en-US/config-provider)
- [Consulte a especificação de apoio](https://vant-ui.github.io/vant/#/en-US/address-list)
- [Consulte a especificação de apoio](https://vant-ui.github.io/vant/#/en-US/form)
- [Consulte a especificação de apoio](https://vant-ui.github.io/vant/#/en-US/quickstart)
- [Referência de código](https://vant-ui.github.io/vant/#/en-US/address-list)
- [Referência de código](https://vant-ui.github.io/vant/#/en-US/config-provider)
- [AddressList Formato do registro de endereço, seleção e API de lista desativada.](https://vant-ui.github.io/vant/#/en-US/address-list)
- [Form Eventos de envio/falha e regras de validação.](https://vant-ui.github.io/vant/#/en-US/form)
- [Campo Composição nativa de campos de formulário.](https://vant-ui.github.io/vant/#/en-US/field)
- [ConfigProvider Variáveis do tema e tema escuro.](https://vant-ui.github.io/vant/#/en-US/config-provider)
- [Início rápido Configuração de componentes Vue e folhas de estilo.](https://vant-ui.github.io/vant/#/en-US/quickstart)
- [Locale Registro do locale em inglês.](https://vant-ui.github.io/vant/#/en-US/locale)
- [Fonte dos tokens base Cores base, espaçamento interno, tipografia e raios oficiais.](https://github.com/youzan/vant/blob/main/packages/vant/src/style/var.less)