行政・公共サービス · 新しいリソース

VA デザインシステム.

VAのセマンティックトークンとネイティブのProcess Listを活用して、わかりやすいサービス利用フローを構築しましょう。各ステップの説明を見やすくし、意味の伝わるステータスラベルを付け、補足情報を整理してメインの流れを読みやすく保ちます。

OpenDesign ガイド8章参考項目21件オリジナルアプリケーションガイド
01

VA デザインシステム インターフェースプレビュー

例示用の3つのプロセス状態を確認し、ステップの概要を隠さずに補足説明を開けます。

申請の流れを理解する完全な例を開く
ネイティブのVA web-components 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に依存するweb-components 24.14.0を使用しています。フォントにはローカルの代替フォントを明示的に指定しています。52remのサンプル用シェルはアプリケーション側の選択です。

セマンティックなタイポグラフィ

ソース
名前 / ルール値 / 設定用途
--vads-font-family-headingBitter, Georgia, Cambria, Times New Roman, Times, serif見出し用フォント。プレビューではGeorgiaを使用。
--vads-font-family-sansSource Sans Pro Web / Source Sans Pro, system sans fallbacks本文とUI用フォント。プレビューではArialを使用。
--vads-font-size-body-default1.06rem (about 17px)source-sans-normalizedより、セマンティックな役割を示すトークンを優先。
--vads-font-size-heading-level-1 / 2 / 32.5 / 2 / 1.25remルートサイズ16pxの場合、40 / 32 / 20px。
--vads-font-size-heading-level-4 / 5 / 61.063 / .938 / .938rem約17 / 15 / 15px。
--vads-font-line-height-default / heading / body-lead1.5 / 1.2 / 1.75テキストの役割に合わせる。
名前 / ルール値 / 設定用途
--vads-spacing-inset-s / m / l1 / 1.5 / 2rem16 / 24 / 32px。
--vads-spacing-vertical-stack-default1rem / 16px一般的な縦方向の積み重ね。
--vads-forms-spacing-vertical-stack-default2rem / 32pxフォーム項目の積み重ね。
--vads-spacing-0p5 / 1 / 1p5 / 2 / 2p5 / 34 / 8 / 12 / 16 / 20 / 24px標準のルートサイズでのプリミティブスケール。
--vads-spacing-4 / 5 / 6 / 7 / 832 / 40 / 48 / 56 / 64pxより大きなプリミティブ値。

セマンティックカラー

ソース
名前 / ルール値 / 設定用途
--vads-color-text#1b1b1b 標準のテキストには、推奨されるデフォルトの役割を使用。
--vads-color-link / link-active#005ea2 / #0b4778デフォルトとアクティブ状態のリンクの役割。
--vads-color-primary-darker#162e51 強調度の高いプライマリーサーフェスの参照値。
--vads-color-base-lighter / base-lightest#dfe1e2 / #f0f0f0ニュートラルな区切り線と背景。
--vads-color-error#d54309 非推奨のセカンダリーレッドではなく、エラーのセマンティクスを使用。
--vads-color-success-darker#216e1f 濃い成功色の参照値。状態は色だけでなく言葉でも示す必要があります。

レスポンシブの境界値

ソース
名前 / ルール値 / 設定用途
--vads-breakpoint-mobile / mobile-lg320 / 480px小画面のブレークポイント。
--vads-breakpoint-tablet / tablet-lg640 / 880px中間サイズのレイアウト。
--vads-breakpoint-desktop / desktop-lg1024 / 1201pxデスクトップのブレークポイント。
--vads-breakpoint-widescreen1400pxワイド画面のレイアウト基準。
03

VA デザインシステム 完全ガイド

実際のインターフェースで、このデザインシステムを選び、適用し、レビューするための実践ガイドです。

DESIGN-va.md

詳しいガイダンス、実装の出発点、ソースへのリンクをまとめています。

ガイドをダウンロード

VA デザインシステム 退役軍人向けサービスのデザインシステム

基盤とコンポーネントは別々のパッケージ

VAのデザインシステムは、サービスパターン、コンテンツガイダンス、トークン、CSSユーティリティ、Web Componentsで構成されています。ドキュメントに記載されたインストール方法では、全体の基盤にCSS-libraryパッケージを、インタラクティブな要素にcomponent-libraryパッケージを使用します。このリファレンスではcomponent-library 56.14.0とcss-library 0.36.1を組み合わせています。これらのパッケージのバージョン番号はそれぞれ独立しています。

この OpenDesign ガイドから

この例は、記録の開示請求について架空の説明を示すものです。請求が提出された、あるいは誰かが給付の対象になると主張することなく、プロセスリストで進行状況を伝える方法を説明しています。VAのロゴ、政府機関の識別バナー、個人記録、実際の案件ステータスは表示していません。実際のサービスで使用する文面は、担当する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つの役割を混同することになります。このサンプルのプロセス項目には、ページのレベル2のセクション見出しの下にレベル3を使用しています。

関連する仕様を確認する

VA デザインシステム セマンティックな余白とレイアウト

通常の縦方向の間隔とフォームの間隔を使い分ける

general vertical-stack-defaultは1rem / 16px、forms vertical-stack-defaultは2rem / 32pxです。この違いは有用です。短い説明項目2つの間隔と、ラベル、ヒント、入力コントロール、エラーを含む個別の質問の間隔には、異なるリズムが必要だからです。インセットs、m、lはそれぞれ16、24、32pxに対応します。

プリミティブな余白のファミリーには4、8、12、16、20、24pxと、それより大きな8px刻みの値に加えて、1pxと2pxの特殊な値があります。レイアウトの目的に合う場合は、セマンティックな余白名を優先してください。この例の外側のシェル幅52remはアプリケーション側の選択ですが、24pxのインセットと32pxのセクション間隔には公開済みのスケール値を使用しています。このシェル幅をすべてのVAページテンプレートに適用するものではありません。

関連する仕様を確認する

VA デザインシステム カラーとレスポンシブ対応のトークン

歴史的な別名ではなく、役割に対応するトークンを使用

現在のテキストトークンは--vads-color-text(#1b1b1b)です。--vads-color-linkは#005ea2、リンクのアクティブ状態は#0b4778です。これらは、プライマリーカラー系のより濃い色すべてと同じではありません。エラーの役割には#d54309を使用します。従来のセカンダリーレッド系はこの用途では非推奨のため、新しい入力検証の表示にはセカンダリーではなく、エラーのセマンティクスを参照してください。

プリミティブとセマンティックの各テーブルは、指定されたCSS-libraryのリリースから生成されます。このサンプルでは、古いUSWDSのパレットをコピーしてVAのものとして示すのではなく、実際の変数を読み込んでいます。ネイティブコンポーネントには、これらの変数に加えて、コンパイル済みの値が含まれる場合があります。アップグレード時は両方のレイヤーを確認してください。

関連する仕様を確認する

VAのブレークポイントは汎用フレームワークのスケールとは異なる

関連する仕様を確認する

VA デザインシステム プロセスリストの構造

意味のあるステップを3〜10個

VAのProcess Listは、地下鉄路線図とも表現されます。長いプロセスの全体像を示したり、現在どの段階にいるかを伝えたりするためのものです。ガイダンスでは、ステップ数を3〜10個とし、1ページにつき1つだけ配置するよう求めています。各項目には、動詞で始まる簡潔な見出しと、常に見える説明文が必要です。内容のないタイトルの横に数字を飾りとして置くものではありません。

ネイティブタグはva-process-listとva-process-list-itemです。各項目にはheaderとlevelのほか、active、pending、checkmark、status-textを指定できます。公開されているコンポーネントモジュールでは、checkmark、active、pendingの順に優先されます。状態の組み合わせに矛盾が生じないよう、いずれか1つを設定する際はほかのブール値を解除してください。状態のスタイルにstatus-textを明示的に添えることで、色を見なくてもステージの意味が伝わります。

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でステップを見える状態に保つ

すべてのステップをアコーディオンにしない

プロセスに関するガイダンスでは、アコーディオンの見出しとプロセスのステップを組み合わせないよう求めています。説明をすべて隠すと、プロセスを示す目的が損なわれます。一方、補足情報を示すために、ステップ内でDetailsコンポーネントを使うことはできます。この例では、記録の特定方法に関する説明を常に表示し、補足情報をva-details内に配置しています。

コンポーネントのlabel属性は、開閉領域に表示する質問になります。「詳細はこちら」のような表現より、短い質問のほうが、隠れた内容が自分に関係するかどうかを読者が判断しやすくなります。この例では、記録の特定に役立つ可能性のある情報を説明しています。なお、内容は例示であり、特定のVA手続きについての指示ではありません。

  • Pendingのステージも含め、各ステージの説明を常に表示します。
  • ステージ内の補足説明に限り、Detailsの開閉領域を使います。
  • 次に行う実際のサービス上の操作は、見出しを操作ボタンにせず、プロセスの見出しの外に配置します。

関連する仕様を確認する

VA デザインシステム ステータスのデモと正確性

架空の進捗ではなく、シナリオ選択を使う

プレビューの「Example stage」セレクターを操作すると、コンポーネントの表示例が「準備」「送信」「回答の確認」に切り替わります。実際の請求を進めたり、公式の処理時間を推定したり、ボタンのクリックから完了を推測したりするものではありません。実際のサービスでは、検証済みのバックエンド状態をこれらの表示状態に対応付け、遅延の意味については別途説明してください。

セレクターを変更すると、選択したステージより前はComplete、選択したステージはActive、後続のステージはPendingになります。ライブステータスの文章で、例示の状態が変わったことを伝えます。3つのステージの説明はすべて表示したままにし、任意のDetailsの状態も維持します。リセットすると、最初の例示ステージに戻り、補足情報の開閉領域が閉じます。

関連する仕様を確認する

VA デザインシステム ネイティブWeb Componentsの読み込み

一度だけ登録し、依存関係を維持する

ドキュメントに記載されたバンドラーの設定では、main.cssをインポートし、component-libraryパッケージからdefineCustomElementsを呼び出します。フォントはCSS-libraryから取得し、別途配信します。アイコンスプライトを使うコンポーネントには、同一オリジンのスプライトパスが必要です。既定値は/img/sprite.svgです。これらはデプロイ後に初めて気づくような任意の調整ではなく、実際に必要な統合要件です。

スタンドアロンの例では、component-library 56.14.0が依存関係として宣言しているweb-components 24.14.0の公式ブラウザー向けESMエントリと、Process List、Process List Item、Detailsそれぞれの遅延読み込みモジュールを使用します。アプリケーションのスクリプトは、例示用の状態を選択するだけです。Detailsの操作を含むネイティブカスタム要素の動作は、ブラウザーのランタイムが提供します。

  1. 対応するトークンCSSとブラウザー向けコンポーネントのエントリを読み込み、相対モジュールの配置を維持してください。
  2. 例示用の状態を設定する前に、va-process-list-itemの定義完了を待ってください。
  3. 説明文を隠さず、すべてのシナリオ状態、Detailsのキーボード操作、および狭い画面幅での表示をテストしてください。

関連する仕様を確認する

VA デザインシステムのコンポーネント例

ネイティブな3段階の説明

実際の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>

コードリファレンス

  • ステップ数は3〜10個とし、ページ内のProcess Listは1つだけにします。
  • ステップの見出しをアコーディオンの開閉ボタンに置き換えないでください。
  • 各項目に設定するステータスフラグは1つだけにしてください。

単体で動作するサンプル一式

レイアウト、操作要素、初期化処理を含むドキュメント全体です。リンク先のサンプルアーカイブを展開すると、このプレビューで使用する正確な相対パスのベンダーアセットが得られます。その後、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エージェントの設定

実装の出発点

検証済みのパッケージバージョンを使用した、ドキュメント記載のバンドラー初期化方法です。スタンドアロンのブラウザー例では、Reactビルドではなく、対応するネイティブのweb-components ESM配布物を使用します。「Sources」にある動作確認済みの完全なサンプルZIPには、プレビューに必要な依存関係とドキュメント一式も含まれています。ZIPを展開し、そのディレクトリで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を1つ作成し、その中にva-process-list-itemを3〜10個配置してください。動詞で始まるheader、h2の下に置くlevel=3、常に見える説明文、および各項目につき1つのactive/pending/checkmark状態を使い、status-textも明示してください。va-detailsはステップ内の補足文に限って使い、ステップ全体を隠さないでください。最新のVADS CSSトークンファイルをインポートし、ネイティブコンポーネントを登録してください。本文の17px、Bitter/Source Sansのフォントの役割、意味に基づくスペーシング、320/480/640/880/1024/1201/1400pxのブレークポイントを維持してください。インタラクティブなデモでは、各ステージが例示であることを明示し、VAへの申請が送信済みであるかのように見せないでください。
05

VA デザインシステム 参考資料と対象範囲

架空の記録請求ステージを使った技術的なコンポーネントのデモです。実際のVAへの請求、ケースの状況、給付の決定、または機関による推奨を示すものではありません。