将 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 将系统令牌、项目主题设置、实用类和组件分开管理。下方参考内容记录了当前文档中的默认主题选项。联邦项目可以配置不同的字体角色或颜色别名，而不必替换每个组件。
此预览是独立的研究机会对比界面，使用 3.14.0 CSS 和手风琴式 JavaScript。其中省略了政府横幅和身份标识。项目名称和阶段均为虚构，筛选完全在浏览器中进行。
一个 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);
}默认的无衬线令牌映射到 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" );
默认的 primary 别名解析为 blue-60v，即 #005ea2。primary-dark 解析为 blue-warm-70v，即 #1a4480；ink 解析为 gray-90，即 #1b1b1b。这些是主题值，并不意味着每个 USWDS 网站都必须采用相同的品牌颜色。
用于操作或标题样式时，选择语义别名；只有在设计决策确实针对系统颜色时，才使用系统颜色令牌。在设置中替换 primary 别名，比在编译后的 CSS 中替换所有匹配的十六进制字符串更可控。
此示例使用了表格标题、带有 scope="col" 的列标题，以及带有 scope="row" 的机会名称。这是一个表格，因为读者需要比较各记录中相同的主题和阶段字段。即使区域可滚动，这些关联关系仍然有效。
可滚动容器设置了 tabindex="0"，让键盘用户可以进入其中。它将宽数据限制在该区域内，避免整个文档被撑宽。预览中使用的是普通文本单元格；如果缺少项目数据，应明确展示内容状态，而不是编造数字。
USWDS 通过 data-sortable 支持可排序表头。可排序表格还需要一个带有 aria-live="polite" 的 usa-table__announcement-region。对于数字显示，可能需要设置 data-sort-value，让格式化后的金额按数值而非字母顺序排序。当前的对比示例未启用排序，因为按主题筛选三行数据才是此示例的预期用途。
每个 usa-accordion__button 的 aria-controls 都指向对应的 usa-accordion__content。原生 JavaScript 会更新 aria-expanded 和可见性。带边框修饰符会改变容器样式；data-allow-multiple 则允许同时展开多个部分。
按钮置于标题内，使内容大纲仍然清晰易懂。判断某个项目是否符合条件所需的要求，应在折叠面板上方保持可见。这里的面板用于补充准备说明，并解释虚构数据集。
安装 @uswds/[email protected]，并复制其 dist 目录；不要将 css、js、img 和 fonts 扁平化到同一个文件夹中。样式表使用图标和字体的相对路径。否则，页面可能看起来部分正常，却缺少折叠符号或字体。
在 head 中加载 uswds-init.min.js，接着加载样式表，并在 body 标记之后加载 uswds.min.js。打包后的库会增强折叠面板。下方的搜索输入框和主题筛选器使用自定义应用逻辑，不会调用远程搜索服务。
原生标签、输入框、选择框和按钮样式提供了控件；应用会将搜索词和所选主题与三条虚构记录进行比对。结果数量通过礼貌播报的实时区域呈现。无匹配结果时会显示说明和重置操作，同时保留已输入的搜索词。
此示例有意区分查找机会与提交申请。展开准备内容不会创建草稿，也不会将要求标记为已完成。实际的资助申请还需要相应的项目政策、身份验证和持久化事务状态。
原生 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>保留 dist 目录结构，以便 CSS 能正确加载字体和图标。这是预编译的分发方式；自定义主题需要通过 Sass 构建。Sources 中提供的完整示例 ZIP 还包含准确的预览依赖和完整文档。解压后，在该目录中运行 python3 -m http.server 8080，然后打开 http://localhost:8080/uswds.html。请勿通过 file:// 打开基于模块的示例。
npm install @uswds/[email protected] 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 3.14.0 组件研究示例。机会记录均为虚构，不代表任何联邦机构身份，也不提供申请入口。Helvetica/Arial 和 Georgia 是本地字体替代项，并非 USWDS 默认字体资源。
