Gestalte klare Serviceabläufe mit den semantischen Tokens von VA und der nativen Process List: sichtbare Erläuterungen zu den einzelnen Schritten, aussagekräftige Statusbezeichnungen und ergänzende Details, die den Hauptablauf übersichtlich halten.
Native VA-Web-Components 24.14.0 (Abhängigkeit von component-library 56.14.0) und Tokens aus css-library 0.36.1; eigener Szenariocontroller und Ersatzschriften. · Implementierungsreferenz
02
VA Designsystem-Designreferenz
Veröffentlichte Variablen aus css-library 0.36.1 und Web Components 24.14.0 als Abhängigkeit von component-library 56.14.0. Die Schriften sind ausdrücklich lokale Ersatzschriften. Der 52rem breite Beispielcontainer ist eine Entscheidung auf Anwendungsebene.
Das VA-System umfasst Servicemuster, Inhaltsrichtlinien, Tokens, CSS-Hilfsfunktionen und Web Components. Für die dokumentierte Installation wird ein CSS-library-Paket für die globalen Grundlagen und ein component-library-Paket für interaktive Elemente verwendet. Diese Referenz kombiniert component-library 56.14.0 mit css-library 0.36.1; die Pakete haben voneinander unabhängige Versionsnummern.
Das Beispiel erläutert fiktiv eine Anfrage zu Unterlagen. Es zeigt, wie eine Prozessliste den Fortschritt vermittelt, ohne zu behaupten, dass eine Anfrage eingereicht wurde oder jemand Anspruch auf eine Leistung hat. Es sind weder ein VA-Logo noch ein Banner mit Regierungskennzeichnung, persönliche Unterlagen oder ein tatsächlicher Fallstatus zu sehen. Texte für einen Produktiveinsatz müssen weiterhin mit dem zuständigen VA-Programm abgestimmt werden.
Schriftfamilien für Fließtext und Überschriften unterscheiden sich bewusst
Die semantische Schriftfamilie für Überschriften ist Bitter, mit Georgia und weiteren Serifen-Ersatzschriften. Der Schriftstapel für Fließtext beginnt mit Source Sans Pro Web und Source Sans Pro, gefolgt von plattformabhängigen serifenlosen Ersatzschriften. Die Standardrolle für Fließtext beträgt 1.06rem, also ungefähr 17px bei einer Root-Größe von 16px. Überschriften verwenden 40px für Ebene 1, 32px für Ebene 2, 20px für Ebene 3 und etwa 17px für Ebene 4.
Verwenden Sie --vads-font-size-body-default anstelle des älteren Namens source-sans-normalized. Das semantische Token bezeichnet die Rolle, während der ältere Normalisierungsname ein Implementierungsdetail der Schrift offenlegt. In der Vorschau werden ausdrücklich Arial für Fließtext und Georgia für Überschriften verwendet. Die native Prozesskomponente CSS bestimmt weiterhin ihre interne Struktur und Größen. Die Ersatzschrift gibt nicht vor, die genauen Metriken von Source Sans und Bitter wiederzugeben.
Der Standardwert für die Zeilenhöhe von Absätzen beträgt 1.5, für Überschriften 1.2. Fließtext mit hervorgehobener Rolle hat eine Zeilenhöhe von 1.75. Das Serifen-Zeilenhöhen-Token beträgt 1.9 und ist für fortlaufenden Text mit Serifen gedacht, nicht für jede Überschrift mit Serifen. Der Wert 1.9 für eine kompakte Prozessüberschrift zu verwenden, würde zwei unterschiedliche Rollen verwechseln. Die Prozesselemente in diesem Beispiel verwenden Ebene 3 unterhalb des Abschnittstitels der Seite auf Ebene 2.
Einen gewöhnlichen Abstandsstapel von einem Formular unterscheiden
Der allgemeine Standardabstand für vertikale Stapel beträgt 1rem/16px. Bei Formularen beträgt der Standardabstand für vertikale Stapel 2rem/32px. Dieser Unterschied ist sinnvoll: Zwei kurze Erläuterungen benötigen einen anderen Rhythmus als einzelne Fragen mit Beschriftungen, Hinweisen, Steuerelementen und Fehlermeldungen. Die Innenabstände s, m und l entsprechen 16, 24 bzw. 32px.
Die primitive Abstandsreihe umfasst 4, 8, 12, 16, 20 und 24px sowie größere Schritte von jeweils acht Pixeln und spezielle Werte von einem und zwei Pixeln. Bevorzuge semantische Abstandsnamen, wenn ihre Bedeutung zum Layout passt. Die äußere Hülle von 52rem im Beispiel ist eine Anwendungsentscheidung; der Innenabstand von 24px und der Abschnittsabstand von 32px verwenden dagegen veröffentlichte Skalenwerte. Die Hülle ist nicht für jede VA-Seitenvorlage vorgeschrieben.
Eine Rolle statt eines historischen Alias verwenden
Das aktuelle Text-Token ist --vads-color-text (#1b1b1b). --vads-color-link hat den Wert #005ea2, die Rolle für aktive Links den Wert #0b4778; diese Werte entsprechen nicht allen dunkleren Einträgen der Primärfarbpalette. Die Fehlermeldungsrolle hat den Wert #d54309. Die geerbte sekundäre Rotpalette ist für diesen Zweck veraltet. Eine neue Validierungsdarstellung sollte daher auf die Fehlersemantik statt auf die Sekundärfarbe verweisen.
Die Tabellen mit primitiven und semantischen Tokens werden anhand eines benannten Releases von CSS-library generiert. Das Beispiel lädt die tatsächlichen Variablen, statt eine alte USWDS-Palette zu kopieren und als VA-Palette auszugeben. Die nativen Komponenten können zusätzlich zu diesen Variablen eigene, einkompilierte Werte enthalten. Prüfe bei einer Aktualisierung beide Ebenen.
Die VA Process List wird auch als U-Bahn-Karte beschrieben. Sie erläutert einen längeren Ablauf oder zeigt an, an welcher Stelle sich eine Person darin befindet. Die Richtlinien empfehlen drei bis zehn Schritte und höchstens eine solche Liste pro Seite. Jeder Eintrag benötigt eine prägnante, mit einem Verb beginnende Überschrift und sichtbare Erläuterungen. Eine dekorative Zahl neben einer ansonsten leeren Überschrift reicht nicht aus.
Die nativen Tags sind va-process-list und va-process-list-item. Ein Element verwendet header und level sowie active, pending, checkmark und status-text. Im veröffentlichten Komponentenmodul hat checkmark Vorrang, gefolgt von active und dann pending. Vermeide widersprüchliche Kombinationen, indem du beim Setzen eines booleschen Status die anderen zurücksetzt. Expliziter Statustext ergänzt die Statusdarstellung und macht die Phase verständlich, ohne dass die Farbe interpretiert werden muss.
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>
VA Designsystem Details ergänzen einen sichtbaren Schritt
Nicht jeden Schritt in ein Akkordeon verwandeln
Die Process-List-Richtlinien raten davon ab, eine Akkordeonüberschrift mit einem Prozessschritt zu kombinieren. Alle Erläuterungen auszublenden, vereitelt den Zweck, den Ablauf sichtbar zu machen. Innerhalb eines Schritts ist jedoch eine Details-Komponente für ergänzende Informationen zulässig. Im Beispiel bleibt die Erläuterung zur Identifizierung eines Eintrags sichtbar; eine optionale Ergänzung befindet sich in va-details.
Das Attribut label der Komponente wird zur sichtbaren Frage des Offenlegungsbereichs. Eine kurze Frage ist hilfreicher als „Weitere Informationen“, weil sie den Lesenden zeigt, ob der verborgene Inhalt relevant ist. In diesem Beispiel wird erläutert, was bei der Identifizierung eines Eintrags hilfreich sein kann. Ein ausdrücklicher Hinweis stellt klar, dass es sich um beispielhafte Inhalte und nicht um Anweisungen für ein bestimmtes VA-Verfahren handelt.
Eine Zusammenfassung jeder Phase sichtbar halten, auch bei Phasen mit dem Status „Ausstehend“.
Eine Details-Offenlegung nur für ergänzende Erläuterungen innerhalb einer Phase verwenden.
Die nächste tatsächliche Serviceaktion außerhalb der Prozessüberschrift platzieren, statt die Überschrift in ein Steuerelement zu verwandeln.
VA Designsystem Statusdemonstration und Wahrheitsgehalt
Einen Szenario-Auswahlschalter statt eines vorgetäuschten Fortschritts verwenden
Die Szenarioauswahl „Beispielphase“ in der Vorschau wechselt zwischen den Zuständen Vorbereitung, Übermittlung und Prüfung der Antwort. Sie führt keine echte Anfrage weiter, schätzt keine offizielle Bearbeitungsdauer und leitet den Abschluss nicht daraus ab, dass eine Person auf eine Schaltfläche klickt. Ein aktiver Service sollte einen verifizierten Backend-Status auf diese visuellen Zustände abbilden und Verzögerungen separat erläutern.
Beim Ändern der Auswahl werden vorherige Phasen auf „Abgeschlossen“, die ausgewählte Phase auf „Aktiv“ und spätere Phasen auf „Ausstehend“ gesetzt. Ein Live-Statustext gibt die Änderung des Beispielstatus bekannt. Alle drei Erläuterungen bleiben sichtbar, und der optionale Zustand „Details“ bleibt erhalten. Durch Zurücksetzen wird die erste Beispielphase wiederhergestellt und die ergänzende Offenlegung geschlossen.
Einmal registrieren und Abhängigkeiten beibehalten
Der dokumentierte Bundler-Weg importiert main.css und ruft defineCustomElements aus dem Paket component-library auf. Die Schriftarten stammen aus CSS-library und werden separat bereitgestellt. Komponenten, die das Icon-Sprite verwenden, benötigen einen Sprite-Pfad gleichen Ursprungs; standardmäßig ist dies /img/sprite.svg. Dabei handelt es sich um tatsächliche Integrationsanforderungen und nicht um optionalen Feinschliff, den man erst nach der Bereitstellung entdeckt.
Das eigenständige Beispiel verwendet den offiziellen ESM-Browser-Einstieg aus web-components 24.14.0, die von component-library 56.14.0 deklarierte Abhängigkeit sowie die spezifischen Lazy-Module für Process List, Process List Item und Details. Das Anwendungsskript wählt lediglich Beispielzustände aus. Die Browserlaufzeit stellt das Verhalten der nativen Custom Elements bereit, einschließlich des Details-Steuerelements.
Das passende Token-CSS und den Browser-Komponenteneinstieg laden; dabei die relativen Modulpfade beibehalten.
Vor dem Zuweisen von Beispielzuständen warten, bis va-process-list-item definiert ist.
Alle Szenariozustände, die Tastaturbedienung von Details und schmale Ansichtsbreiten testen, ohne Erläuterungen auszublenden.
VA Designsystem Beispiele für VA-Designsystem-Komponenten
Eine native Erläuterung in drei Phasen
Echte Web-Component-Attribute und eine zulässige Details-Offenlegung innerhalb eines Schritts.
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>
3–10 Schritte und eine Process List pro Seite verwenden.
Schrittüberschriften nicht durch Akkordeon-Auslöser ersetzen.
Für jedes Element darf nur ein Statuskennzeichen gesetzt sein.
Vollständiges eigenständiges Beispiel
Das vollständige Dokument enthält Layout, Steuerelemente und Initialisierung. Entpacken Sie das verknüpfte Beispielarchiv, um die exakten relativen Vendor-Assets zu erhalten, und stellen Sie es anschließend über HTTP bereit.
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>
Laden Sie das vollständige Beispiel unter Sources herunter. Die README enthält den genauen lokalen Startbefehl.
Behalten Sie die Vendor-Pfade relativ zu diesem Dokument bei. Das Archiv enthält alle Assets, die in dieser Vorschau verwendet werden.
04
VA Designsystem Agent einrichten
Ausgangspunkt für die Implementierung
Dokumentierte Initialisierung des Bundlers mit verifizierten Paketversionen. Das eigenständige Browserbeispiel verwendet anstelle eines React-Builds die entsprechende native ESM-Distribution der Web Components. Das vollständige ZIP mit dem funktionsfähigen Beispiel unter „Quellen“ enthält außerdem die exakten Abhängigkeiten für die Vorschau und das vollständige Dokument. Entpacken Sie es, führen Sie in diesem Verzeichnis python3 -m http.server 8080 aus und öffnen Sie anschließend http://localhost:8080/va.html. Öffnen Sie Beispiele mit Modulen nicht über 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.
Ein Prompt für dein Projekt
Agenten-Prompt
Erstellen Sie eine Erläuterung zum VA-Dienstprozess mit einem va-process-list und drei bis zehn va-process-list-item-Elementen. Verwenden Sie handlungsorientierte Überschriften, level=3 unter einem h2, sichtbare Beschreibungen und pro Element genau einen Status für aktiv, ausstehend oder erledigt – jeweils mit explizitem status-text. Verwenden Sie va-details nur für ergänzende Informationen innerhalb eines Schritts und blenden Sie niemals den gesamten Schritt aus. Importieren Sie die aktuelle VADS-CSS-Token-Datei und registrieren Sie die nativen Komponenten. Behalten Sie 17px Fließtext, die Rollen der Schriftfamilien Bitter/Source Sans, semantische Abstände und die Haltepunkte 320/480/640/880/1024/1201/1400px bei. Jede interaktive Vorschau muss ihre Phasen ausdrücklich als veranschaulichend kennzeichnen und darf nicht den Eindruck erwecken, sie stelle einen eingereichten VA-Antrag dar.
05
VA Designsystem Quellen und Umfang
Technische Komponentendemonstration mit fiktiven Phasen einer Aktenanfrage. Es werden weder eine echte VA-Anfrage noch ein tatsächlicher Fallstatus oder Leistungsbescheid dargestellt oder eine institutionelle Unterstützung suggeriert.
