Создавайте понятные сценарии получения услуг с семантическими токенами VA и нативным списком Process List: наглядными пояснениями к этапам, содержательными обозначениями статуса и дополнительными сведениями, не мешающими воспринимать основной маршрут.
Нативные веб-компоненты VA 24.14.0 (зависимость component-library 56.14.0) и токены css-library 0.36.1; исходный контроллер сценария и резервные шрифты. · Справочник по реализации
02
Дизайн-система VA Справочник по дизайну
Опубликованные переменные css-library 0.36.1 и веб-компоненты-зависимость component-library 56.14.0, версия 24.14.0. Резервные шрифты указаны явно. Оболочка примера шириной 52rem — решение на уровне приложения.
Фундаментальные стили и компоненты — отдельные пакеты
Система VA объединяет шаблоны сервисов, рекомендации по контенту, токены, утилиты CSS и веб-компоненты. В документированном сценарии установки для глобальных фундаментальных стилей используется пакет CSS-library, а для интерактивных элементов — пакет component-library. В этом справочнике используются component-library 56.14.0 и css-library 0.36.1; у этих пакетов независимая нумерация версий.
В примере показано вымышленное пояснение процесса запроса записей. Он объясняет, как список этапов отражает ход процесса, и не утверждает, что запрос был отправлен или что человек имеет право на получение пособия. Здесь нет логотипа VA, баннера с символикой правительства, личной записи или реального статуса дела. Перед публикацией тексты сервисов должны быть проверены ответственным подразделением VA.
Для основного текста и заголовков намеренно используются разные семейства шрифтов
Для семантических заголовков используется Bitter с резервными шрифтами Georgia и другими шрифтами с засечками. Стек основного текста начинается с Source Sans Pro Web и Source Sans Pro, за которыми следуют системные шрифты без засечек. Размер по умолчанию для роли основного текста — 1.06rem, то есть примерно 17px при корневом размере 16px; для заголовков используются размеры 40px для уровня 1, 32px для уровня 2, 20px для уровня 3 и примерно 17px для уровня 4.
Используйте --vads-font-size-body-default вместо прежнего имени source-sans-normalized. Семантический токен указывает на роль, а старое имя нормализации раскрывает деталь реализации шрифта. В примере для основного текста явно задан Arial, а для заголовков — Georgia. Нативный компонент Process List CSS по-прежнему самостоятельно управляет своей внутренней структурой и размерами; резервный вариант не претендует на точное воспроизведение метрик Source Sans и Bitter.
Межстрочный интервал по умолчанию составляет 1.5 для абзацев и 1.2 для заголовков. Для вводного текста предусмотрено значение 1.75; токен межстрочного интервала для шрифтов с засечками — 1.9 — предназначен для обычного текста с засечками, а не для всех заголовков с засечками. Значение 1.9 для компактного заголовка этапа процесса смешало бы две разные роли. Элементы процесса в этом примере используют уровень 3 внутри раздела страницы с заголовком уровня 2.
Для общего вертикального стека по умолчанию используется 1rem/16px, а для форм — 2rem/32px. Это различие полезно: два коротких пояснительных пункта требуют другого ритма, чем отдельные вопросы с метками, подсказками, полями и сообщениями об ошибках. Внутренние отступы s, m и l соответствуют 16, 24 и 32px.
Семейство примитивных интервалов включает 4, 8, 12, 16, 20 и 24px, более крупные значения с шагом в восемь пикселей, а также специальные значения в один и два пикселя. Если назначение семантического имени соответствует макету, отдавайте предпочтение ему. Внешняя оболочка примера шириной 52rem — решение на уровне приложения, а внутренний отступ 24px и расстояние между разделами 32px взяты из опубликованной шкалы. Эта оболочка не является обязательной для всех шаблонов страниц VA.
Текущий токен цвета текста — --vads-color-text (#1b1b1b). Для --vads-color-link задано значение #005ea2, а для активной ссылки — #0b4778; они не совпадают со всеми более тёмными цветами из основной палитры. Роль error соответствует цвету #d54309. Унаследованное семейство secondary red для этой цели устарело, поэтому для нового оформления проверки следует использовать семантику error, а не secondary.
Таблицы примитивных и семантических токенов созданы на основе указанной версии CSS-library. В примере загружаются настоящие переменные, а не скопированная старая палитра USWDS, выданная за палитру VA. Помимо этих переменных, нативные компоненты могут содержать собственные скомпилированные значения; при обновлении проверяйте оба уровня.
Process List в системе VA также описывается как схема метро. Он объясняет длительный процесс или показывает, на каком его этапе находится человек. Рекомендации предусматривают от трёх до десяти этапов и только один такой список на странице. Для каждого пункта нужен краткий заголовок, начинающийся с глагола, и видимое пояснение; это не декоративный номер рядом с пустым заголовком.
Используются нативные теги va-process-list и va-process-list-item. Для элемента задаются атрибуты header и level, а также active, pending, checkmark и status-text. В опубликованном модуле компонента приоритеты заданы в следующем порядке: checkmark, затем active, затем pending. Не допускайте противоречивых сочетаний: при установке одного булева состояния сбрасывайте остальные. Стиль статуса должен сопровождаться явно заданным текстом, чтобы этап был понятен и без цвета.
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 Используйте Details как дополнение к видимому этапу
Не превращайте каждый этап в аккордеон
Рекомендации по Process List запрещают объединять заголовок аккордеона с этапом процесса. Если скрыть все пояснения, исчезнет смысл отображения процесса. Однако внутри этапа можно использовать компонент Details для дополнительной информации. В примере пояснение об идентификации записи остаётся видимым, а необязательное дополнение размещено в va-details.
Значение атрибута label компонента отображается как видимый вопрос раскрывающегося блока. Краткий вопрос полезнее, чем «Дополнительная информация»: по нему читатели могут понять, относится ли к ним скрытое содержимое. В этом примере блок поясняет, что может помочь определить запись; также прямо указано, что это наглядный текст, а не инструкция для конкретной процедуры VA.
Держите сводку по каждому этапу на виду, в том числе по этапам со статусом «Ожидает».
Используйте Details только для дополнительного пояснения внутри этапа.
Размещайте следующее реальное действие сервиса за пределами заголовка этапа, а не превращайте заголовок в элемент управления.
Дизайн-система VA Демонстрация статусов и достоверность
Используйте переключатель сценария, а не имитацию прогресса
Переключатель этапов в примере меняет отображение компонента, позволяя посмотреть на подготовку, отправку и проверку ответа. Он не продвигает реальный запрос, не оценивает официальный срок обработки и не определяет завершение по нажатию кнопки пользователем. В рабочем сервисе визуальные состояния должны соответствовать проверенным данным из серверной части, а значение возможной задержки нужно объяснять отдельно.
При смене выбранного этапа предыдущие отмечаются как «Завершено», выбранный — как «Текущий», а последующие — как «Ожидает». Об изменении состояния примера сообщает динамически обновляемое предложение. Пояснения ко всем трём этапам остаются видимыми, а состояние дополнительного блока Details сохраняется. Сброс возвращает пример к первому этапу и закрывает дополнительный блок.
Дизайн-система VA Подключение нативных веб-компонентов
Зарегистрируйте компоненты один раз и сохраните зависимости
В документированном сценарии сборки импортируется main.css, а из пакета component-library вызывается defineCustomElements. Шрифты подключаются из CSS-library и поставляются отдельно. Компонентам, использующим спрайт значков, нужен путь к спрайту с того же источника; по умолчанию это /img/sprite.svg. Это реальные требования к интеграции, а не необязательная полировка, о которой можно вспомнить уже после развертывания.
В отдельном примере используется официальный браузерный ESM-вход из web-components 24.14.0 — зависимости, указанной в component-library 56.14.0, — а также специальные ленивые модули для Process List, Process List Item и Details. Скрипт приложения только переключает состояния примера. Среда выполнения браузера обеспечивает работу нативных пользовательских элементов, в том числе элемента управления Details.
Подключите соответствующие токен CSS и браузерную точку входа компонентов, сохранив относительное расположение модулей.
Дождитесь определения va-process-list-item, прежде чем назначать примерам свойства состояния.
Проверьте все сценарии состояний, клавиатурное управление Details и отображение на узких экранах, не скрывая пояснительный текст.
Дизайн-система VA Примеры компонентов дизайн-системы
Объяснение из трёх этапов на нативных компонентах
Реальные атрибуты Web Components и допустимое раскрытие Details внутри шага.
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 шагов и один Process List на странице.
Не заменяйте заголовки шагов триггерами аккордеона.
Для каждого элемента можно установить только один флаг состояния.
Полный автономный пример
Полный документ включает разметку, элементы управления и инициализацию. Распакуйте связанный архив примера, чтобы получить нужные относительные пути к ресурсам поставщика, затем запустите его через 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>
Скачайте полный пример из раздела «Источники». Точная команда локального запуска приведена в README.
Оставьте пути к ресурсам поставщика относительными к этому документу; архив включает все ресурсы, используемые в предварительном просмотре.
04
Дизайн-система VA Настройка AI-агента
Отправная точка для реализации
Документированная инициализация сборщика с проверенными версиями пакетов. В автономном примере для браузера используется соответствующий дистрибутив нативных веб-компонентов ESM, а не сборка React. В ZIP-архиве с полным рабочим примером в разделе Sources также доступны точные зависимости для предпросмотра и полный документ. Распакуйте архив, запустите в этой директории команду python3 -m http.server 8080, затем откройте http://localhost:8080/va.html. Не открывайте примеры с модулями через 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.
Запрос для вашего проекта
Промпт для AI-агента
Создайте объяснение процесса обслуживания VA с одним va-process-list, содержащим от трёх до десяти элементов va-process-list-item. Используйте заголовки, начинающиеся с глагола, уровень level=3 внутри раздела с заголовком h2, видимые описания и только одно состояние для каждого элемента — active, pending или checkmark — с явным указанием status-text. Используйте va-details только для дополнительного текста внутри шага и никогда не скрывайте весь шаг. Импортируйте актуальный файл токенов VADS CSS и зарегистрируйте нативные компоненты. Сохраните основной текст размером 17px, роли шрифтов Bitter/Source Sans, семантические отступы и контрольные точки 320/480/640/880/1024/1201/1400px. В каждом интерактивном примере укажите, что этапы иллюстративные, и не создавайте впечатление, будто это отправленная заявка в VA.
05
Дизайн-система VA Источники и область применения
Техническая демонстрация компонентов с вымышленными этапами запроса записей. Здесь не показаны реальный запрос в VA, статус дела, решение о назначении пособия или одобрение со стороны учреждения.
