VA 시스템은 서비스 패턴, 콘텐츠 가이드, 토큰, CSS 유틸리티와 Web Components로 구성됩니다. 문서에 안내된 설치 방법에서는 전역 기반 요소에 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이며 루트 크기 16px 기준 약 17px입니다. 제목은 1단계 40px, 2단계 32px, 3단계 20px, 4단계 약 17px입니다.
이전 이름인 source-sans-normalized 대신 --vads-font-size-body-default를 사용하세요. 의미 기반 토큰은 역할을 나타내지만, 이전 정규화 이름은 글꼴 구현 세부 사항을 드러냅니다. 미리보기에서는 본문에 Arial, 제목에 Georgia를 명시적으로 사용합니다. 기본 프로세스 컴포넌트 CSS는 내부 구조와 크기를 계속 관리합니다. 대체 글꼴을 사용하더라도 Source Sans와 Bitter의 정확한 글꼴 특성을 재현한다고 볼 수는 없습니다.
기본 문단의 줄 높이는 1.5이고 제목은 1.2입니다. 도입부 본문 텍스트의 줄 높이는 1.75이며, 세리프 글꼴 줄 높이 토큰은 1.9로, 모든 세리프 제목이 아닌 세리프 본문 텍스트를 위한 값입니다. 간결한 프로세스 제목에 1.9를 적용하면 서로 다른 두 역할을 혼동하게 됩니다. 이 예시의 프로세스 항목은 페이지의 2단계 섹션 제목 아래에서 3단계 제목을 사용합니다.
일반 vertical-stack-default는 1rem/16px입니다. forms vertical-stack-default는 2rem/32px입니다. 이 차이는 유용합니다. 짧은 설명 항목 두 개에 필요한 간격과 라벨, 힌트, 컨트롤, 오류가 있는 별개의 질문들에 필요한 간격은 다르기 때문입니다. 인셋 s, m, l은 각각 16, 24, 32px에 해당합니다.
기본 간격 계열에는 4, 8, 12, 16, 20, 24px과 그보다 큰 8px 단위의 간격, 그리고 1px과 2px의 특수 값이 포함됩니다. 용도가 레이아웃에 맞으면 의미 기반 간격 이름을 우선 사용하세요. 예시의 바깥 셸 52rem은 애플리케이션에서 선택한 값이고, 인셋 24px과 섹션 간격 32px은 공개된 간격 척도 값을 사용합니다. 모든 VA 페이지 템플릿에 해당 셸을 적용해야 한다는 뜻은 아닙니다.
현재 텍스트 토큰은 --vads-color-text (#1b1b1b)입니다. --vads-color-link는 #005ea2이고 링크 활성 역할은 #0b4778입니다. 두 값은 기본 색상 계열의 더 어두운 모든 색상과 같지 않습니다. 오류 역할은 #d54309입니다. 기존의 보조 빨간색 계열은 이 용도에서 사용 중단되었으므로, 새 유효성 검사 스타일에는 secondary 대신 오류 의미를 나타내는 토큰을 사용하세요.
기본 토큰 표와 의미 토큰 표는 버전이 명시된 CSS-library 릴리스를 기반으로 생성됩니다. 예시 화면은 오래된 USWDS 팔레트를 복사해 VA의 팔레트라고 표시하는 대신 실제 변수를 불러옵니다. 기본 구성 요소에는 해당 변수 외에 자체 컴파일 값이 포함될 수 있으므로, 업그레이드할 때는 두 계층을 모두 확인하세요.
VA의 Process List는 지하철 노선도라고도 합니다. 긴 프로세스를 설명하거나 사용자가 현재 어느 단계에 있는지 보여 줍니다. 가이드라인은 단계 수를 3~10개로 제한하고 페이지당 하나의 목록만 사용하도록 안내합니다. 각 항목에는 간결하고 동사로 시작하는 제목과 항상 표시되는 설명이 필요합니다. 내용이 비어 있는 제목 옆에 장식용 숫자만 붙이는 방식은 적절하지 않습니다.
기본 태그는 va-process-list와 va-process-list-item입니다. 항목에는 header와 level을 지정하고, active, pending, checkmark, status-text를 사용할 수 있습니다. 공개된 구성 요소 모듈에서는 checkmark가 active보다, 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>
프로세스 가이드라인은 아코디언 헤더와 프로세스 단계를 결합하지 않도록 안내합니다. 설명을 모두 숨기면 프로세스를 보여 주는 목적에 어긋납니다. 단계 안에 Details 구성 요소를 넣어 보충 정보를 제공하는 것은 허용됩니다. 예시에서는 기록 식별에 관한 설명을 계속 표시하고, 선택적 추가 설명은 va-details 안에 배치합니다.
구성 요소의 label 속성은 펼침 영역에 표시되는 질문이 됩니다. 짧은 질문은 숨겨진 내용이 관련 있는지 독자가 판단하는 데 도움이 되므로, More information보다 유용합니다. 이 예시에서는 기록을 식별하는 데 도움이 될 수 있는 정보를 설명하고, 이는 특정 VA 절차에 대한 안내가 아니라 예시용 콘텐츠임을 명시합니다.
미리 보기의 Example stage 선택기는 구성 요소 예시를 준비, 전송, 응답 검토 상태로 전환합니다. 실제 요청을 진행하거나 공식 처리 시간을 추정하지 않으며, 사용자가 버튼을 클릭했다는 이유만으로 완료 여부를 추론하지도 않습니다. 실제 서비스에서는 검증된 백엔드 상태를 이러한 시각적 상태에 매핑하고, 지연의 의미는 별도로 설명해야 합니다.
선택기를 변경하면 이전 단계는 Complete, 선택한 단계는 Active, 이후 단계는 Pending으로 설정됩니다. 상태가 변경되면 라이브 상태 문구로 예시 상태를 알립니다. 세 단계의 설명은 계속 표시되며 선택적 Details 상태도 유지됩니다. 재설정하면 첫 번째 예시 단계로 돌아가고 보충 설명 영역은 닫힙니다.
문서에 안내된 번들러 경로는 main.css를 가져오고 component-library 패키지에서 defineCustomElements를 호출합니다. 글꼴은 CSS-library에서 가져오며 별도로 제공됩니다. 아이콘 스프라이트를 사용하는 구성 요소에는 기본값이 /img/sprite.svg인 동일 출처 스프라이트 경로가 필요합니다. 이는 배포 후에야 알게 되는 선택적 세부 사항이 아니라 실제 통합 요구 사항입니다.
독립 실행형 예시에서는 web-components 24.14.0의 공식 브라우저 ESM 진입점과 component-library 56.14.0에 선언된 종속성, 그리고 Process List, Process List Item, Details용 지연 로드 모듈을 사용합니다. 애플리케이션 스크립트는 예시 상태만 선택합니다. 브라우저 런타임이 Details 컨트롤을 포함한 기본 사용자 지정 요소 동작을 제공합니다.
일치하는 토큰 CSS과 브라우저 구성 요소 진입점을 불러오고 상대 모듈 위치를 유지하세요.
예시 상태 속성을 지정하기 전에 va-process-list-item의 정의가 완료될 때까지 기다리세요.
설명 내용을 숨기지 않은 상태에서 모든 시나리오 상태, Details 키보드 컨트롤, 좁은 화면 너비를 테스트하세요.
실제 Web Component 속성과 단계 내부에서 사용할 수 있는 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>
전체 문서에 레이아웃, 컨트롤 및 초기화가 포함되어 있습니다. 링크된 예시 아카이브의 압축을 풀면 정확한 상대 경로의 벤더 에셋을 얻을 수 있습니다. 그런 다음 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>
Sources에서 완전한 예시를 다운로드하세요. README에 정확한 로컬 실행 명령이 안내되어 있습니다.
벤더 경로는 이 문서에 대한 상대 경로로 유지하세요. 아카이브에는 이 미리보기에 사용된 에셋이 모두 포함되어 있습니다.
04
VA 디자인 시스템 에이전트 설정
구현 시작점
검증된 패키지 버전으로 번들러를 초기화하는 방법을 문서화했습니다. 독립 실행형 브라우저 예제에서는 React 빌드 대신 이에 해당하는 기본 웹 구성 요소 ESM 배포판을 사용합니다. Sources의 완전한 작동 예제 ZIP에는 정확한 미리보기 종속 항목과 전체 문서도 포함되어 있습니다. 압축을 풀고 해당 디렉터리에서 python3 -m http.server 8080을 실행한 다음 http://localhost:8080/va.html을 여세요. 모듈 기반 예제를 file://로 열지 마세요.
자바스크립트
// 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.
프로젝트를 위한 프롬프트
에이전트 프롬프트
va-process-list 하나에 va-process-list-item 요소를 3~10개 포함해 VA 서비스 절차를 설명하세요. 동사로 시작하는 제목, h2 다음의 level=3, 표시되는 설명을 사용하고, 각 항목에는 active/pending/checkmark 상태 하나와 명시적인 status-text를 지정하세요. va-details는 단계 전체를 숨기는 용도가 아니라 단계 내 보충 설명에만 사용하세요. 최신 VADS CSS 토큰 파일을 가져오고 기본 구성 요소를 등록하세요. 본문 글자 크기 17px, Bitter/Source Sans 서체 역할, 시맨틱 간격, 320/480/640/880/1024/1201/1400px 경계를 유지하세요. 상호작용이 있는 예시는 각 단계가 예시임을 명시하고, 제출된 VA 신청인 것처럼 보이게 하지 마세요.
05
VA 디자인 시스템 출처 및 범위
가상의 기록 요청 단계를 보여 주는 기술 구성 요소 데모입니다. 실제 VA 요청, 사건 상태, 복지 혜택 결정 또는 기관의 보증을 나타내지 않습니다.
