# VA 设计系统

## VA 设计系统 界面预览

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

## VA 设计系统 设计参考

已发布的 css-library 0.36.1 变量，以及 component-library 56.14.0 依赖项 web-components 24.14.0。字体明确使用本地备用字体。52rem 示例容器宽度为应用层选择。

### 语义化字体排印

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --vads-font-family-heading | Bitter, Georgia, Cambria, Times New Roman, Times, serif | 标题字体系列；预览使用 Georgia。 |
| --vads-font-family-sans | Source Sans Pro Web / Source Sans Pro, system sans fallbacks | 正文和界面字体系列；预览使用 Arial。 |
| --vads-font-size-body-default | 1.06rem (about 17px) | 优先使用语义角色，而非 source-sans-normalized。 |
| --vads-font-size-heading-level-1 / 2 / 3 | 2.5 / 2 / 1.25rem | 在根字号为 16px 时，分别为 40 / 32 / 20px。 |
| --vads-font-size-heading-level-4 / 5 / 6 | 1.063 / .938 / .938rem | 约为 17 / 15 / 15px。 |
| --vads-font-line-height-default / heading / body-lead | 1.5 / 1.2 / 1.75 | 与文本角色保持一致。 |
### 间距

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --vads-spacing-inset-s / m / l | 1 / 1.5 / 2rem | 16 / 24 / 32px。 |
| --vads-spacing-vertical-stack-default | 1rem / 16px | 常规垂直堆叠间距。 |
| --vads-forms-spacing-vertical-stack-default | 2rem / 32px | 表单字段堆叠间距。 |
| --vads-spacing-0p5 / 1 / 1p5 / 2 / 2p5 / 3 | 4 / 8 / 12 / 16 / 20 / 24px | 标准根字号下的基础尺度。 |
| --vads-spacing-4 / 5 / 6 / 7 / 8 | 32 / 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-lg | 320 / 480px | 小屏参考断点。 |
| --vads-breakpoint-tablet / tablet-lg | 640 / 880px | 中间尺寸布局。 |
| --vads-breakpoint-desktop / desktop-lg | 1024 / 1201px | 桌面端断点。 |
| --vads-breakpoint-widescreen | 1400px | 宽屏布局参考。 |
## VA 设计系统 完整指南

实用指南，介绍如何为真实界面选择、应用和评审此系统。

完整指导、实现起点和源代码链接。

## VA 设计系统 面向退伍军人的服务系统

### 基础样式与组件属于不同的软件包

> VA 的系统整合了服务模式、内容指南、设计令牌、CSS 工具和 Web Components。文档中的安装方式使用 CSS-library 包提供全局基础样式，并使用组件库包提供交互元素。本参考搭配使用 component-library 56.14.0 和 css-library 0.36.1；这两个包的版本号各自独立。

示例讲解的是虚构的档案申请流程。它展示如何通过流程列表说明步骤进展，但不声称有人已提交申请或符合福利资格。示例中没有 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 的断点并非通用框架刻度

令牌集定义了以下断点：mobile 320px、mobile-lg 480px、tablet 640px、tablet-lg 880px、desktop 1024px、desktop-lg 1201px 和 widescreen 1400px。不同寻常的 1201px 阈值对于匹配现有模板很重要。断点变量用于记录这些值；CSS 自定义属性不能直接替代原生媒体查询条件中的值。请使用对应的构建时值，或使用根据已验证令牌得出的字面值。

阅读配套规范

## VA 设计系统 流程列表结构

### 三个至十个有意义的步骤

VA 的流程列表也被称为地铁图，用于说明较长的流程，或显示某人在流程中的进度。指南建议列出三个至十个步骤，并且每页仅使用一个流程列表。每项都应包含简洁、以动词开头的标题和可见的说明内容；它不是在空洞标题旁装饰性地放一个数字。

原生标签为 va-process-list 和 va-process-list-item。条目接受 header 和 level 属性，以及 active、pending、checkmark 和 status-text 属性。已发布的组件模块按 checkmark、active、pending 的顺序确定状态优先级。设置其中一个布尔状态时，请清除其他状态，避免组合矛盾。状态文本应与状态样式相辅相成，让用户无需辨别颜色也能理解当前阶段。

```
<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 展开面板。

```
<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 提供服务。

```
<!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 路径相对于本文档；该归档包含此预览所使用的全部资源。

## VA 设计系统 AI Agent 设置

### 实现起点

采用文档所述的打包器初始化方式，并使用已验证的包版本。独立浏览器示例使用对应的原生 web-components ESM 分发版本，而非 React 构建版本。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/component-library@56.14.0 \
//   @department-of-veterans-affairs/css-library@0.36.1
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 服务流程说明，其中包含一个 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 申请。
```

## VA 设计系统 来源与范围

虚构记录申请阶段的技术组件演示。此处不代表真实的 VA 申请、案件状态、福利决定或机构背书。

- VA Design System 官方基础规范、内容、组件与治理指南。

- VA 模式 适用于申请任务、预填、签名与恢复的模式。

- VA 组件 组件规范、决策与无障碍资料。

- 下载完整可运行示例 包含完整 HTML、本地 CSS/JavaScript 依赖、随附许可证以及确切启动说明的 ZIP 包。无需构建步骤。

## VA 设计系统 相关资源

### W3C 设计系统

运用流式字体、语义化颜色角色和原生折叠内容，打造适应力强的阅读界面，即使没有 JavaScript，内容依然清晰易读。

### Codex

运用 Codex 的真实 SearchInput 结构、操作层级和适于阅读的令牌。在本地文章索引中搜索、查看搜索结果，并返回原来的阅读位置。

### Agriculture 设计系统

借助 AgDS 具体的间距、响应式属性与 TaskList 状态模型，构建更长的服务流程事务。试用一个准备流程：只有当所有前置条件都完成时，复核步骤才会解锁。


- [实现参考](https://design.va.gov/components/process-list)
- [来源](https://design.va.gov/foundation/design-tokens/typography)
- [来源](https://design.va.gov/foundation/design-tokens/spacing)
- [来源](https://design.va.gov/foundation/design-tokens/color)
- [来源](https://design.va.gov/foundation/design-tokens/breakpoints)
- [阅读配套规范](https://design.va.gov/about/developers/install)
- [阅读配套规范](https://design.va.gov/foundation/design-tokens/typography)
- [阅读配套规范](https://design.va.gov/foundation/design-tokens/spacing)
- [阅读配套规范](https://design.va.gov/foundation/design-tokens/color)
- [阅读配套规范](https://design.va.gov/foundation/design-tokens/breakpoints)
- [代码参考](https://design.va.gov/components/process-list)
- [阅读配套规范](https://design.va.gov/components/process-list)
- [VA Design System 官方基础规范、内容、组件与治理指南。](https://design.va.gov/)
- [VA 模式 适用于申请任务、预填、签名与恢复的模式。](https://design.va.gov/patterns/)
- [VA 组件 组件规范、决策与无障碍资料。](https://design.va.gov/components/)