政府与公共服务 · 新资源

VA 设计系统.

运用 VA 的语义令牌和原生 Process List,打造清晰的服务流程:展示步骤说明和含义明确的状态标签,并提供补充详情,同时保持主要路径清晰易读。

OpenDesign 指南8 个章节21 条参考条目原始应用指南
01

VA 设计系统 界面预览

查看三个示例流程状态,并打开补充说明,同时不隐藏步骤摘要。

了解请求流程打开完整示例
原生 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正文和界面字体系列;预览使用 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 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;一级标题为 40px,二级标题为 32px,三级标题为 20px,四级标题约为 17px。

请使用 --vads-font-size-body-default,而不要使用较旧的 source-sans-normalized 名称。语义化令牌说明其用途,而较旧的规范化名称则暴露了字体实现细节。预览中正文明确使用 Arial,标题使用 Georgia。原生流程组件 CSS 仍负责其内部结构和字号;此处的后备字体并不声称能精确复现 Source Sans 和 Bitter 的字体度量。

阅读配套规范

行高应与文本角色相匹配

默认段落行高为 1.5,标题行高为 1.2。引导性正文的行高角色为 1.75;衬线字体行高令牌为 1.9,适用于衬线正文,而非所有衬线标题。将 1.9 用于紧凑的流程标题,会混淆两个不同的文本角色。本示例中的流程项使用三级标题,位于页面的二级章节标题之下。

阅读配套规范

VA 设计系统 语义化间距与布局

区分常规堆叠间距与表单间距

通用 vertical-stack-default 为 1rem/16px,表单的 vertical-stack-default 为 2rem/32px。这种差异很实用:两个简短说明项所需的节奏,与包含标签、提示、控件和错误信息的独立问题不同。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 设计系统 流程列表结构

三个至十个有意义的步骤

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 支持可见的步骤说明

不要把每个步骤都变成手风琴

流程指南不建议将手风琴标题与流程步骤合并。隐藏所有说明会违背展示流程的初衷。不过,指南允许在步骤内使用 Details 组件提供补充信息。示例中,记录识别说明始终可见,可选的补充说明则放在 va-details 中。

组件的 label 属性会成为展开面板中可见的问题。与“更多信息”相比,简短的问题更有用,因为它能让读者判断隐藏内容是否与自己相关。本例中的详细说明介绍了哪些信息可能有助于识别记录,并明确指出这些内容仅为示例,并非针对特定 VA 流程的操作说明。

  • 保持每个阶段的摘要始终可见,包括标记为 Pending 的阶段。
  • 仅在阶段内使用 Details 展示次要说明。
  • 将下一步实际服务操作放在流程标题之外,不要把标题变成控件。

阅读配套规范

VA 设计系统 状态演示与真实性

使用场景选择器,不要伪造进度

预览中的“示例阶段”选择器会在准备、发送和回复审核这几个组件示例之间切换。它不会推进真实请求、估算官方处理时间,也不会根据用户点击按钮推断请求已完成。在线服务应将经过验证的后端状态映射到这些视觉状态,并单独说明任何延迟的含义。

更改选择器后,之前的阶段会设为 Complete,所选阶段设为 Active,后续阶段设为 Pending。实时状态提示会播报示例状态变化。所有三个阶段的说明都保持可见,并保留可选的 Details 展开状态。重置后会回到第一个示例阶段,并关闭补充说明。

阅读配套规范

VA 设计系统 加载原生 Web Components

仅注册一次,并保留依赖项

文档所述的打包器接入方式会导入 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 控件。

  1. 加载匹配的令牌 CSS 和浏览器组件入口,并保留模块的相对位置。
  2. 在设置示例状态属性之前,等待 va-process-list-item 定义完成。
  3. 测试所有场景状态、Details 键盘控件和窄屏显示,确保说明内容不会被隐藏。

阅读配套规范

VA 设计系统组件示例

原生的三阶段说明

在步骤内使用真实的 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。
  • 不要用手风琴触发器替代步骤标题。
  • 每个条目只能设置一个状态标记。

完整的独立示例

完整文档包含其布局、控件与初始化。解压所链接的示例归档,即可获得完全一致的相对 vendor 资源,然后通过 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 给出了确切的本地启动命令。
  • 保持 vendor 路径相对于本文档;该归档包含此预览所使用的全部资源。
04

VA 设计系统 AI Agent 设置

实现起点

采用文档所述的打包器初始化方式,并使用已验证的包版本。独立浏览器示例使用对应的原生 web-components ESM 分发版本,而非 React 构建版本。Sources 中提供的完整可运行示例 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.

适用于你项目的提示词

Agent 提示词
创建 VA 服务流程说明,其中包含一个 va-process-list,并在其中放置三个至十个 va-process-list-item 元素。使用以动词开头的标题,在 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 申请、案件状态、福利决定或机构背书。