# Sistema di design VA ## Sistema di design VA Anteprima dell’interfaccia Esplora tre stati esemplificativi del processo e apri una spiegazione aggiuntiva senza nascondere il riepilogo delle fasi. ## 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. ### Tipografia semantica | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | --vads-font-family-heading | Bitter, Georgia, Cambria, Times New Roman, Times, serif | Famiglia per i titoli; l’anteprima usa Georgia. | | --vads-font-family-sans | Source Sans Pro Web / Source Sans Pro, system sans fallbacks | Famiglia per il corpo del testo e l’interfaccia; l’anteprima usa Arial. | | --vads-font-size-body-default | 1.06rem (about 17px) | Preferire il ruolo semantico a source-sans-normalized. | | --vads-font-size-heading-level-1 / 2 / 3 | 2.5 / 2 / 1.25rem | 40 / 32 / 20px con radice a 16px. | | --vads-font-size-heading-level-4 / 5 / 6 | 1.063 / .938 / .938rem | Circa 17 / 15 / 15px. | | --vads-font-line-height-default / heading / body-lead | 1.5 / 1.2 / 1.75 | Usare il ruolo tipografico appropriato. | ### Spaziatura | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | --vads-spacing-inset-s / m / l | 1 / 1.5 / 2rem | 16 / 24 / 32px. | | --vads-spacing-vertical-stack-default | 1rem / 16px | Spaziatura verticale generica. | | --vads-forms-spacing-vertical-stack-default | 2rem / 32px | Spaziatura verticale dei campi del modulo. | | --vads-spacing-0p5 / 1 / 1p5 / 2 / 2p5 / 3 | 4 / 8 / 12 / 16 / 20 / 24px | Scala primitiva con dimensione radice standard. | | --vads-spacing-4 / 5 / 6 / 7 / 8 | 32 / 40 / 48 / 56 / 64px | Valori primitivi più ampi. | ### Colori semantici | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | --vads-color-text | #1b1b1b | Ruolo predefinito consigliato per il testo. | | --vads-color-link / link-active | #005ea2 / #0b4778 | Ruoli predefiniti e attivi dei link. | | --vads-color-primary-darker | #162e51 | Riferimento per una superficie primaria ad alta enfasi. | | --vads-color-base-lighter / base-lightest | #dfe1e2 / #f0f0f0 | Divisori e sfondi neutri. | | --vads-color-error | #d54309 | Usare la semantica di errore anziché il rosso secondario deprecato. | | --vads-color-success-darker | #216e1f | Riferimento per un colore di successo più scuro; lo stato va comunque espresso a parole. | ### Breakpoint responsive | Nome / regola | Valore / configurazione | Utilizzo | | --- | --- | --- | | --vads-breakpoint-mobile / mobile-lg | 320 / 480px | Limiti di riferimento per gli schermi piccoli. | | --vads-breakpoint-tablet / tablet-lg | 640 / 880px | Layout intermedi. | | --vads-breakpoint-desktop / desktop-lg | 1024 / 1201px | Limiti per desktop. | | --vads-breakpoint-widescreen | 1400px | Riferimento per layout ampi. | ## Sistema di design VA Guida completa 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. ## 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. Leggi la specifica di supporto ## Sistema di design VA Ruoli tipografici semantici ### 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. Leggi la specifica di supporto ### L’interlinea dipende dal ruolo 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. Leggi la specifica di supporto ## 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. Leggi la specifica di supporto ## Sistema di design VA Colori e token responsivi ### Usare un ruolo anziché un alias storico 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. Leggi la specifica di supporto ### I breakpoint VA non sono una scala generica di framework L’insieme di token definisce i breakpoint mobile a 320px, mobile-lg a 480px, tablet a 640px, tablet-lg a 880px, desktop a 1024px, desktop-lg a 1201px e widescreen a 1400px. La soglia insolita di 1201px è importante per adeguarsi ai modelli esistenti. Le variabili dei breakpoint documentano i valori; le proprietà personalizzate CSS non possono essere semplicemente sostituite all’interno di una condizione nativa media-query. Usa il valore corrispondente in fase di build o un valore letterale derivato dal token verificato. Leggi la specifica di supporto ## 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. ```

Identify the record you need and the office that holds it.

A title, approximate date, or reference number can help distinguish similar records. This is illustrative content, not a VA records-request procedure.

In this example, a request is ready for the appropriate service. No request is sent from this page.

A real service should explain where a response appears and how to ask about missing information.

 ``` Riferimento del codice Leggi la specifica di supporto ## 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. Leggi la specifica di supporto ## 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. Leggi la specifica di supporto ## 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. 1. Caricare CSS dei token e l’entry point dei componenti per il browser corrispondenti, preservando la posizione relativa dei moduli. 2. Attendi che va-process-list-item sia definito prima di assegnare le proprietà di stato dell’esempio. 3. Verifica tutti gli stati dello scenario, il controllo da tastiera Details e le larghezze ridotte, senza nascondere i contenuti esplicativi. Leggi la specifica di supporto ## 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. ```

Identify the record you need and the office that holds it.

A title, approximate date, or reference number can help distinguish similar records. This is illustrative content, not a VA records-request procedure.

In this example, a request is ready for the appropriate service. No request is sent from this page.

A real service should explain where a response appears and how to ask about missing information.

 ``` Riferimento del codice - 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. ``` Request journey — VA component specimen

VA native component example

Understand a request journey

See how a service can explain preparation, sending a request, and reviewing its response.

Fictional process for design exploration. These are not VA submission instructions or a real case status.

Example: preparing a request.

The three stages

Identify the record you need and the office that holds it.

A title, approximate date, or reference number can help distinguish similar records. This is illustrative content, not a VA records-request procedure.

In this example, a request is ready for the appropriate service. No request is sent from this page.

A real service should explain where a response appears and how to ask about missing information.
``` 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’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://. ``` // Install in an application with a JavaScript bundler: // npm install @department-of-veterans-affairs/component-library@56.14.0 \ // @department-of-veterans-affairs/css-library@0.36.1 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 ``` 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. ``` ## 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. - VA Design System Fondamenti ufficiali, contenuti, componenti e governance. - Pattern VA Pattern per attività di richiesta, precompilazione, firme e ripristino. - Componenti VA Specifiche dei componenti, decisioni e materiali sull’accessibilità. - 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 sistema di design VA ### W3C sistema di design Crea interfacce di lettura flessibili con tipografia fluida, ruoli semantici dei colori e contenuti comprimibili nativi, sempre leggibili anche senza JavaScript. ### Codex Usa la struttura effettiva di SearchInput di Codex, la gerarchia delle azioni e i token pensati per la lettura. Cerca in un indice locale di articoli, esamina un risultato e torna alla stessa posizione di lettura. ### 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. - [Riferimento per l’implementazione](https://design.va.gov/components/process-list) - [Fonte](https://design.va.gov/foundation/design-tokens/typography) - [Fonte](https://design.va.gov/foundation/design-tokens/spacing) - [Fonte](https://design.va.gov/foundation/design-tokens/color) - [Fonte](https://design.va.gov/foundation/design-tokens/breakpoints) - [Leggi la specifica di supporto](https://design.va.gov/about/developers/install) - [Leggi la specifica di supporto](https://design.va.gov/foundation/design-tokens/typography) - [Leggi la specifica di supporto](https://design.va.gov/foundation/design-tokens/spacing) - [Leggi la specifica di supporto](https://design.va.gov/foundation/design-tokens/color) - [Leggi la specifica di supporto](https://design.va.gov/foundation/design-tokens/breakpoints) - [Riferimento del codice](https://design.va.gov/components/process-list) - [Leggi la specifica di supporto](https://design.va.gov/components/process-list) - [VA Design System Fondamenti ufficiali, contenuti, componenti e governance.](https://design.va.gov/) - [Pattern VA Pattern per attività di richiesta, precompilazione, firme e ripristino.](https://design.va.gov/patterns/) - [Componenti VA Specifiche dei componenti, decisioni e materiali sull’accessibilità.](https://design.va.gov/components/)