CMS 设计系统.

名称 / 规则	值 / 配置	用途
`--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 设计系统完整指南

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

DESIGN-cms.md

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

下载指南

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

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

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

可通过 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 断点前缀

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 结构；导航和更新仍需由应用负责管理。

jsx

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- 工具类。应用类不应伪装成未记录在文档中的官方组件。在预览中，阅读容器和行内编辑器由本地组合构成；评审行和按钮则使用分发的样式。

加载匹配的 Core 组件和主题 CSS，然后渲染两条评审行。
将每个编辑操作连接到受控编辑器；保存或取消后恢复焦点。
在桌面和移动端宽度下，测试已更改的值、已丢弃的草稿，以及最终的本地完成状态。

CMS 设计系统组件示例

两条互不相关的评审行

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

jsx

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 集成方式。

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 提供服务。

html

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