政府与公共服务 · 新资源

CFPB 设计系统.

实现 CFPB 的编辑网格、现行排版规范和原生 Expandables,并提供可用的阅读工作表、经过验证的软件包 API,以及明确的品牌标识使用边界。

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

CFPB 设计系统 界面预览

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

编辑式阅读工作表打开完整示例
原生 CFPB 5.10.2 CSS 和 Expandable JavaScript;逐字提取软件包基础样式 CSS,使用系统字体回退,并保留原创应用内容。· 实现参考
02

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 / #b4b5b65.10.2 中 Expandable 的背景和边框。
--red / --gold#d14124 / #ff9e1b辅助调色板;不要仅靠颜色替代文字状态说明。

版本化基础样式中的排版

来源
名称 / 规则值 / 配置用途
Current brand fontSource Sans 32025 年 7 月取代 Avenir Next;演示使用软件包中的 system-ui 回退字体。
Body16px / 1.375默认浏览器根字号下,行框为 22px。
H134px / 1.25; weight 600在 <=600px 时为 26px;桌面端代码行高为 42.5px。
H226px / 1.25; weight 600在 <=600px 时为 22px。
H3 / H422px weight 400 / 18px weight 500小屏幕为 18px / 16px;两者的行高均为 1.25。
H514px / 1.25; weight 600全大写,字间距为 1px。
Normalizationbase .517; step .0054版本化自定义属性会为标题逐级增加更大的调整值;这与简化版基础规范表不同。

网格、节奏与响应式范围

来源
名称 / 规则值 / 配置用途
Grid12 columns; 30px gutters文档中的布局模型;演示组合为 8/4 的编辑式分栏。
Maximum width1230px使用响应式外边距,而非固定宽度的内容区。
Edge spacing15px mobile; 30px tablet/desktop在窄屏上保留易读的间距。
Breakpoints0–600, 601–900, 901–1020, 1021–1200, 1201+已在 5.10.2 模块中核实导出的 varsBreakpoints。
Text rhythm15px paragraph gap; 30px stacked headings编辑式间距,并非宣称存在通用的 4px 设计令牌尺度。
Measure66 characters ideal; 45–90 range连续阅读的字体建议;预览的最大宽度为 66ch。

可展开结构与运行时

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

CFPB 设计系统 完整指南

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

DESIGN-cfpb.md

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

下载指南

CFPB 设计系统 CFPB 实现范围

内容优先于装饰

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

摘自本 OpenDesign 指南

该软件包是公开的,但政府印章和 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 修饰符提供更宽松的样式,并相应增大标签字号,但并非所有折叠面板都必须使用。工作表的重要说明始终放在隐藏面板之外,因为读者在打开可选说明前就应理解任务要求。

html
<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

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

html
<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 模块及其返回的实例;是否加载全局基础样式需另行决定。

html
npm install --save-exact @cfpb/[email protected]
# 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 提供服务。

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

CFPB 设计系统 AI Agent 配置

实现起点

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

bash / html
npm install --save-exact @cfpb/[email protected]
# 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>

适用于你项目的提示词

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

CFPB 设计系统 来源与范围

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