# CFPB 设计系统

## CFPB 设计系统 界面预览

打开原生说明，使用单独的清单，并重置本地状态。调整窗口大小，查看十二栏版面如何堆叠。

## CFPB 设计系统 设计参考

CFPB 软件包 5.10.2 编译后的 CSS 和 ES 模块；当前公开的基础规范指南。演示使用原生 Expandable 类和 JavaScript。全局基础样式 CSS 逐字复制自已发布模块的基础样式字符串，并使用系统字体回退。文档表格与版本化代码不一致时，下文的 font-size-adjust 和标题行距以该版本代码为准。不表示与 CFPB 存在关联，也未使用 CFPB 标志。

### 颜色与实际自定义属性

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --black | #101820 | 默认文本色；绿色用作品牌强调色，不用作默认正文颜色。 |
| --green | #20aa3f | Slug 标题强调色与机构调色板参考。 |
| --pacific | #0072ce | 链接与交互提示色系。 |
| --gray-5 / --gray-40 | #f7f8f9 / #b4b5b6 | 5.10.2 中 Expandable 的背景和边框。 |
| --red / --gold | #d14124 / #ff9e1b | 辅助调色板；不要仅靠颜色替代文字状态说明。 |
### 版本化基础样式中的排版

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| Current brand font | Source Sans 3 | 2025 年 7 月取代 Avenir Next；演示使用软件包中的 system-ui 回退字体。 |
| Body | 16px / 1.375 | 默认浏览器根字号下，行框为 22px。 |
| H1 | 34px / 1.25; weight 600 | 在 <=600px 时为 26px；桌面端代码行高为 42.5px。 |
| H2 | 26px / 1.25; weight 600 | 在 <=600px 时为 22px。 |
| H3 / H4 | 22px weight 400 / 18px weight 500 | 小屏幕为 18px / 16px；两者的行高均为 1.25。 |
| H5 | 14px / 1.25; weight 600 | 全大写，字间距为 1px。 |
| Normalization | base .517; step .0054 | 版本化自定义属性会为标题逐级增加更大的调整值；这与简化版基础规范表不同。 |
### 网格、节奏与响应式范围

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| Grid | 12 columns; 30px gutters | 文档中的布局模型；演示组合为 8/4 的编辑式分栏。 |
| Maximum width | 1230px | 使用响应式外边距，而非固定宽度的内容区。 |
| Edge spacing | 15px mobile; 30px tablet/desktop | 在窄屏上保留易读的间距。 |
| Breakpoints | 0–600, 601–900, 901–1020, 1021–1200, 1201+ | 已在 5.10.2 模块中核实导出的 varsBreakpoints。 |
| Text rhythm | 15px paragraph gap; 30px stacked headings | 编辑式间距，并非宣称存在通用的 4px 设计令牌尺度。 |
| Measure | 66 characters ideal; 45–90 range | 连续阅读的字体建议；预览的最大宽度为 66ch。 |
### 可展开结构与运行时

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| Root | o-expandable | 背景与边框修饰符可独立选用，且均为可选项。 |
| Required descendants | __header, __label, __content | 标题是原生按钮。运行时会添加行为钩子和 ARIA 状态。 |
| Initialization | Expandable.init(container) | 返回与匹配根元素对应的已初始化实例。 |
| Instance API | expand(), collapse(), isExpanded(), getLabelText() | 已对照发布的 5.10.2 版本核实，而非较旧的 toggleTargetState 文档条目。 |
| Initial expanded state | o-expandable--onload-open | 请在初始化前设置；不要手动与运行时可见性类冲突。 |
| Group choice | o-expandable-group--accordion | 选择启用互斥行为。预览特意允许对比多个同时打开的面板。 |
## CFPB 设计系统 完整指南

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

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

## CFPB 设计系统 CFPB 实现范围

### 内容优先于装饰

> CFPB 将编辑式信息架构与表单及信息披露组件结合起来。它的网格、字体层级和小型全大写 slug 标题，与标志性的绿色同样重要。本示例是原创阅读工作表：保留必要的指引信息，并通过原生 Expandable 展示可选说明。它不是财务建议、投诉提交表单或政府服务。

该软件包是公开的，但政府印章和 CFPB 标识各有单独的使用限制。复用代码并不意味着服务具有官方身份。因此，本示例不含印章、徽标、官方网站横幅或仿制的政府页眉。

阅读配套规范

## CFPB 设计系统 排版与阅读节奏

### Source Sans 3 与版本差异

当前字体指南指定使用 Source Sans 3，该字体于 2025 年 7 月取代 Avenir Next。本地示例没有依赖外部托管字体，而是有意使用编译后的系统字体回退。真实的品牌化实现应通过文档中说明的授权字体 mixin 提供获准使用的字体文件。

公开的标题表与当前基础样式字符串并不完全一致。在软件包 5.10.2 中，H1 为 2.125em，行高为 1.25；在根字号为 16px 时，对应 34/42.5，而不是表格中的 60px 行高。上述参考遵循可执行源码。标题规范化也会按级别使用不同的调整值；不要将简化版表格改成全局覆盖规则。

段落长度尽量控制在约 66 个字符，段间距为 15px。除紧凑型 H5/slug 样式外，标题使用句首字母大写。这能让指南文章便于浏览，而不必将每个段落都放进卡片。

阅读配套规范

## CFPB 设计系统 色彩与编辑式版面

### 依据用途使用颜色，而不只是使用绿色

编译后的 CSS 提供 --black、--green、--pacific 和分级的辅助色系。文本使用黑色；Pacific 用作更易识别的交互提示色。浅灰色 Expandable 背景表示阅读边界，并非禁用状态。原生 slug 标题将细灰色全宽横线与较粗的短绿色线段结合起来。

工作表有意将主要阅读区域留白。绿色用于章节分隔，进度数字则使用普通易读文本。即使无法区分绿色和红色，已完成或已勾选的项目仍然清晰易懂。页面不会为调色板中的每种颜色都赋予成功或错误含义。

- 使用 --gray-5 作为克制的可展开背景层，并用 --gray-40 绘制轮廓。

- 除了色相，还要通过下划线或交互样式让链接易于辨认。

- 身份标识仅限授权使用；获得调色板许可，并不意味着可以暗示存在关联。

阅读配套规范

## CFPB 设计系统 十二列网格与恰到好处的信息密度

### 留有适当边距的文章

文档所述网格包含十二列、固定 30px 列间距，最大宽度为 1230px。移动设备上的外侧间距为 15px，较大布局则使用 30px。预览将其转化为八列的阅读区域和四列的工作清单；宽度达到 901px 时采用并排布局，之后则将清单移至文章下方。这种分栏是基于已发布网格构建的应用页面布局，并非官方通用页面模板。

即使页面可以继续加宽，长文本区域仍会将最大宽度限制在 66ch。按钮会自动换行，侧栏不会固定高度，也不会形成嵌套滚动区域。展开说明只会增加普通文档高度，因此同样的布局也适用于资源页面中的嵌入式预览。

阅读配套规范

## CFPB 设计系统 原生可展开组件结构

### 将触发按钮与可选内容分开

旧版 Expandable 根元素包含一个 __header 按钮、一个 __label 和一个 __content 区域。按钮是键盘焦点目标。在此示例中，标签由 span 提供，装饰性加号和减号提示不会纳入无障碍名称。库会在初始化时设置展开状态和行为钩子，应用无需重复执行这些更改。

--background 和 --border 修饰符用于呈现带边框的样式。--padded 修饰符提供更宽松的样式，并相应增大标签字号，但并非所有折叠面板都必须使用。工作表的重要说明始终放在隐藏面板之外，因为读者在打开可选说明前就应理解任务要求。

```
<div class="o-expandable o-expandable--background o-expandable--border">
  <button class="o-expandable__header" type="button">
    <span class="o-expandable__label">Keep the question specific</span>
    <span class="o-expandable__cues" aria-hidden="true">
      <span class="o-expandable__cue-open">+</span>
      <span class="o-expandable__cue-close">−</span>
    </span>
  </button>
  <div class="o-expandable__content">
    <p>Describe the document and the words you want explained.</p>
  </div>
</div>
```

代码参考

阅读配套规范

## CFPB 设计系统 折叠面板与清单行为

### 两种彼此独立的状态

折叠面板状态由原生库管理。工作表负责管理三个普通复选框的值并据此计算数量。打开面板不会将任务标记为已完成，勾选任务也不会折叠内容。这两种状态刻意采用不同的模型：内容可见并不代表读者已经理解。

5.10.2 版本的实例提供 expand、collapse 和 isExpanded。公开的 Expandables 页面还引用了较旧的 toggleTargetState；因此，本指南使用实际版本化的 API。全部展开和全部关闭操作会遍历已初始化的实例。这里采用彼此独立的面板更合适，因为读者可能需要对照两段说明。

重置操作会清除所有复选框的值，并通过库的 API 折叠面板。它不会虚构提交成功的确认信息。进度通过礼貌提示状态元素播报，且每次复选框状态变化后都不会移动键盘焦点。

阅读配套规范

## CFPB 设计系统 编译后的资源与基础样式

### 使用 ES 模块，而非经典脚本

安装固定版本的软件包，将两个编译后的资源复制到静态资源目录，再通过模块脚本导入 Expandable。已发布的 5.10.2 index.js 使用 ES 导出，因此，照搬旧版集成示例中的经典脚本标签会导致语法错误。它也不会自动初始化旧版 Expandable 根元素。

组件样式表本身不包含全局页面标题和正文样式。生产项目可以按照官方集成指南所示编译软件包基础 SCSS。此独立示例则保留了从同一已发布模块中提取的基础 CSS 原文字符串，并将其作为单独记录的本地文件。这样的提取属于本地打包选择，并非 CFPB 新发布的入口文件。

如果编译包含图标引用的源 SCSS，请加入项目文档中说明的 PostCSS SVG 替换步骤。编译后的快照已经解析了这些引用。不要臆造只用 Sass 的配置，以免 --cfpb-background-icon-svg 无法解析。

1. 安装 5.10.2，并将其 TERMS.md 与本地提供的资源一同保留。

2. 加载组件 CSS 以及选定的全局基础样式；字体需显式配置。

3. 使用模块导入；待容器标记加载完成后再进行初始化，然后为返回的实例绑定应用操作。

阅读配套规范

## CFPB 设计系统 验证阅读流程

### 无障碍测试不止于折叠面板

在窄屏下，主标题会根据原生基础样式缩小，清单则显示在文章之后。在桌面屏幕上，两列布局会同时展示可选阅读内容和工作说明。请在两种视图下都展开所有面板进行测试，而不只是检查折叠状态。

按 Tab 键移动到每个原生按钮，再按 Enter 或 Space 切换状态。确认库会更新 aria-expanded，并且隐藏内容不再出现在 Tab 键导航顺序中。接着勾选两个任务，再展开并关闭所有说明；确认计数在重置前仍为两个。这些测试能发现截图无法呈现的应用与库之间的状态冲突。

此本地示例不包含存储、分析、网络提交或真实个人数据。使用原生组件本身并不能证明最终网站符合要求；采用该组件的服务仍需评估对比度、内容、浏览器支持情况以及辅助技术的表现。

阅读配套规范

## CFPB 设计系统组件示例

### 原生 Expandable

旧版结构要求、装饰性提示和可选说明内容。

```
<div class="o-expandable o-expandable--background o-expandable--border">
  <button class="o-expandable__header" type="button">
    <span class="o-expandable__label">Keep the question specific</span>
    <span class="o-expandable__cues" aria-hidden="true">
      <span class="o-expandable__cue-open">+</span>
      <span class="o-expandable__cue-close">−</span>
    </span>
  </button>
  <div class="o-expandable__content">
    <p>Describe the document and the words you want explained.</p>
  </div>
</div>
```

代码参考

### 初始化并控制内容折叠

使用 5.10.2 模块及其返回的实例；是否加载全局基础样式需另行决定。

```
npm install --save-exact @cfpb/cfpb-design-system@5.10.2
# Copy the published compiled files as static assets:
mkdir -p public/vendor/cfpb
cp node_modules/@cfpb/cfpb-design-system/dist/index.css public/vendor/cfpb/
cp node_modules/@cfpb/cfpb-design-system/dist/index.js public/vendor/cfpb/

# In the HTML document:
<link rel="stylesheet" href="/vendor/cfpb/index.css">
<!-- Supply project global/base typography separately. -->
<script type="module">
  import { Expandable } from '/vendor/cfpb/index.js';
  const panels = Expandable.init(document.querySelector('#guide'));
  document.querySelector('#open-all').addEventListener('click', () => {
    panels.forEach(panel => panel.expand());
  });
  document.querySelector('#close-all').addEventListener('click', () => {
    panels.forEach(panel => panel.collapse());
  });
</script>
```

代码参考

- 已发布的 5.10.2 使用 ESM。请勿将其作为经典脚本加载。

- 此示例使用从软件包中逐字提取的基础样式，并在其 vendor SOURCE.md 中说明。

### 完整的独立示例

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

```
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>CFPB reading worksheet specimen</title><link rel="stylesheet" href="vendor/cfpb-5.10.2/index.css"><link rel="stylesheet" href="vendor/cfpb-5.10.2/base-extracted.css"><style>*{box-sizing:border-box}body{margin:0;background:#fff}main{max-width:1230px;margin:auto;padding:30px}header{max-width:66ch;margin-bottom:30px}.layout{display:grid;grid-template-columns:2fr 1fr;gap:30px}.article{min-width:0}.o-expandable{margin:15px 0}.toolbar{display:flex;gap:15px;flex-wrap:wrap;margin:15px 0}.notes{border-top:5px solid var(--gray-40);padding-top:15px}.notes label{display:flex;gap:10px;margin:20px 0;align-items:flex-start}.notes input{flex:none;width:20px;height:20px;margin-top:2px;accent-color:var(--pacific)}.o-expandable__content p{max-width:66ch}.eyebrow{color:var(--gray);font-size:14px}.note{font-size:14px;margin-top:30px;color:var(--gray)}button{font-family:inherit}button:focus-visible,a:focus-visible,input:focus-visible{outline:3px solid var(--pacific);outline-offset:3px}@media(max-width:900px){.layout{grid-template-columns:1fr}}@media(max-width:600px){main{padding:20px 15px}}</style><main><header><p class="eyebrow">Independent educational specimen · CFPB components</p><h1>Make your question easier to answer</h1><p>Use this reading worksheet to organize a question about an unfamiliar document. No information is submitted or saved.</p></header><div class="layout"><section class="article" id="guide"><div class="m-slug-header"><h2 class="m-slug-header__heading">Before a conversation</h2></div><p>A useful question identifies the document, quotes the unclear wording, and says what you want explained. Keep account numbers and other private details out of this practice worksheet.</p><div class="toolbar"><button id="open-all" class="a-btn a-btn--secondary">Open all explanations</button><button id="close-all" class="a-btn a-btn--secondary">Close all</button></div><div class="o-expandable o-expandable--background o-expandable--border">
  <button class="o-expandable__header" type="button">
    <span class="o-expandable__label">Keep the question specific</span>
    <span class="o-expandable__cues" aria-hidden="true">
      <span class="o-expandable__cue-open">+</span>
      <span class="o-expandable__cue-close">−</span>
    </span>
  </button>
  <div class="o-expandable__content">
    <p>Describe the document and the words you want explained.</p>
  </div>
</div><div class="o-expandable o-expandable--background o-expandable--border">
  <button class="o-expandable__header" type="button">
    <span class="o-expandable__label">Separate a question from a request</span>
    <span class="o-expandable__cues" aria-hidden="true">
      <span class="o-expandable__cue-open">+</span>
      <span class="o-expandable__cue-close">−</span>
    </span>
  </button>
  <div class="o-expandable__content">
    <p>“What does this label mean?” asks for an explanation. “Please send a copy” asks for an action. Writing them separately makes the desired response easier to identify.</p>
  </div>
</div><p class="note">Original practice content. This example does not provide financial advice or represent a CFPB service.</p></section><aside class="notes"><h2>Your working notes</h2><p>Use the checklist as a local memory aid.</p><label><input type="checkbox">I can name the document I am asking about.</label><label><input type="checkbox">I have identified the wording I want explained.</label><label><input type="checkbox">I know whether I need an explanation or an action.</label><p id="count" role="status" aria-live="polite">0 of 3 notes checked</p><button id="reset" class="a-btn">Reset worksheet</button></aside></div></main><script type="module">import {Expandable} from './vendor/cfpb-5.10.2/index.js';const panels=Expandable.init(document.querySelector('#guide'));document.querySelector('#open-all').onclick=()=>panels.forEach(x=>x.expand());document.querySelector('#close-all').onclick=()=>panels.forEach(x=>x.collapse());const checks=[...document.querySelectorAll('input[type=checkbox]')];const update=()=>document.querySelector('#count').textContent=checks.filter(x=>x.checked).length+' of 3 notes checked';checks.forEach(x=>x.onchange=update);document.querySelector('#reset').onclick=()=>{checks.forEach(x=>x.checked=false);update();panels.forEach(x=>x.collapse())};window.demoReady=true;</script></html>
```

代码参考

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

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

## CFPB 设计系统 AI Agent 配置

### 实现起点

本地演示运行原生 5.10.2 编译模块和 CSS。npm 复制方案供项目使用；从源 SCSS 构建时，还需要按文档说明处理图标。Sources 中提供的完整可运行示例 ZIP 还包含准确的预览依赖和完整文档。将其解压后，在该目录运行 python3 -m http.server 8080，然后打开 http://localhost:8080/cfpb.html。请勿通过 file:// 打开基于模块的示例。

```
npm install --save-exact @cfpb/cfpb-design-system@5.10.2
# Copy the published compiled files as static assets:
mkdir -p public/vendor/cfpb
cp node_modules/@cfpb/cfpb-design-system/dist/index.css public/vendor/cfpb/
cp node_modules/@cfpb/cfpb-design-system/dist/index.js public/vendor/cfpb/

# In the HTML document:
<link rel="stylesheet" href="/vendor/cfpb/index.css">
<!-- Supply project global/base typography separately. -->
<script type="module">
  import { Expandable } from '/vendor/cfpb/index.js';
  const panels = Expandable.init(document.querySelector('#guide'));
  document.querySelector('#open-all').addEventListener('click', () => {
    panels.forEach(panel => panel.expand());
  });
  document.querySelector('#close-all').addEventListener('click', () => {
    panels.forEach(panel => panel.collapse());
  });
</script>
```

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

```
使用实际的 5.10.2 Expandable 模块，创建一份独立且参考 CFPB 的编辑式工作表。包含必需的页眉/标签/内容结构、独立的全部展开和全部收起操作，以及一份普通复选框清单，其选中状态不会因展开或收起内容而改变。采用十二列 8/4 布局，在 901px 以下堆叠显示，移动端边缘留白 15px，阅读行宽为 66ch。基础排版需与组件 CSS 分开提供。请勿添加 CFPB 标识、金融建议、虚假的提交功能，或为 ESM 包导入经典脚本。
```

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

独立实现参考。原生包组件不代表与 CFPB 有任何关联。原创教育内容，不提供金融建议，也不提交信息；重复使用前请查看 TERMS.md。

- 字体 当前字体、规范化样式和阅读节奏。

- 标题 响应式标题层级；可与对应版本的代码对照。

- 颜色 CFPB 调色板与使用指南。

- 网格 十二列、列间距和最大宽度。

- 展开 组件结构与变体。

- 安装 包和源代码构建集成。

- 令牌 新版令牌管线的适用范围。

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

## CFPB 设计系统 相关资源

### CMS 设计系统

使用带版本的主题变量、真实的 Review 组件 API，以及可正常运行的编辑与审核流程，实现 CMS Core，并保留用户答案和焦点。

### Det Fælles Designsystem

通过完整的资源对比，探索丹麦 DKFDS 主题、实际 Sass 尺度和无障碍表格模式；其中包含数字排序、提交搜索和无结果状态恢复。

### 设计系统 .italia

使用 Bootstrap Italia 的真实字体排版、响应式 Stepper 结构和可恢复的本地表单状态，实现易于阅读的服务流程。


- [实现参考](https://cfpb.github.io/design-system/components/expandables)
- [来源](https://cfpb.github.io/design-system/foundation/color)
- [来源](https://cdn.jsdelivr.net/npm/@cfpb/cfpb-design-system@5.10.2/dist/index.js)
- [来源](https://cfpb.github.io/design-system/foundation/grid)
- [阅读配套规范](https://cfpb.github.io/design-system/)
- [阅读配套规范](https://cfpb.github.io/design-system/foundation/fonts)
- [阅读配套规范](https://cfpb.github.io/design-system/foundation/color)
- [阅读配套规范](https://cfpb.github.io/design-system/foundation/grid)
- [代码参考](https://cfpb.github.io/design-system/components/expandables)
- [阅读配套规范](https://cfpb.github.io/design-system/components/expandables)
- [阅读配套规范](https://cdn.jsdelivr.net/npm/@cfpb/cfpb-design-system@5.10.2/dist/index.js)
- [阅读配套规范](https://cfpb.github.io/design-system/development/integrating-the-design-system-into-your-project)
- [代码参考](https://cfpb.github.io/design-system/development/integrating-the-design-system-into-your-project)
- [字体 当前字体、规范化样式和阅读节奏。](https://cfpb.github.io/design-system/foundation/fonts)
- [标题 响应式标题层级；可与对应版本的代码对照。](https://cfpb.github.io/design-system/foundation/headings)
- [颜色 CFPB 调色板与使用指南。](https://cfpb.github.io/design-system/foundation/color)
- [网格 十二列、列间距和最大宽度。](https://cfpb.github.io/design-system/foundation/grid)
- [展开 组件结构与变体。](https://cfpb.github.io/design-system/components/expandables)
- [安装 包和源代码构建集成。](https://cfpb.github.io/design-system/development/integrating-the-design-system-into-your-project)
- [令牌 新版令牌管线的适用范围。](https://cfpb.github.io/design-system/development/design-tokens)