# USWDS 设计系统

## USWDS 设计系统界面预览

搜索并筛选虚构记录，在无结果时恢复，并展开原生要求面板。

## USWDS 设计系统设计参考

USWDS 3.14.0 原生组件分发包。默认令牌取自官方文档；预览中的字体替换为明确指定的本地选择。

### 间距单位

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| 0.5 / 05 | 4px | 半单位间距与实用类 |
| 1 | 8px | 基础间距单位 |
| 1.5 / 105 | 12px | 中间间距 |
| 2 | 16px | 紧凑的内部边距 |
| 3 | 24px | 相关内容间距 |
| 4 | 32px | 章节间距 |
| 5 | 40px | 较大的间隔 |
| 6 | 48px | 大间距 |
| tablet | 640px | 命名宽度令牌 |
| desktop | 1024px | 命名宽度令牌 |
### 默认字体映射

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| sans | source-sans-pro | 基于字体类型的系列令牌 |
| serif | merriweather | 基于字体类型的系列令牌 |
| body / ui | sans | 基于角色的映射 |
| heading | serif | 基于角色的映射 |
| code | mono → roboto-mono | 代码角色映射 |
### 默认主题颜色

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| primary | blue-60v / #005ea2 | 主色别名 |
| primary-lighter | blue-10 / #d9e8f6 | 辅助主色调 |
| primary-dark | blue-warm-70v / #1a4480 | 较深的主色别名 |
| ink | gray-90 / #1b1b1b | 正文颜色别名 |
### 组件契约

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| aria-controls | Panel ID | 将每个手风琴按钮与其内容关联。 |
| aria-expanded | true / false | 原生 JS 负责维护展开状态。 |
| data-allow-multiple | Accordion root attribute | 允许多个面板分别展开。 |
| usa-accordion--bordered | Root modifier | 提供带边框的变体。 |
## USWDS 设计系统完整指南

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

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

## USWDS 设计系统：可配置的 Foundation

### 默认令牌是起始配置

> USWDS 将系统令牌、项目主题设置、实用类和组件分开管理。下方参考内容记录了当前文档中的默认主题选项。联邦项目可以配置不同的字体角色或颜色别名，而不必替换每个组件。

此预览是独立的研究机会对比界面，使用 3.14.0 CSS 和手风琴式 JavaScript。其中省略了政府横幅和身份标识。项目名称和阶段均为虚构，筛选完全在浏览器中进行。

阅读配套规范

## USWDS 设计系统：间距与主题令牌

### 看单位，不要只看数字

一个 USWDS 间距单位为 8px：units(2) 表示 16px，units(3) 表示 24px。比例中还包含半单位令牌，可用于较小的间距；实用类名称中的 05 表示半个单位。margin-2 实用类并不表示 2px 的外边距。

比例中还包含 tablet 和 desktop 等命名宽度。这些名称是可重复使用的令牌，并不意味着每种宽度都必须重新设计每个页面。此对比界面使用 grid-container 包裹内容，并为表格提供一个可聚焦的滚动区域。

```
@use "uswds-core" as *;
.opportunity-meta {
  padding: units(2);
  margin-bottom: units(3);
}
```

代码参考

阅读配套规范

## USWDS 设计系统：字体类型与角色

### 角色可以更改，而无需重命名组件

默认的无衬线令牌映射到 Source Sans Pro，衬线令牌映射到 Merriweather。正文和 UI 角色映射到无衬线字体，标题映射到衬线字体。family("body") 函数会解析这条映射链。记录项目文档时，应区分语义角色和最终字体族。

本地预览明确为正文使用 Helvetica/Arial，为标题使用 Georgia，因此无需下载字体。这是研究用覆盖设置，并非标准的 USWDS 字体标识。生产构建应通过 uswds-core 设置配置这些角色，或复制随包分发的字体资源。

```
@use "uswds-core" with (
  $theme-font-type-sans: "helvetica",
  $theme-font-type-serif: "georgia",
  $theme-font-role-body: "sans",
  $theme-font-role-heading: "serif"
);
```

代码参考

阅读配套规范

## USWDS 设计系统主题颜色别名

### 让别名始终对应其用途

默认的 primary 别名解析为 blue-60v，即 #005ea2。primary-dark 解析为 blue-warm-70v，即 #1a4480；ink 解析为 gray-90，即 #1b1b1b。这些是主题值，并不意味着每个 USWDS 网站都必须采用相同的品牌颜色。

用于操作或标题样式时，选择语义别名；只有在设计决策确实针对系统颜色时，才使用系统颜色令牌。在设置中替换 primary 别名，比在编译后的 CSS 中替换所有匹配的十六进制字符串更可控。

阅读配套规范

## USWDS 设计系统可比较的机会列表

### 保留表格语义

此示例使用了表格标题、带有 scope="col" 的列标题，以及带有 scope="row" 的机会名称。这是一个表格，因为读者需要比较各记录中相同的主题和阶段字段。即使区域可滚动，这些关联关系仍然有效。

可滚动容器设置了 tabindex="0"，让键盘用户可以进入其中。它将宽数据限制在该区域内，避免整个文档被撑宽。预览中使用的是普通文本单元格；如果缺少项目数据，应明确展示内容状态，而不是编造数字。

阅读配套规范

### 排序是单独的增强功能

USWDS 通过 data-sortable 支持可排序表头。可排序表格还需要一个带有 aria-live="polite" 的 usa-table__announcement-region。对于数字显示，可能需要设置 data-sort-value，让格式化后的金额按数值而非字母顺序排序。当前的对比示例未启用排序，因为按主题筛选三行数据才是此示例的预期用途。

阅读配套规范

## USWDS 设计系统：以折叠面板展示要求

### 关联按钮和面板 ID

每个 usa-accordion__button 的 aria-controls 都指向对应的 usa-accordion__content。原生 JavaScript 会更新 aria-expanded 和可见性。带边框修饰符会改变容器样式；data-allow-multiple 则允许同时展开多个部分。

按钮置于标题内，使内容大纲仍然清晰易懂。判断某个项目是否符合条件所需的要求，应在折叠面板上方保持可见。这里的面板用于补充准备说明，并解释虚构数据集。

- 标题描述面板主题。

- 按钮包含展开状态和目标 ID。

- 面板在可见性改变时保留相同的 ID。

阅读配套规范

## USWDS 设计系统：安装完整资源目录树

### 保留编译后的 CSS 所用路径

安装 @uswds/uswds@3.14.0，并复制其 dist 目录；不要将 css、js、img 和 fonts 扁平化到同一个文件夹中。样式表使用图标和字体的相对路径。否则，页面可能看起来部分正常，却缺少折叠符号或字体。

在 head 中加载 uswds-init.min.js，接着加载样式表，并在 body 标记之后加载 uswds.min.js。打包后的库会增强折叠面板。下方的搜索输入框和主题筛选器使用自定义应用逻辑，不会调用远程搜索服务。

阅读配套规范

## USWDS 设计系统：筛选与恢复

### 搜索必须明确呈现结果

原生标签、输入框、选择框和按钮样式提供了控件；应用会将搜索词和所选主题与三条虚构记录进行比对。结果数量通过礼貌播报的实时区域呈现。无匹配结果时会显示说明和重置操作，同时保留已输入的搜索词。

此示例有意区分查找机会与提交申请。展开准备内容不会创建草稿，也不会将要求标记为已完成。实际的资助申请还需要相应的项目政策、身份验证和持久化事务状态。

1. 筛选到环境主题，并查看剩余的机会。

2. 搜索一个无法匹配的词组，然后使用“清除筛选条件”。

3. 同时展开两个准备面板，并确认它们各自的展开状态互不影响。

阅读配套规范

## USWDS 设计系统组件示例

### 补充准备信息折叠面板

原生 USWDS 折叠面板，按钮与面板之间具有明确的关联关系。

```
<div class="usa-accordion usa-accordion--bordered" data-allow-multiple>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button"
      aria-expanded="false" aria-controls="preparation">Before you prepare a draft</button>
  </h3>
  <div id="preparation" class="usa-accordion__content usa-prose" hidden>
    <p>This fictional opportunity asks for a project summary and a named contact.</p>
  </div>
</div>
```

代码参考

### 机会对比表

说明文字以及行、列标题保留比较关系。

```
<div class="usa-table-container--scrollable" tabindex="0">
  <table class="usa-table usa-table--borderless">
    <caption>Illustrative research opportunities</caption>
    <thead><tr><th scope="col">Opportunity</th><th scope="col">Topic</th><th scope="col">Stage</th></tr></thead>
    <tbody><tr><th scope="row">Community water study</th><td>Environment</td><td>Example draft</td></tr></tbody>
  </table>
</div>
```

代码参考

### 完整的独立示例

完整文档包含其布局、控件与初始化。解压所链接的示例归档，即可获得完全一致的相对 vendor 资源，然后通过 HTTP 提供服务。

```
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Research opportunities — OpenDesign study</title><script src="vendor/uswds-3.14.0/uswds-init.min.js"></script><link rel="stylesheet" href="vendor/uswds-3.14.0/css/uswds.min.css"><style>body,body *,body *:before,body *:after{font-family:Helvetica,Arial,sans-serif!important}h1,h2{font-family:Georgia,serif!important}body{color:#1b1b1b;margin:0}[hidden]{display:none!important}.study-head{background:#d9e8f6;padding:16px 0;border-bottom:4px solid #005ea2}.study-head p{margin:0}.study-form{display:flex;gap:24px;align-items:end;flex-wrap:wrap}.study-form>div{flex:1;min-width:200px}.study-form .usa-input,.study-form .usa-select{max-width:none}.usa-table{width:100%}.study-main{padding-top:32px;padding-bottom:48px}.usa-table th{min-width:120px}#count{margin-top:24px}.study-note{border-top:1px solid #a9aeb1;margin-top:32px;padding-top:16px;line-height:1.5}</style></head><body><header class="study-head"><div class="grid-container"><p><strong>OpenDesign · USWDS component study</strong><br>Fictional research records. No application is submitted.</p></div></header><main class="grid-container study-main"><h1>Research opportunities</h1><p class="usa-intro">Compare topics and read the preparation notes.</p><form class="study-form" id="filters"><div><label class="usa-label" for="query">Search opportunity names</label><input class="usa-input" id="query" type="search"></div><div><label class="usa-label" for="topic">Topic</label><select class="usa-select" id="topic"><option value="">All topics</option><option>Environment</option><option>Transport</option><option>Education</option></select></div><button type="submit" class="usa-button">Apply filters</button><button type="button" class="usa-button usa-button--outline" id="clear">Clear filters</button></form><p id="count" aria-live="polite">3 opportunities</p><div class="usa-table-container--scrollable" tabindex="0"><table class="usa-table usa-table--borderless"><caption>Illustrative research opportunities</caption><thead><tr><th scope="col">Opportunity</th><th scope="col">Topic</th><th scope="col">Stage</th></tr></thead><tbody><tr data-topic="Environment"><th scope="row">Community water study</th><td>Environment</td><td>Example draft</td></tr><tr data-topic="Transport"><th scope="row">Accessible transport research</th><td>Transport</td><td>Example review</td></tr><tr data-topic="Education"><th scope="row">Local skills survey</th><td>Education</td><td>Example draft</td></tr></tbody></table></div><p id="empty" hidden>No matching opportunities. Broaden the topic or clear the filters.</p><h2>Preparation notes</h2><div class="usa-accordion usa-accordion--bordered" data-allow-multiple>
  <h3 class="usa-accordion__heading">
    <button type="button" class="usa-accordion__button"
      aria-expanded="false" aria-controls="preparation">Before you prepare a draft</button>
  </h3>
  <div id="preparation" class="usa-accordion__content usa-prose" hidden>
    <p>This fictional opportunity asks for a project summary and a named contact.</p>
  </div>
<h3 class="usa-accordion__heading"><button type="button" class="usa-accordion__button" aria-expanded="false" aria-controls="scope">What the example data means</button></h3><div id="scope" class="usa-accordion__content usa-prose" hidden><p>Draft and review are demonstration stages. They do not indicate an actual funding programme or eligibility decision.</p></div>
</div><p class="study-note">USWDS 3.14.0 native accordion and styles, with local Helvetica/Georgia font overrides. Filters are original application code. <a href="vendor/uswds-3.14.0/LICENSE.md">Distribution licence</a>.</p></main><script src="vendor/uswds-3.14.0/uswds.min.js"></script><script>const rows=[...document.querySelectorAll('tbody tr')],q=document.getElementById('query'),t=document.getElementById('topic');function filter(){let n=0;for(const row of rows){const show=(!t.value||row.dataset.topic===t.value)&&row.firstElementChild.textContent.toLowerCase().includes(q.value.trim().toLowerCase());row.hidden=!show;if(show)n++}document.getElementById('count').textContent=n+' '+(n===1?'opportunity':'opportunities');document.getElementById('empty').hidden=n!==0;}document.getElementById('filters').addEventListener('submit',e=>{e.preventDefault();filter()});document.getElementById('clear').addEventListener('click',()=>{q.value='';t.value='';filter();q.focus()});</script></body></html>
```

代码参考

- 从“来源”一节下载完整示例。其 README 给出了确切的本地启动命令。

- 保持 vendor 路径相对于本文档；该归档包含此预览所使用的全部资源。

## USWDS 设计系统 AI Agent 设置

### 实现起点

保留 dist 目录结构，以便 CSS 能正确加载字体和图标。这是预编译的分发方式；自定义主题需要通过 Sass 构建。Sources 中提供的完整示例 ZIP 还包含准确的预览依赖和完整文档。解压后，在该目录中运行 python3 -m http.server 8080，然后打开 http://localhost:8080/uswds.html。请勿通过 file:// 打开基于模块的示例。

```
npm install @uswds/uswds@3.14.0
mkdir -p public/assets/uswds
cp -R node_modules/@uswds/uswds/dist public/assets/uswds/

<!-- HTML head -->
<script src="/assets/uswds/dist/js/uswds-init.min.js"></script>
<link rel="stylesheet" href="/assets/uswds/dist/css/uswds.min.css">
<!-- After the component markup, before closing body -->
<script src="/assets/uswds/dist/js/uswds.min.js"></script>
```

### 适用于你项目的提示词

```
使用 USWDS 3.14.0 构建一个虚构的研究机会比较页面。加载完整的 dist 资源树、初始化脚本、组件样式表和 JavaScript。使用语义化表格展示可比较的记录，并添加说明文字和列标题；提供带标签的搜索和类别筛选、结果数量、实用的无匹配状态以及重置功能。使用原生折叠面板展示补充要求，同时确保关键比较信息始终可见。遵循文档中规定的间距单位和主题角色映射，并注明系统字体覆盖设置。不要将此目录改造成申请流程，也不要暗示真实的资格认定或资助承诺。
```

## USWDS 设计系统资源与适用范围

独立的 USWDS 3.14.0 组件研究示例。机会记录均为虚构，不代表任何联邦机构身份，也不提供申请入口。Helvetica/Arial 和 Georgia 是本地字体替代项，并非 USWDS 默认字体资源。

- 间距单位 数值单位和命名宽度。

- 字体系列角色 字体与角色令牌解析。

- 主题颜色 默认别名和设置。

- 表格 语义化比较与滚动。

- 手风琴 面板状态与标记。

- 开发者设置 分发内容与资源路径。

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

## USWDS 设计系统相关资源

### VA 设计系统

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

### W3C 设计系统

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

### Codex

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


- [实现参考](https://designsystem.digital.gov/components/accordion/)
- [来源](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [来源](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [来源](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [来源](https://designsystem.digital.gov/components/accordion/)
- [阅读配套规范](https://designsystem.digital.gov/documentation/developers/)
- [代码参考](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [阅读配套规范](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [代码参考](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [阅读配套规范](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [阅读配套规范](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [阅读配套规范](https://designsystem.digital.gov/components/table/)
- [阅读配套规范](https://designsystem.digital.gov/components/accordion/)
- [代码参考](https://designsystem.digital.gov/components/accordion/)
- [代码参考](https://designsystem.digital.gov/components/table/)
- [间距单位 数值单位和命名宽度。](https://designsystem.digital.gov/design-tokens/spacing-units/)
- [字体系列角色 字体与角色令牌解析。](https://designsystem.digital.gov/design-tokens/typesetting/font-family/)
- [主题颜色 默认别名和设置。](https://designsystem.digital.gov/design-tokens/color/theme-tokens/)
- [表格 语义化比较与滚动。](https://designsystem.digital.gov/components/table/)
- [手风琴 面板状态与标记。](https://designsystem.digital.gov/components/accordion/)
- [开发者设置 分发内容与资源路径。](https://designsystem.digital.gov/documentation/developers/)