Crea percorsi di servizio chiari con i token semantici e il Process List nativo di VA: spiegazioni visibili delle fasi, etichette di stato significative e dettagli supplementari che mantengono leggibile il percorso principale.
Web Components nativi VA 24.14.0 (dipendenza component-library 56.14.0) e token css-library 0.36.1; controller dello scenario originale e font di fallback. · Riferimento per l’implementazione
02
Sistema di design VA Riferimento di progettazione
Variabili css-library 0.36.1 pubblicate e dipendenza component-library 56.14.0 web-components 24.14.0. I font di fallback locali sono espliciti. Il contenitore dell’esempio da 52rem è una scelta dell’applicazione.
Sistema di design VA Un sistema di servizi per i veterani
Fondamenti e componenti sono pacchetti separati
Il sistema VA combina modelli di servizio, linee guida sui contenuti, token, utilità CSS e Web Components. L’installazione documentata usa un pacchetto CSS-library per i fondamenti globali e un pacchetto component-library per gli elementi interattivi. Questo riferimento abbina component-library 56.14.0 a css-library 0.36.1; i due pacchetti hanno numeri di versione indipendenti.
L’esempio descrive una richiesta fittizia di documenti. Mostra come un elenco di processo comunichi l’avanzamento, senza affermare che una richiesta sia stata presentata o che una persona abbia diritto a un beneficio. Non compaiono loghi VA, banner istituzionali, dati personali né stati reali di pratiche. I testi dei servizi in produzione devono comunque essere verificati con il programma VA responsabile.
Le famiglie tipografiche per il corpo del testo e i titoli sono volutamente diverse
La famiglia semantica per i titoli è Bitter, con Georgia e altri caratteri serif come fallback. La famiglia per il corpo del testo inizia con Source Sans Pro Web e Source Sans Pro, seguiti dai sans-serif della piattaforma. Il ruolo predefinito per il corpo del testo è 1.06rem, circa 17px con una radice di 16px; i titoli usano 40px per il livello 1, 32px per il livello 2, 20px per il livello 3 e circa 17px per il livello 4.
Usare --vads-font-size-body-default anziché il nome precedente source-sans-normalized. Il token semantico indica il ruolo, mentre il vecchio nome di normalizzazione rivela un dettaglio di implementazione del font. L’anteprima usa esplicitamente Arial per il corpo del testo e Georgia per i titoli. Il componente di processo nativo CSS mantiene comunque la propria struttura interna e le proprie dimensioni; il fallback non pretende di riprodurre esattamente le metriche di Source Sans e Bitter.
L’interlinea predefinita dei paragrafi è 1.5 e quella dei titoli è 1.2. Il testo introduttivo ha un ruolo con interlinea 1.75; il token di interlinea serif è 1.9 ed è destinato al testo corrente serif, non a ogni titolo serif. Assegnare 1.9 a un titolo compatto di un processo confonderebbe due ruoli distinti. Gli elementi del processo in questo esempio usano il livello 3, sotto il titolo di sezione di livello 2 della pagina.
Sistema di design VA Spaziatura semantica e layout
Distinguere una spaziatura verticale ordinaria da quella di un modulo
Il valore predefinito della spaziatura verticale generica è 1rem/16px. Quello dei moduli è 2rem/32px. La differenza è utile: due brevi elementi esplicativi richiedono un ritmo diverso da domande separate con etichette, suggerimenti, controlli ed errori. Gli inset s, m e l corrispondono rispettivamente a 16, 24 e 32px.
La famiglia di spaziature primitive include 4, 8, 12, 16, 20 e 24px, valori più ampi con incrementi di otto pixel e valori speciali di uno e due pixel. Preferire i nomi semantici della spaziatura quando corrispondono allo scopo del layout. Il contenitore esterno da 52rem dell’esempio è una scelta dell’applicazione, mentre l’inset da 24px e la separazione da 32px tra le sezioni usano valori della scala pubblicata. Questa scelta non impone quel contenitore a tutti i modelli di pagina VA.
Il token attuale per il testo è --vads-color-text (#1b1b1b). --vads-color-link è #005ea2 e il ruolo attivo dei link è #0b4778; non corrispondono a tutte le varianti più scure della famiglia primaria. Il ruolo di errore è #d54309. La famiglia rossa secondaria ereditata è deprecata per questo uso: un nuovo trattamento di convalida dovrebbe quindi basarsi sulla semantica di errore anziché su quella secondaria.
Le tabelle primitive e semantiche sono generate da una versione specifica di CSS-library. L’esempio carica le variabili effettive invece di copiare una vecchia palette USWDS e presentarla come VA. Oltre a queste variabili, i componenti nativi potrebbero includere valori compilati al proprio interno; durante un aggiornamento, verifica entrambi i livelli.
Sistema di design VA Anatomia dell’elenco di processo
Da tre a dieci fasi significative
L’elenco di processo VA viene descritto anche come una mappa della metropolitana. Illustra un processo articolato o indica a che punto si trova una persona. Le linee guida prevedono da tre a dieci fasi e un solo elenco di questo tipo per pagina. Ogni elemento deve avere un titolo conciso che inizi con un verbo e contenuti esplicativi visibili; non è un numero decorativo accanto a un titolo privo di contenuto.
I tag nativi sono va-process-list e va-process-list-item. Un elemento accetta header e level, oltre a active, pending, checkmark e status-text. Il modulo del componente pubblicato assegna la precedenza a checkmark, poi ad active e infine a pending. Per evitare combinazioni contraddittorie, deseleziona gli altri stati booleani quando ne imposti uno. Il testo di stato esplicito accompagna lo stile dello stato e rende comprensibile la fase anche senza leggere il colore.
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 di design VA Details integra una fase visibile
Non trasformare ogni fase in un pannello a fisarmonica
Le linee guida per i processi sconsigliano di combinare l’intestazione di un pannello a fisarmonica con una fase del processo. Nascondere tutte le spiegazioni vanifica lo scopo di mostrare il processo. È invece possibile inserire un componente Details all’interno di una fase per aggiungere informazioni supplementari. L’esempio mantiene visibile la spiegazione sull’identificazione dei documenti e inserisce un approfondimento facoltativo in va-details.
L’attributo label del componente diventa la domanda visibile dell’elemento a scomparsa. Una domanda breve è più utile di Ulteriori informazioni, perché aiuta chi legge a capire se il contenuto nascosto è pertinente. In questo esempio, il contenuto di Details spiega cosa può aiutare a identificare un documento e precisa che si tratta di contenuti esemplificativi, non di istruzioni per una procedura VA specifica.
Mantieni visibile un riepilogo di ogni fase, comprese quelle contrassegnate come In sospeso.
Usare un elemento Details a scomparsa solo per una spiegazione secondaria all’interno di una fase.
Mantenere la prossima azione effettiva del servizio al di fuori del titolo del processo, anziché trasformare il titolo in un controllo.
Sistema di design VA Dimostrazione e attendibilità degli stati
Usare un selettore di scenario, non un avanzamento fittizio
Il selettore Fase di esempio dell’anteprima cambia l’esempio del componente tra preparazione, invio e revisione della risposta. Non fa avanzare una richiesta reale, non stima i tempi ufficiali di elaborazione e non deduce il completamento dal clic di una persona su un pulsante. Un servizio attivo dovrebbe associare gli stati verificati dal backend a questi stati visivi e spiegare separatamente il significato di eventuali ritardi.
Modificando il selettore, le fasi precedenti vengono impostate su Completata, la fase selezionata su Attiva e quelle successive su In sospeso. Una frase di stato dinamica annuncia il cambiamento dello stato di esempio. Tutte e tre le spiegazioni restano visibili e lo stato facoltativo di Details viene mantenuto. Il ripristino riporta alla prima fase esemplificativa e chiude l’elemento supplementare a scomparsa.
Sistema di design VA Caricare i Web Components nativi
Registrare una volta e preservare le dipendenze
Il percorso di bundling documentato importa main.css e richiama defineCustomElements dal pacchetto component-library. I font provengono da CSS-library e vengono distribuiti separatamente. I componenti che usano lo sprite delle icone richiedono un percorso dello sprite della stessa origine, per impostazione predefinita /img/sprite.svg. Si tratta di requisiti reali di integrazione, non di rifiniture facoltative da scoprire dopo la distribuzione.
L’esempio autonomo usa l’entry point ESM ufficiale per il browser di web-components 24.14.0, dipendenza dichiarata da component-library 56.14.0, oltre ai moduli lazy specifici per Process List, Process List Item e Details. Lo script dell’applicazione si limita a selezionare gli stati di esempio. Il runtime del browser fornisce il comportamento nativo degli elementi personalizzati, compreso il controllo Details.
Caricare CSS dei token e l’entry point dei componenti per il browser corrispondenti, preservando la posizione relativa dei moduli.
Attendi che va-process-list-item sia definito prima di assegnare le proprietà di stato dell’esempio.
Verifica tutti gli stati dello scenario, il controllo da tastiera Details e le larghezze ridotte, senza nascondere i contenuti esplicativi.
Esempi di componenti del sistema di design sistema di design VA
Una spiegazione nativa in tre fasi
Attributi reali dei Web Component e disclosure Details consentita all’interno di una fase.
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>
Usa da 3 a 10 fasi e un solo Process List per pagina.
Non sostituire i titoli delle fasi con trigger di accordion.
Imposta un solo indicatore di stato per elemento.
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.
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>
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.
04
Configurazione dell’agent sistema di design VA
Punto di partenza per l’implementazione
Inizializzazione del bundler documentata con versioni dei pacchetti verificate. L’esempio autonomo nel browser usa la corrispondente distribuzione ESM nativa dei web component, anziché una build React. Il file ZIP dell’esempio completo e funzionante, disponibile in Sources, include anche le dipendenze esatte per l’anteprima e il documento completo. Estrailo, esegui python3 -m http.server 8080 in quella directory e poi apri http://localhost:8080/va.html. Non aprire gli esempi basati su moduli tramite 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.
Un prompt per il tuo progetto
Prompt per l’agente
Crea una spiegazione del processo di un servizio VA con un va-process-list contenente da tre a dieci elementi va-process-list-item. Usa intestazioni che iniziano con un verbo, level=3 sotto un h2, descrizioni visibili e un solo stato active/pending/checkmark per elemento, con status-text esplicito. Usa va-details solo per testo aggiuntivo all’interno di una fase, senza nascondere mai la fase intera. Importa il file dei token VADS CSS attuale e registra i componenti nativi. Mantieni il corpo del testo a 17px, i ruoli delle famiglie Bitter/Source Sans, la spaziatura semantica e i breakpoint di 320/480/640/880/1024/1201/1400px. Ogni esempio interattivo deve indicare che le fasi sono illustrative e non deve mai sembrare una richiesta VA inviata.
05
Fonti e ambito sistema di design VA
Dimostrazione tecnica di componenti con fasi fittizie di richiesta di documenti. Non rappresenta una richiesta reale alla VA, lo stato di una pratica, una decisione sui benefici né un’approvazione istituzionale.
