Crie jornadas de serviço claras com os tokens semânticos e a Process List nativa da VA: explicações visíveis das etapas, rótulos de status significativos e detalhes complementares que mantêm o fluxo principal legível.
Web Components nativos do VA 24.14.0 (dependência component-library 56.14.0) e tokens do css-library 0.36.1; controlador de cenário original e fontes substitutas. · Referência de implementação
02
Referência de design do sistema de design VA
Variáveis publicadas do css-library 0.36.1 e web-components 24.14.0 da dependência component-library 56.14.0. As fontes são substituições locais explícitas. O contêiner de demonstração de 52rem é uma escolha da aplicação.
Um sistema de serviços para veteranos do sistema de design VA
Fundamentos e componentes são pacotes separados
O sistema do VA combina padrões de serviço, orientações de conteúdo, tokens, utilitários CSS e Web Components. A instalação documentada usa um pacote CSS-library para os fundamentos globais e um pacote component-library para os elementos interativos. Esta referência combina component-library 56.14.0 com css-library 0.36.1; esses pacotes têm números de versão independentes.
O exemplo explica ficticiamente como solicitar registros. Ele mostra como uma lista de etapas comunica o andamento sem afirmar que uma solicitação foi enviada ou que alguém tem direito a um benefício. Não há logotipo do VA, faixa de identidade governamental, registro pessoal nem status de caso real. O conteúdo de um serviço em produção ainda precisa ser verificado com o programa responsável do VA.
Funções tipográficas semânticas do sistema de design VA
As famílias tipográficas do corpo e dos títulos são intencionalmente diferentes
A família semântica dos títulos é Bitter, com Georgia e outras fontes serifadas como alternativas. A pilha do corpo começa com Source Sans Pro Web e Source Sans Pro, seguidas por alternativas sans-serif da plataforma. A função padrão do corpo é 1.06rem, aproximadamente 17px com uma raiz de 16px; os títulos usam 40px no nível 1, 32px no nível 2, 20px no nível 3 e aproximadamente 17px no nível 4.
Use --vads-font-size-body-default em vez do nome antigo source-sans-normalized. O token semântico indica a função, enquanto o nome antigo de normalização revela um detalhe da implementação da fonte. A prévia usa explicitamente Arial no texto do corpo e Georgia nos títulos. O componente nativo de processo CSS continua controlando sua estrutura e seus tamanhos internos; a alternativa não afirma reproduzir exatamente as métricas de Source Sans e Bitter.
A altura de linha padrão é 1,5 para parágrafos e 1,2 para títulos. O texto de abertura usa 1,75; o token de altura de linha serifada é 1,9, destinado a textos corridos com serifa, não a todos os títulos serifados. Aplicar 1,9 a um título compacto de etapa confundiria duas funções distintas. Neste exemplo, os itens do processo usam o nível 3, abaixo do título de seção da página, que está no nível 2.
Sistema de design VA Espaçamento semântico e layout
Diferencie uma pilha comum de um formulário
O valor padrão da pilha vertical geral é 1rem/16px. O valor padrão da pilha vertical de formulários é 2rem/32px. Essa diferença é útil: dois itens explicativos curtos precisam de um ritmo diferente daquele usado entre perguntas separadas, com rótulos, dicas, controles e erros. Os recuos s, m e l correspondem a 16, 24 e 32px, respectivamente.
A escala de espaçamento primitiva inclui 4, 8, 12, 16, 20 e 24px, além de incrementos maiores de oito pixels e valores especiais de um e dois pixels. Prefira nomes de espaçamento semânticos quando corresponderem à finalidade do layout. O contêiner externo de 52rem do exemplo é uma escolha da aplicação; já o recuo de 24px e o espaço de 32px entre seções usam valores publicados da escala. Isso não impõe esse contêiner a todos os modelos de página da VA.
O token atual para texto é --vads-color-text (#1b1b1b). --vads-color-link é #005ea2 e a função de link ativo é #0b4778; esses valores não correspondem a todas as entradas mais escuras da família de cores primárias. A função de erro é #d54309. A família herdada de vermelho secundário está obsoleta para essa finalidade. Portanto, uma nova apresentação de validação deve usar a semântica de erro, não a de secundário.
As tabelas de valores primitivos e semânticos são geradas a partir de uma versão identificada de CSS-library. O exemplo carrega essas variáveis reais, em vez de copiar uma paleta antiga de USWDS e identificá-la como VA. Além dessas variáveis, os componentes nativos podem conter valores compilados próprios; ao atualizar, verifique ambas as camadas.
O Process List da VA também é descrito como um mapa de metrô. Ele explica um processo mais longo ou mostra em que etapa a pessoa está. As diretrizes recomendam de três a dez etapas e apenas uma lista desse tipo por página. Cada item precisa de um título conciso iniciado por um verbo e de conteúdo explicativo visível; não deve ser apenas um número decorativo ao lado de um título sem conteúdo.
As tags nativas são va-process-list e va-process-list-item. Um item aceita header e level, além de active, pending, checkmark e status-text. O módulo publicado do componente dá precedência a checkmark, depois a active e, por fim, a pending. Evite combinações contraditórias: ao definir um estado booleano, desative os demais. O texto de status explícito acompanha o estilo de status e ajuda a entender a etapa sem depender da cor.
html
<va-process-list>
<va-process-list-item header="Prepare your request" level="3"
checkmark="true" status-text="Complete">
<p>Identify the record you need and the office that holds it.</p>
<va-details label="What information helps identify a record?">
<p>A title, approximate date, or reference number can help distinguish similar records. This is illustrative content, not a VA records-request procedure.</p>
</va-details>
</va-process-list-item>
<va-process-list-item header="Send the request" level="3"
active="true" status-text="Active">
<p>In this example, a request is ready for the appropriate service. No request is sent from this page.</p>
</va-process-list-item>
<va-process-list-item header="Read the response" level="3"
pending="true" status-text="Pending">
<p>A real service should explain where a response appears and how to ask about missing information.</p>
</va-process-list-item>
</va-process-list>
Sistema de design VA Use Details como complemento a uma etapa visível
Não transforme todas as etapas em acordeões
As diretrizes do Process List não recomendam combinar o cabeçalho de um acordeão com uma etapa do processo. Ocultar toda a explicação vai contra o objetivo de mostrar o processo. É permitido incluir um componente Details em uma etapa para apresentar informações complementares. Neste exemplo, a explicação para identificar o registro permanece visível, enquanto um detalhamento opcional fica em va-details.
O atributo label do componente se torna a pergunta visível na área expansível. Uma pergunta curta é mais útil do que “Mais informações”, pois indica às pessoas se o conteúdo oculto é relevante. Neste exemplo, os detalhes explicam o que pode ajudar a identificar um registro, com uma observação explícita de que o conteúdo é ilustrativo e não serve como instrução para um procedimento específico da VA.
Mantenha visível um resumo de cada etapa, inclusive das etapas marcadas como Pendente.
Use a área expansível Details apenas para uma explicação complementar dentro de uma etapa.
Mantenha a próxima ação real do serviço fora do título da etapa, em vez de transformar o título em um controle.
Sistema de design VA Demonstração de status e veracidade
Use um seletor de cenários, não um progresso fictício
O seletor de etapas de exemplo da prévia alterna a demonstração do componente entre preparação, envio e análise da resposta. Ele não avança uma solicitação real, não estima o tempo oficial de processamento nem deduz que algo foi concluído porque alguém clicou em um botão. Um serviço em produção deve mapear o estado verificado no backend para esses estados visuais e explicar separadamente o significado de qualquer atraso.
Ao mudar o seletor, as etapas anteriores ficam como Concluída, a etapa selecionada fica como Ativa e as etapas seguintes ficam como Pendente. Uma mensagem de status dinâmica anuncia a mudança no estado do exemplo. As três explicações permanecem visíveis no processo, e o estado opcional de Details é mantido. A opção de redefinição retorna à primeira etapa ilustrativa e fecha a área expansível complementar.
Sistema de design VA Carregue os Web Components nativos
Registre uma vez e preserve as dependências
O fluxo documentado do bundler importa main.css e chama defineCustomElements do pacote component-library. As fontes vêm de CSS-library e são carregadas separadamente. Os componentes que usam o sprite de ícones precisam de um caminho para o sprite na mesma origem, /img/sprite.svg por padrão. Esses são requisitos reais de integração, não ajustes opcionais a descobrir depois da implantação.
O exemplo independente usa a entrada oficial ESM para navegadores do web-components 24.14.0, a dependência declarada por component-library 56.14.0, além dos módulos sob demanda específicos para Process List, Process List Item e Details. O script da aplicação apenas seleciona os estados de exemplo. O ambiente de execução do navegador fornece o comportamento dos elementos personalizados nativos, inclusive o controle de Details.
Carregue o arquivo de tokens correspondente de CSS e a entrada dos componentes para navegador, preservando os caminhos relativos dos módulos.
Aguarde a definição de va-process-list-item antes de atribuir propriedades de estado de exemplo.
Teste todos os estados do cenário, o controle de teclado de Details e as larguras reduzidas sem ocultar o conteúdo explicativo.
Sistema de design VA Exemplos de componentes do sistema de design
Uma explicação nativa em três etapas
Atributos reais de Web Component e uma área expansível Details permitida dentro de uma etapa.
html
<va-process-list>
<va-process-list-item header="Prepare your request" level="3"
checkmark="true" status-text="Complete">
<p>Identify the record you need and the office that holds it.</p>
<va-details label="What information helps identify a record?">
<p>A title, approximate date, or reference number can help distinguish similar records. This is illustrative content, not a VA records-request procedure.</p>
</va-details>
</va-process-list-item>
<va-process-list-item header="Send the request" level="3"
active="true" status-text="Active">
<p>In this example, a request is ready for the appropriate service. No request is sent from this page.</p>
</va-process-list-item>
<va-process-list-item header="Read the response" level="3"
pending="true" status-text="Pending">
<p>A real service should explain where a response appears and how to ask about missing information.</p>
</va-process-list-item>
</va-process-list>
Use de 3 a 10 etapas e um único Process List por página.
Não substitua os títulos das etapas por controles de acordeão.
Defina apenas um indicador de status por item.
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.
html
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Request journey — VA component specimen</title><link rel="stylesheet" href="vendor/va-56.14.0/variables.css"><style>*{box-sizing:border-box}:root{--font-serif:Georgia,serif;--font-sans:Arial,sans-serif;--vads-font-family-heading:Georgia,serif;--vads-font-family-serif:Georgia,serif;--vads-font-family-sans:Arial,sans-serif}body{margin:0;font:1.06rem/1.5 Arial,sans-serif;color:var(--vads-color-text);border-top:8px solid var(--vads-color-primary-darker)}main{max-width:52rem;margin:auto;padding:32px 24px}h1,h2{font-family:Georgia,serif;line-height:1.2}h1{font-size:40px;margin:16px 0 24px}h2{font-size:32px;margin:32px 0 24px}.controls{padding:24px;background:var(--vads-color-base-lightest);display:flex;gap:16px;align-items:center;flex-wrap:wrap;margin:32px 0}label{font-weight:bold}select,button{font:inherit;padding:8px 12px;max-width:100%;background:white;color:var(--vads-color-text);border:1px solid var(--vads-color-base-dark)}button{cursor:pointer;color:var(--vads-color-link)}select:focus-visible,button:focus-visible{outline:3px solid #ffbe2e;outline-offset:3px}va-process-list-item,va-process-list-item *,va-process-list-item::before{font-family:Arial,sans-serif!important}va-process-list-item .usa-process-list__heading{font-family:Georgia,serif!important}va-process-list-item p{margin:8px 0 16px}footer{border-top:1px solid #dfe1e2;padding-top:24px;margin-top:32px}.note{background:#e7f6f8;padding:16px;border-left:4px solid #005ea2}#state{font-weight:bold}@media(max-width:479px){h1{font-size:32px}.controls{padding:16px;align-items:flex-start;flex-direction:column}}</style></head><body><main><p>VA native component example</p><h1>Understand a request journey</h1><p>See how a service can explain preparation, sending a request, and reviewing its response.</p><p class="note">Fictional process for design exploration. These are not VA submission instructions or a real case status.</p><div class="controls"><label for="stage">Example stage</label><select id="stage"><option value="0">Preparing a request</option><option value="1">Sending a request</option><option value="2">Reviewing a response</option></select><button id="reset" type="button">Reset example</button></div><p id="state" role="status">Example: preparing a request.</p><h2>The three stages</h2><va-process-list>
<va-process-list-item header="Prepare your request" level="3"
checkmark="true" status-text="Complete">
<p>Identify the record you need and the office that holds it.</p>
<va-details label="What information helps identify a record?">
<p>A title, approximate date, or reference number can help distinguish similar records. This is illustrative content, not a VA records-request procedure.</p>
</va-details>
</va-process-list-item>
<va-process-list-item header="Send the request" level="3"
active="true" status-text="Active">
<p>In this example, a request is ready for the appropriate service. No request is sent from this page.</p>
</va-process-list-item>
<va-process-list-item header="Read the response" level="3"
pending="true" status-text="Pending">
<p>A real service should explain where a response appears and how to ask about missing information.</p>
</va-process-list-item>
</va-process-list><footer>Native VA Web Components 24.14.0 · CSS tokens 0.36.1<br>Arial and Georgia fallbacks. No request is sent or stored.</footer></main><script>globalThis.getVaIconSpriteLocation=()=>new URL("vendor/va-web-24.14.0/sprite.svg",document.baseURI).pathname;</script><script type="module" src="vendor/va-web-24.14.0/component-library.esm.js"></script><script type="module">await customElements.whenDefined('va-process-list-item');const items=[...document.querySelectorAll('va-process-list-item')],select=document.querySelector('#stage');function render(){const current=Number(select.value);items.forEach((item,i)=>{for(const [key,on] of Object.entries({active:i===current,pending:i>current,checkmark:i<current})){item[key]=on;if(on)item.setAttribute(key,'true');else item.removeAttribute(key)}item.statusText=i<current?'Complete':i===current?'Active':'Pending';item.setAttribute('status-text',item.statusText)});document.querySelector('#state').textContent='Example: '+select.selectedOptions[0].textContent.toLowerCase()+'.'}select.addEventListener('change',render);document.querySelector('#reset').addEventListener('click',()=>{select.value='0';render();const detail=document.querySelector('va-details');if(detail.shadowRoot){if(detail.shadowRoot.querySelector('details').open)detail.shadowRoot.querySelector('summary').click()}select.focus()});render();</script></body></html>
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.
04
Sistema de design VA Configuração do agente
Ponto de partida para implementação
Inicialização documentada do bundler com versões de pacotes verificadas. O exemplo independente para navegador usa a distribuição ESM nativa correspondente de web-components, e não um build de React. O ZIP completo do exemplo funcional, disponível em Sources, também inclui as dependências exatas da prévia e o documento completo. Extraia os arquivos, execute python3 -m http.server 8080 nesse diretório e abra http://localhost:8080/va.html. Não abra exemplos baseados em módulos usando file://.
javascript
// Install in an application with a JavaScript bundler:
// npm install @department-of-veterans-affairs/[email protected] \
// @department-of-veterans-affairs/[email protected]
import '@department-of-veterans-affairs/component-library/dist/main.css';
import '@department-of-veterans-affairs/css-library/dist/tokens/css/variables.css';
import { defineCustomElements } from '@department-of-veterans-affairs/component-library';
defineCustomElements();
// Render the va-process-list markup in your page after this initialization.
// Deliver the CSS-library fonts separately, or choose an explicit fallback.
// Components that use va-icon also require the same-origin /img/sprite.svg.
Um prompt para seu projeto
Prompt para agente de IA
Crie uma explicação de processo de serviço da VA com um va-process-list contendo de três a dez elementos va-process-list-item. Use cabeçalhos iniciados por verbos, level=3 abaixo de um h2, descrições visíveis e um único estado active/pending/checkmark por item, com status-text explícito. Use va-details somente para texto complementar dentro de uma etapa; nunca oculte a etapa inteira. Importe o arquivo atual de tokens VADS CSS e registre os componentes nativos. Preserve o corpo do texto em 17px, as funções das famílias Bitter/Source Sans, o espaçamento semântico e os limites de 320/480/640/880/1024/1201/1400px. Qualquer demonstração interativa deve identificar suas etapas como ilustrativas e nunca se passar por uma solicitação enviada à VA.
05
Sistema de design VA Fontes e escopo
Demonstração técnica de componente com etapas fictícias de solicitação de registros. Não representa uma solicitação real à VA, o status de um caso, uma decisão sobre benefícios nem um endosso institucional.
