Administración pública y servicios públicos · Nuevo recurso
Sistema de diseño VA.
Crea recorridos de servicio claros con los tokens semánticos de VA y la Process List nativa: explicaciones visibles de cada paso, etiquetas de estado significativas y detalles complementarios que mantienen legible el recorrido principal.
Web Components nativos de VA 24.14.0 (dependencia de component-library 56.14.0) y tokens de css-library 0.36.1; controlador de escenario original y fuentes de reserva. · Referencia de implementación
02
Referencia de diseño de sistema de diseño VA
Variables publicadas de css-library 0.36.1 y dependencia web-components 24.14.0 de component-library 56.14.0. Las fuentes son alternativas locales explícitas. El contenedor de muestra de 52rem es una elección de la aplicación.
Sistema de diseño VA Un sistema de servicios para veteranos
Los fundamentos y los componentes son paquetes independientes
El sistema de VA combina patrones de servicio, pautas de contenido, tokens, utilidades de CSS y Web Components. La instalación documentada usa un paquete CSS-library para los fundamentos globales y un paquete component-library para los elementos interactivos. Esta referencia combina component-library 56.14.0 con css-library 0.36.1; ambos paquetes tienen números de versión independientes.
El ejemplo es una explicación ficticia sobre una solicitud de registros. Muestra cómo una lista de procesos comunica el progreso, sin afirmar que se haya presentado una solicitud ni que alguien reúna los requisitos para recibir una prestación. No incluye el logotipo de VA, un banner de identidad gubernamental, datos personales ni el estado de un caso real. El contenido de producción de un servicio aún debe verificarse con el programa de VA responsable.
Sistema de diseño VA Roles tipográficos semánticos
Las familias para el cuerpo y los encabezados son deliberadamente distintas
La familia semántica para encabezados es Bitter, con Georgia y otras fuentes serif como alternativas. La pila para el cuerpo empieza con Source Sans Pro Web y Source Sans Pro, seguidas de fuentes sans serif de la plataforma. El rol predeterminado para el cuerpo es 1.06rem, aproximadamente 17px con una raíz de 16px; los encabezados usan 40px para el nivel 1, 32px para el nivel 2, 20px para el nivel 3 y aproximadamente 17px para el nivel 4.
Usa --vads-font-size-body-default en lugar del nombre anterior source-sans-normalized. El token semántico expresa el rol, mientras que el nombre de normalización anterior revela un detalle de implementación de la fuente. La vista previa usa explícitamente Arial para el texto del cuerpo y Georgia para los encabezados. El componente de proceso nativo CSS sigue controlando su estructura interna y sus tamaños; esta fuente alternativa no pretende reproducir las métricas exactas de Source Sans y Bitter.
La altura de línea predeterminada es 1.5 para los párrafos y 1.2 para los encabezados. El texto introductorio del cuerpo tiene un rol de 1.75; el token de altura de línea serif es 1.9 y está pensado para texto corrido serif, no para todos los encabezados serif. Asignar 1.9 a un encabezado compacto de proceso confundiría dos roles distintos. Los elementos de proceso de esta muestra usan el nivel 3 debajo del título de sección de nivel 2 de la página.
Sistema de diseño VA Espaciado y diseño semánticos
Distingue una pila común de una pila de formulario
El valor predeterminado de la pila vertical general es 1rem/16px. El valor predeterminado de la pila vertical de formularios es 2rem/32px. Esta diferencia es útil: dos breves elementos explicativos necesitan un ritmo distinto al de preguntas separadas con etiquetas, indicaciones, controles y errores. Los valores de inserción s, m y l corresponden a 16, 24 y 32px, respectivamente.
La escala de espaciado primitivo incluye 4, 8, 12, 16, 20 y 24px, además de incrementos de ocho píxeles y valores especiales de uno y dos píxeles. Prefiere los nombres semánticos de espaciado cuando su propósito coincida con el diseño. El contenedor exterior de 52rem del ejemplo es una decisión de la aplicación, mientras que el margen interior de 24px y la separación de 32px entre secciones usan valores publicados de la escala. No impone ese contenedor a todas las plantillas de páginas de VA.
El token de texto actual es --vads-color-text (#1b1b1b). --vads-color-link es #005ea2 y el rol de enlace activo es #0b4778; no son iguales a todas las entradas más oscuras de la familia principal. El rol de error es #d54309. La familia roja secundaria heredada está obsoleta para este propósito, así que un nuevo tratamiento de validación debe referirse a la semántica de error, no a la secundaria.
Las tablas de valores primitivos y semánticos se generan a partir de una versión específica de CSS-library. El ejemplo carga esas variables reales en lugar de copiar una paleta antigua de USWDS y etiquetarla como VA. Sus componentes nativos pueden incluir valores compilados propios además de esas variables; verifica ambas capas al actualizar.
Sistema de diseño VA Anatomía de la lista de procesos
De tres a diez pasos significativos
La lista de procesos de VA también se describe como un mapa de metro. Explica un proceso largo o indica en qué punto se encuentra una persona. Las pautas recomiendan de tres a diez pasos y solo una lista de este tipo por página. Cada elemento necesita un encabezado conciso que empiece con un verbo y contenido explicativo visible; no es un número decorativo junto a un título sin contenido.
Las etiquetas nativas son va-process-list y va-process-list-item. Un elemento admite header y level, además de active, pending, checkmark y status-text. El módulo publicado del componente da prioridad a checkmark, luego a active y después a pending. Evita combinaciones contradictorias desactivando los otros estados booleanos al establecer uno. El texto de estado explícito acompaña el estilo del estado y permite entender la etapa sin depender del color.
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 diseño VA Details permite mostrar un paso
No conviertas cada paso en un acordeón
Las pautas del proceso no permiten combinar el encabezado de un acordeón con un paso del proceso. Ocultar todas las explicaciones va en contra del propósito de mostrar el proceso. Sí permiten incluir un componente Details dentro de un paso para mostrar información complementaria. El ejemplo mantiene visible la explicación sobre la identificación del registro y coloca una ampliación opcional en va-details.
El atributo label del componente se convierte en la pregunta visible del panel desplegable. Una pregunta breve es más útil que «Más información», porque indica a los lectores si el contenido oculto les será pertinente. En este ejemplo, los detalles explican qué podría ayudar a identificar un registro e incluyen una nota explícita de que son opciones de contenido ilustrativas, no instrucciones para un procedimiento específico de VA.
Mantén visible un resumen de cada etapa, incluidas las etapas marcadas como Pendiente.
Usa un panel Details solo para una explicación secundaria dentro de una etapa.
Mantén la siguiente acción real del servicio fuera del encabezado del proceso, en lugar de convertir el encabezado en un control.
Sistema de diseño VA Demostración de estados y veracidad
Usa un selector de escenarios, no un progreso ficticio
El selector de etapas de ejemplo de la vista previa cambia el ejemplo del componente entre preparación, envío y revisión de la respuesta. No hace avanzar una solicitud real, calcula un tiempo oficial de procesamiento ni infiere que el proceso se completó porque alguien hizo clic en un botón. Un servicio activo debe asignar los estados verificados del backend a estos estados visuales y explicar por separado el significado de cualquier demora.
Al cambiar el selector, las etapas anteriores pasan a Completada, la etapa seleccionada pasa a Activa y las posteriores quedan como Pendiente. Un mensaje de estado dinámico anuncia el cambio de estado del ejemplo. Las tres explicaciones permanecen visibles y se conserva el estado opcional de Details. Restablecer vuelve a la primera etapa ilustrativa y cierra el panel complementario.
Sistema de diseño VA Carga componentes web nativos
Regístralos una sola vez y conserva las dependencias
La ruta documentada del empaquetador importa main.css y llama a defineCustomElements desde el paquete component-library. Las fuentes provienen de CSS-library y se distribuyen por separado. Los componentes que usan el sprite de iconos necesitan una ruta al sprite del mismo origen; de forma predeterminada, /img/sprite.svg. Son requisitos reales de integración, no detalles opcionales que se puedan descubrir después de la implementación.
El ejemplo independiente usa el punto de entrada ESM oficial para navegadores de web-components 24.14.0, la dependencia declarada por component-library 56.14.0, además de los módulos diferidos específicos de Process List, Process List Item y Details. El script de la aplicación solo selecciona los estados de ejemplo. El entorno de ejecución del navegador proporciona el comportamiento de los elementos personalizados nativos, incluido el control Details.
Carga el token CSS correspondiente y el punto de entrada de componentes para navegador, conservando las rutas relativas de los módulos.
Espera a que se defina va-process-list-item antes de asignar las propiedades de estado de ejemplo.
Prueba todos los estados de los escenarios, el control de teclado de Details y los anchos reducidos sin ocultar el contenido explicativo.
Sistema de diseño VA Ejemplos de componentes del sistema de diseño
Una explicación nativa en tres etapas
Atributos reales de Web Components y un panel Details permitido dentro de un paso.
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 entre 3 y 10 pasos y una sola lista de procesos por página.
No sustituyas los encabezados de los pasos por controles de acordeón.
Establece solo una marca de estado en cada elemento.
Ejemplo independiente completo
El documento completo incluye su estructura, controles e inicialización. Extrae el archivo de ejemplo enlazado para obtener los recursos del proveedor con sus rutas relativas exactas y luego sírvelo mediante 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>
Descarga el ejemplo completo desde Fuentes. El README contiene el comando exacto para ejecutarlo en local.
Mantén las rutas de los recursos del proveedor relativas a este documento; el archivo incluye todos los recursos que utiliza esta vista previa.
04
Sistema de diseño VA Configuración del agente
Punto de partida para la implementación
Inicialización documentada del empaquetador con versiones de paquetes verificadas. El ejemplo independiente para navegador usa la distribución ESM correspondiente de componentes web nativos, en lugar de una compilación de React. El ZIP con el ejemplo completo y funcional, disponible en Sources, también incluye las dependencias exactas de la vista previa y el documento completo. Extráelo, ejecuta python3 -m http.server 8080 en ese directorio y abre http://localhost:8080/va.html. No abras ejemplos basados en módulos mediante 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.
Una instrucción para tu proyecto
Instrucción para el agente
Crea una explicación del proceso de servicio de VA con un elemento va-process-list que contenga de tres a diez elementos va-process-list-item. Usa encabezados que comiencen con verbos, level=3 debajo de un h2, descripciones visibles y un único estado activo, pendiente o con marca de verificación por elemento, con status-text explícito. Usa va-details solo para texto complementario dentro de un paso; nunca ocultes el paso completo. Importa el archivo actual de tokens VADS CSS y registra los componentes nativos. Mantén el cuerpo de texto de 17px, las funciones de las familias Bitter/Source Sans, el espaciado semántico y los puntos de corte de 320/480/640/880/1024/1201/1400px. Toda muestra interactiva debe indicar que sus etapas son ilustrativas y nunca hacerse pasar por una solicitud de VA enviada.
05
Fuentes y alcance de sistema de diseño VA
Demostración técnica de componentes con etapas ficticias de solicitud de registros. No representa ninguna solicitud real a VA, estado de caso, decisión sobre prestaciones ni respaldo institucional.
