# CMS 设计系统

## CMS 设计系统 界面预览

编辑一项偏好，保存或放弃草稿，并完成本地审核，不会提交数据。

## CMS 设计系统 设计参考

CMS Core 18.1.0 发布了 core-theme.css 和组件 CSS。通用文档描述与版本化资源不一致时，以版本化资源为准。预览使用 Arial 回退字体和应用专用的 48rem 外壳。

### 颜色角色

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --color-base | #262626 | 版本化 Core 文本值；较早的概览文字写的是 #333。 |
| --color-primary / primary-darker | #0071bc / #004f84 | 操作与较深的交互参考色。 |
| --color-error / success | #e31c3d / #12890e | 状态颜色应始终搭配文字说明。 |
| --color-border | #d9d9d9 | --review__border-color 也使用此值。 |
| --color-focus-dark / focus-light | #bd13b8 / #ffffff | 主题焦点参考色。 |
| --color-background / gray-lightest | #ffffff / #f2f2f2 | 页面与浅色辅助表面。 |
### 排版

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --font-family-body / heading | Open Sans, Inter, Roboto, Helvetica Neue, Arial Nova, Nimbus Sans, Arial, sans-serif | 18.1.0 中的确切字体系列顺序；预览使用 Arial 替代。 |
| --font-size-sm / md / lg / xl / 2xl | .875 / 1 / 1.125 / 1.3125 / 1.5rem | 在 16px 根字号下为 14 / 16 / 18 / 21 / 24px。 |
| --font-size-3xl--mobile / 3xl | 1.875 / 2.25rem | 30 / 36px。 |
| --font-size-4xl--mobile / 4xl | 2.25 / 3rem | 36 / 48px。 |
| --font-size-5xl--mobile / --tablet / 5xl | 2.25 / 3 / 3.75rem | 36 / 48 / 60px。 |
| --font-line-height-base / heading | 1.5 / approximately 1.3 | 主题将标题值存储为 1.2999999523162842。 |
### 间距、网格与形状

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --spacer-half / 1 / 2 / 3 | 4 / 8 / 16 / 24px | 实用类数值修饰符以 8px 为倍数。 |
| --spacer-4 / 5 / 6 / 7 | 32 / 40 / 48 / 56px | 更大的布局节奏。 |
| --grid-columns | 12 | 网格构成。 |
| --grid-gutter-width / grid-form-gutter-width | 32 / 16px | 当前主题中，通用间距与表单间距应分别处理。 |
| --site-max-width | 1104px | 主题容器参考值。 |
| --site-margins / site-margins-mobile | 3rem / 1.5rem | 在标准根字号下为 48 / 24px。 |
| --radius-default / medium / large | 3 / 4 / 8px | 并非所有场景通用的单一圆角值。 |
### 响应式断点

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| sm | 544px | 移动优先的小尺寸前缀。 |
| md | 768px | 中尺寸前缀。 |
| lg | 1024px | 大尺寸前缀。 |
| xl | 1280px | 超大尺寸前缀。 |
## CMS 设计系统 完整指南

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

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

## CMS 设计系统 选择 Core 或子主题

### 该软件包是一组主题，而非单一品牌皮肤

> CMS Core 提供共享的界面基础，并为 Healthcare.gov、Medicare.gov 和 CMS.gov 分别提供子设计系统。本参考固定使用 @cmsgov/design-system 18.1.0 及其 core-theme.css。子主题中提供的颜色、标志或组件并不自动适用于 Core。示例有意采用中性的通知偏好设置流程，并省略官方政府横幅和身份标识。

可通过 React、Preact、Web Component 和手动 HTML/CSS 等方式集成。文档建议在内置行为有用时使用 JavaScript 组件；Web Component 集合只是其中一部分。我们的独立示例使用真实的 Core CSS，并通过应用的 JavaScript 实现编辑、保存和取消。我们并未声称 CSS 实现了验证、路由或持久化。

阅读配套规范

## CMS 设计系统 阅读版本化主题

### 同时引入两个样式表

index.css 定义组件规则，core-theme.css 提供这些规则所需的变量。省略主题可能导致类名有效但变量值无法解析。反之，即使页面能够渲染，在描述 Core 字体排印时引入 Medicare 主题，也会造成误导。此设置使用同一 18.1.0 版本中的两个资源。

本指南中的数值以版本化主题为准。例如，--color-base 的值是 #262626，尽管较宽泛的字体排印说明仍提到 #333。主题中的 --grid-gutter-width 为 --spacer-4（32px），而 --grid-form-gutter-width 为 --spacer-2（16px）。不应将概述中关于 16px 间距的描述套用到所有网格变体。这些差异会影响真实布局的复现。

阅读配套规范

## CMS 设计系统 Core 字体排印与层级

### 统一字体系列，明确字号用途

Core 的标题和正文使用 Open Sans。18.1.0 主题的回退字体链依次为 Inter、Roboto、Helvetica Neue、Arial Nova、Nimbus Sans、Arial 和 sans-serif。本地示例明确使用 Arial，因此不会请求外部字体文件；其字体度量与完整的官方字体排印有所不同。

正文基础字号为 1rem，行高为 1.5。字号变量包括在 16px 根字号下的 14、16、18、21 和 24px，之后是更大的响应式字号：3xl 在移动端为 30px，其他情况下为 36px；4xl 在移动端为 36px，其他情况下为 48px；5xl 在移动端为 36px、平板端为 48px，在最大尺寸下为 60px。这些是主题定义的值，并不意味着每个页面标题都应使用最大字号。请使用语义化标题，以及适当的实用类或 ds-content 映射。

阅读配套规范

## CMS 设计系统 间距与响应式布局

### 以 8px 为节奏单位，含半步进

--spacer-1 到 --spacer-7 分别对应 8–56px，每级递增 8px。--spacer-half 为 4px，--spacer-none 为零。因此，像 ds-u-margin--2 这样的类表示 16px，而不是 2rem。评审行的原生 CSS 已提供 16px 的垂直内边距和 2px 的底边框；无需再为每个答案在外层表单中添加带内边距的卡片。

Core 站点的最大宽度为 1104px；在版本化主题中，站点边距为 3rem，移动端边距为 1.5rem。本示例选用更窄的 48rem 阅读容器，容纳两条简短的评审行。这是应用层的宽度，并非新增的 CMS 令牌。

阅读配套规范

### 使用 CMS 断点前缀

文档中定义的断点为：sm 544px、md 768px、lg 1024px 和 xl 1280px。布局和选定的工具类系列支持这些前缀，例如 ds-u-lg-display--none。不要假设每个组件类都提供响应式变体。在移动端，评审中的长内容必须能够换行，不能把 Edit 控件挤出屏幕；必要时，预览中的应用操作行也会改为纵向排列。

阅读配套规范

## CMS 设计系统 评审行结构与 API

### 标签、值和上下文相关的编辑入口

Review 用于包裹一项可评审内容。标题默认为 h3，可通过 headingLevel 设置，其后是表示当前值的子元素。editHref 用于提供跳转目标；未设置时不会显示编辑链接。editAriaLabel 可为重复出现的可见 Edit 链接提供明确无歧义的可访问名称。18.1.0 版本的类型声明还提供 editText、onEditClick 和 editContent；其中，自定义 editContent 会替换默认链接。

React 示例使用了已在发布的类型声明中核实的实际属性。示例中的路径仅用于说明应用路由，实际路由需由使用方应用实现。原生 CSS 替代方案展示了 ds-c-review、ds-c-review__content 和 ds-c-review__heading 结构；导航和更新仍需由应用负责管理。

```
import { Review } from '@cmsgov/design-system';
import '@cmsgov/design-system/css/index.css';
import '@cmsgov/design-system/css/core-theme.css';

export default function ContactReview() {
  return <section aria-labelledby="contact-title">
    <h2 id="contact-title">Contact preferences</h2>
    <Review heading="Notice format" headingLevel="3"
      editHref="/preferences/notice-format"
      editAriaLabel="Edit notice format">
      <p>Large print</p>
    </Review>
    <Review heading="Preferred language" headingLevel="3"
      editHref="/preferences/language"
      editAriaLabel="Edit preferred language">
      <p>English</p>
    </Review>
  </section>;
}
```

代码参考

阅读配套规范

## CMS 设计系统 行内编辑与分区编辑

### 让更正流程保持清晰可预期

CMS 表单评审模式区分编辑单个答案和编辑整个分区。通知格式和语言偏好等互不相关的答案适合行内编辑。家庭成员及其相关关系等彼此依赖的答案，则可能需要分区编辑，以便应用同时重新核对一致性。官方指南明确指出，在分区标题旁放置分区级 Edit 并非 Review 组件本身实现的功能。

预览会为所选行打开一个专用字段集。保存后，仅更新该值，并将焦点返回触发编辑的 Edit 控件；取消则丢弃草稿。编辑器打开时，显示的答案也会保持不变。局部状态提示会反映实际更改，而不是仅因编辑表单出现就宣告成功。

- 在填写和评审阶段使用相同的问题标签和顺序。

- 为每一行提供上下文相关的编辑名称，即使可见链接显示为 Edit 也不例外。

- 如果相关答案需要一并更改，请在单行组件之外实现分区编辑。

阅读配套规范

## CMS 设计系统 评审、完成与真实性

### 评审不等于提交回执

Review 适用于可编辑的表单答案，不适合作为搜索结果的替代形式。在实际提交流程中，该模式要求评审之后提供最终提交操作。只有在后端确实完成操作后，才能显示回执。本示例则提供 Complete local review，并明确说明不会提交或存储任何内容。

Core 将主色蓝定义为 #0071bc、错误红定义为 #e31c3d、成功绿定义为 #12890e，边框灰定义为 #d9d9d9。已保存的偏好会通过文字而不仅仅是颜色来标识。焦点样式使用主题中的浅色和深色焦点参考；将 Edit 样式设为极简控件时，不要移除焦点指示器。最终状态可通过键盘访问，且不会清除评审行。

阅读配套规范

## CMS 设计系统 安全安装与扩展

### 完整的 CSS 流程与实际组件流程

安装固定版本的软件包，并通过软件包导出路径导入 css/index.css 和 css/core-theme.css。React 使用方从软件包根路径导入 Review；Preact 使用方可使用 /preact 入口。该示例无需编译 Sass。复制静态 CSS 时，请保留字体和图片资源的相对路径，或像本示例一样明确选择受支持的回退方案。

CMS 命名空间区分了 ds-l- 布局类、ds-c- 组件类和 ds-u- 工具类。应用类不应伪装成未记录在文档中的官方组件。在预览中，阅读容器和行内编辑器由本地组合构成；评审行和按钮则使用分发的样式。

1. 加载匹配的 Core 组件和主题 CSS，然后渲染两条评审行。

2. 将每个编辑操作连接到受控编辑器；保存或取消后恢复焦点。

3. 在桌面和移动端宽度下，测试已更改的值、已丢弃的草稿，以及最终的本地完成状态。

阅读配套规范

## CMS 设计系统组件示例

### 两条互不相关的评审行

使用实际的 18.1.0 React 属性；链接的编辑路由由使用方应用实现。

```
import { Review } from '@cmsgov/design-system';
import '@cmsgov/design-system/css/index.css';
import '@cmsgov/design-system/css/core-theme.css';

export default function ContactReview() {
  return <section aria-labelledby="contact-title">
    <h2 id="contact-title">Contact preferences</h2>
    <Review heading="Notice format" headingLevel="3"
      editHref="/preferences/notice-format"
      editAriaLabel="Edit notice format">
      <p>Large print</p>
    </Review>
    <Review heading="Preferred language" headingLevel="3"
      editHref="/preferences/language"
      editAriaLabel="Edit preferred language">
      <p>English</p>
    </Review>
  </section>;
}
```

代码参考

- Review 的标题默认为 h3。

- editContent 会替换默认编辑链接；要显示该链接，必须设置 editHref。

### 原生 CSS 评审结构

当应用负责管理交互时，一种实用的手动 HTML 集成方式。

```
<div class="ds-c-review">
  <div class="ds-c-review__content">
    <h3 class="ds-c-review__heading">Notice format</h3>
    <p>Large print</p>
  </div>
  <a href="/preferences/notice-format" aria-label="Edit notice format">Edit</a>
</div>
```

代码参考

### 完整的独立示例

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

```
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Notice preferences — CMS Core specimen</title><link rel="stylesheet" href="vendor/cms-18.1.0/index.css"><link rel="stylesheet" href="vendor/cms-18.1.0/core-theme.css"><style>body,body *,body *::before,body *::after{font-family:Arial,sans-serif!important}body{margin:0;border-top:8px solid #0071bc}.shell{max-width:48rem;margin:auto;padding:32px 24px}h1{font-size:32px;line-height:1.3;margin:16px 0 24px}h2{font-size:24px;margin:32px 0 16px}.intro{margin-bottom:32px}.ds-c-review__content p{margin:8px 0}.edit{align-self:flex-start;min-width:48px;border:0;background:none;color:#0071bc;text-decoration:underline;font-size:16px;padding:4px;cursor:pointer}.editor{margin:24px 0;padding:24px;background:#e6f1f8;border-left:4px solid #0071bc}fieldset{padding:0;border:0;margin:0}legend{font-size:20px;font-weight:700;margin-bottom:16px}.choice{display:flex;align-items:center;gap:12px;margin:16px 0}.choice input{width:20px;height:20px;accent-color:#0071bc}.actions{display:flex;flex-wrap:wrap;gap:24px;margin-top:24px}footer{margin-top:40px;padding-top:24px;border-top:1px solid #d9d9d9}#status{margin-top:24px;font-weight:bold}button:focus-visible,input:focus-visible{outline:3px solid #bd13b8;outline-offset:3px}[hidden]{display:none!important}@media(max-width:543px){.editor{padding:16px}.actions{flex-direction:column;align-items:flex-start}}</style></head><body><main class="shell"><p>CMS Core component example</p><h1>Review your notice preferences</h1><p class="intro">Check these fictional preferences before completing the local review. This example does not collect health information or contact details.</p><section aria-labelledby="preferences"><h2 id="preferences">Notice preferences</h2><div class="ds-c-review"><div class="ds-c-review__content"><h3 class="ds-c-review__heading">Notice format</h3><p id="format-value">Standard print</p></div><button class="edit" data-field="format" aria-label="Edit notice format">Edit</button></div><div class="ds-c-review"><div class="ds-c-review__content"><h3 class="ds-c-review__heading">Preferred language</h3><p id="language-value">English</p></div><button class="edit" data-field="language" aria-label="Edit preferred language">Edit</button></div></section><form class="editor" id="editor" hidden><fieldset><legend id="legend"></legend><div id="choices"></div></fieldset><div class="actions"><button class="ds-c-button ds-c-button--solid" type="submit">Save preference</button><button class="ds-c-button" id="cancel" type="button">Cancel</button></div></form><div class="actions"><button class="ds-c-button ds-c-button--solid" id="complete">Complete local review</button><button class="ds-c-button" id="reset">Reset example</button></div><p id="status" role="status"></p><footer>Native CMS Core 18.1.0 CSS · Arial fallback<br>Changes exist only on this page. Nothing is submitted or saved after you leave.</footer></main><script>const values={format:'Standard print',language:'English'},options={format:['Standard print','Large print','Electronic text'],language:['English','Spanish']},labels={format:'Notice format',language:'Preferred language'};let field,opener;const editor=document.querySelector('#editor'),status=document.querySelector('#status');function close(){editor.hidden=true;opener?.focus()}document.querySelectorAll('.edit').forEach(button=>button.addEventListener('click',()=>{field=button.dataset.field;opener=button;document.querySelector('#legend').textContent='Edit '+labels[field].toLowerCase();document.querySelector('#choices').replaceChildren(...options[field].map((text,i)=>{const label=document.createElement('label');label.className='choice';const input=document.createElement('input');input.type='radio';input.name='preference';input.value=text;input.checked=text===values[field];label.append(input,document.createTextNode(text));return label}));editor.hidden=false;editor.querySelector('input:checked').focus();status.textContent=''}));editor.addEventListener('submit',event=>{event.preventDefault();values[field]=editor.querySelector('input:checked').value;document.querySelector('#'+field+'-value').textContent=values[field];status.textContent=labels[field]+' updated to '+values[field]+'.';close()});document.querySelector('#cancel').addEventListener('click',close);document.querySelector('#complete').addEventListener('click',()=>{if(!editor.hidden){status.textContent='Save or cancel the open edit before completing the review.';editor.querySelector('input:checked').focus();return}status.textContent='Local review complete. No data was submitted.'});document.querySelector('#reset').addEventListener('click',()=>{values.format='Standard print';values.language='English';Object.entries(values).forEach(([key,value])=>document.querySelector('#'+key+'-value').textContent=value);editor.hidden=true;status.textContent='Example reset.'});</script></body></html>
```

代码参考

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

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

## CMS 设计系统 AI Agent 设置

### 实现起点

已根据发布的 18.1.0 元数据和类型声明核实软件包导出项及 Review 属性。提供了 React 示例供集成使用；独立预览通过原生 CSS 和本地应用 JavaScript 执行。Sources 中的完整可运行示例 ZIP 还包含预览所需的确切依赖项和完整文档。将其解压到目录中，在该目录运行 python3 -m http.server 8080，然后打开 http://localhost:8080/cms.html。请勿通过 file:// 打开基于模块的示例。

```
// npm install @cmsgov/design-system@18.1.0
import { Review } from '@cmsgov/design-system';
import '@cmsgov/design-system/css/index.css';
import '@cmsgov/design-system/css/core-theme.css';

export default function ContactReview() {
  return <section aria-labelledby="contact-title">
    <h2 id="contact-title">Contact preferences</h2>
    <Review heading="Notice format" headingLevel="3"
      editHref="/preferences/notice-format"
      editAriaLabel="Edit notice format">
      <p>Large print</p>
    </Review>
    <Review heading="Preferred language" headingLevel="3"
      editHref="/preferences/language"
      editAriaLabel="Edit preferred language">
      <p>English</p>
    </Review>
  </section>;
}
```

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

```
构建一个 CMS Core 18.1.0 审核界面。同时加载 index.css 和 core-theme.css。使用 Review 的 heading、children、editHref 和 editAriaLabel，为每个可独立编辑的答案设置相应属性；区块级编辑属于单独的应用组合。编辑草稿时保留问题顺序和已保存值。保存或取消后将焦点返回原处，并播报实际更新内容。使用 Core 设计令牌，包括 #262626 基本文字颜色、以 8px 为间距并以 4px 为半步长、32px 通用网格间距和 16px 表单间距。不要混用子主题徽标，也不要让人误以为本地审核会提交申请。
```

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

Core 主题技术参考。虚构的偏好值和仅限本地的更改；不提供健康资格建议，不代表与 CMS 存在关联，也不代表表单已提交。

- CMS Design System 官方介绍、基础规范和组件目录。

- 开发者指南 官方集成方式和软件包指南。

- 表单审核 用于审核表单信息的模式。

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

## CMS 设计系统 相关资源

### Det Fælles Designsystem

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

### 设计系统 .italia

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

### Designsystemet

通过完整的任务说明编辑器，探索 Designsystemet 实际的主题角色、尺寸模式和原生字段行为，并查看字符数反馈及保留的呈现状态。


- [实现参考](https://design.cms.gov/components/review/)
- [来源](https://cdn.jsdelivr.net/npm/@cmsgov/design-system@18.1.0/dist/css/core-theme.css)
- [来源](https://design.cms.gov/foundation/layout-grid/responsive-design/)
- [阅读配套规范](https://design.cms.gov/getting-started/for-developers/)
- [阅读配套规范](https://cdn.jsdelivr.net/npm/@cmsgov/design-system@18.1.0/dist/css/core-theme.css)
- [阅读配套规范](https://design.cms.gov/foundation/spacing/)
- [阅读配套规范](https://design.cms.gov/foundation/layout-grid/responsive-design/)
- [代码参考](https://cdn.jsdelivr.net/npm/@cmsgov/design-system@18.1.0/dist/react-components/types/Review/Review.d.ts)
- [阅读配套规范](https://design.cms.gov/components/review/)
- [阅读配套规范](https://design.cms.gov/patterns/Forms/form-review/)
- [代码参考](https://design.cms.gov/components/review/)
- [CMS Design System 官方介绍、基础规范和组件目录。](https://design.cms.gov/)
- [开发者指南 官方集成方式和软件包指南。](https://design.cms.gov/getting-started/for-developers/)
- [表单审核 用于审核表单信息的模式。](https://design.cms.gov/patterns/Forms/form-review/)