响应式设计规范

把可复用的尺寸与间距变成有语义、可映射、可验证的设计值，让布局在不同空间中使用同一套设计语言。

配套《响应式设计规范》使用；来源与数值边界见《reference.md》。本文给出 Token 分层、起始字典、上下文映射与工程交付示例，不包含已经发布的 Token 包或组件实现。

1. 使用边界¶

本字典主要管理 Web 的断点、间距、容器约束、排版与交互尺寸。折叠成抽屉、列表详情如何返回、焦点如何接续等行为，按设计规范执行；数值 Token 与行为规则共同构成响应式设计。

响应式字典可以复用项目已有视觉基础 Token；不要为响应式再复制颜色、圆角、阴影等没有空间差异的值。Token 不能替代焦点管理、草稿保存、滚动恢复或任务执行机制。

1.1 采用范围与决策责任¶

“基础必需”表示采用本文预设时需要可解析的值，可继承默认，不要求用户填写；“条件启用”表示使用相关组件或能力时补齐；不使用的可选字段可以省略。

每个覆盖项说明“为什么取该值、谁维护、作用域、何时生效、依赖什么”。字段表不是用户设置页；运行时应用通过校验的完整配置，不逐字段刷新出中间的矛盾布局。

2. 分层与命名¶

2.1 三层结构¶

示例引用链：component.dialog.maxWidth → layout.overlay.maxWidth → size.overlay.default。没有组件独有需求时，直接消费语义 Token，无需为每个 CSS 属性建立第三层。

2.2 命名约定¶

• 文档用点路径，如 layout.page.padding.inline；DTCG JSON 用嵌套对象表示层级，不把含点的完整路径作为单个 Token 名称。
• 数值刻度放在基础层；用途名称放在语义层。避免 pagePadding24 这类把数值写进用途的名称。
• 使用 inline、block 等逻辑方向描述边距；具体物理方向由书写模式决定。
• 同一语义名称跨上下文保持不变，避免分别创建 page.padding.mobile、page.padding.tablet、page.padding.desktop。
• Token 可以表达一个布局参数，但不因为有 layout.grid.columns 就要求所有组件遵循同一列数。

以上分层和名称是本项目约定；DTCG 规定交换格式、类型与引用方式，不强制采用这套命名。来源 S04

3. 上下文与解析¶

3.1 空间状态¶

默认空间测量 w 为物理宽度，使用视口 width 媒体查询；组件示例的 C 为逻辑行内尺寸，使用容器 inline-size 查询。两者仅在横排书写模式下可直接比较。

这里的 640 / 1024 CSS px 是建议起点，不是外部标准。区间左闭右开，直接比较连续值；不要用 639px 作为上一档上限而遗漏小数宽度。

布局视口适合页面结构分档；软键盘、安全区与可见高度还需要布局实现单独处理，不能靠这两个宽度 Token 解决。

3.2 独立维度¶

compact 表示可用空间紧凑，dense 表示信息密度较高，二者不能合并为同一维度。无需为了采用本字典而新增密度或主题设置。

本文预设按 §3.3 的确定顺序合并，再解析别名，最后按 §5.1.1 校验。维度优先修改不同字段；同一路径的覆盖要在允许列表中声明，不按设备名称临时猜测优先级。

DTCG Resolver 提供 sets、modifiers 和 contexts 等多上下文组织机制；本文的维度表是项目设计，不是可直接提交给 Resolver 的配置文件。选择上下文的视口测量、容器测量与偏好检测仍由工程实现。来源 S05

3.3 合并、别名与冲突的确定合同¶

本节是项目消费合同，不声称是通用 DTCG Resolver 配置。

1. 加载基础字典与 compact 默认语义，再应用产品默认覆盖。
2. 根据实测视口选择且仅选择一份页面状态：compact 不额外覆盖；regular 或 wide 使用各自完整覆盖集。主题、密度、运动按此顺序应用，但只能写入各自获准字段。
3. 在组件作用域内应用容器状态和组件覆盖；组件不得通过局部配置反向修改全站 Token。页面边距仅由页面空间维度控制，组件局部间距仅由对应组件控制。
4. 组按路径递归合并；同一路径的 Token 节点整体替换，不把 $value 内的对象成员深合并。覆盖节点必须显式保留匹配的 $type，并提供完整 $value。未声明的跨维度同路径覆盖报错，禁止默默采用最后一项。
5. 对最终作用域内的合并结果解析别名。检测缺失目标、循环、类型不匹配及领域非法值；通过后再输出 CSS 或平台值。不要先解析默认别名再覆盖基础值。
6. 任一必需项失败，拒绝整份候选配置；保留上一有效配置。冷启动使用预先交付并经过任务验证的基础单区布局。若该基础布局也未验证，不能宣布验收通过。

手算样本：产品将 space.6 覆盖为 28px，选择 regular 后 layout.page.padding.inline = {space.6}，最终页面边距为 28px。若先把别名解析成 24px 再合并，就会得到错误结果。没有覆盖来源的基础默认仍为 24px。

作用域样本：1440px 视口、500px 工作区，页面采用 wide 边距 32px，记录面板仍用单区布局；两者不互相覆盖。页面断点不能直接触发面板并排。

3.4 单位与轴的输出合同¶

DTCG dimension 支持 px、rem；本文对断点等字段进一步限定为 px 是项目约束。阅读行长可由组件 CSS 使用 ch／ic，也可在明确需要复用时定义具有单位映射的独立字段，但不直接塞进本文 dimension 字典。自定义表达式扩展需标明为工具私有协议。S04、S18

4. 基础值字典¶

以下均为待产品验证的初始值。如果项目已有兼容的基础刻度，应复用并建立映射，不同时维护两份相同数值。

font.size.400 等编号是本项目的刻度标识，不代表字重。标准控件的 40px 高度与触控热区的 44px 是不同对象；图标控件还需同时检查宽度。文字放大时控件应能增长，不能将这些最小值全部输出成固定高度。font.lineHeight.heading 的 1.25 是作者默认值，与 WCAG 1.4.12 的用户覆盖测试值（行高 1.5 倍等）不是同一件事——后者是覆盖后的验收条件，不构成本表的下限（见规范 R3-2）。

5. 语义值与响应式映射¶

5.1 页面与排版¶

表中的引用路径是 Token 别名，括号为默认解析值。

最大宽度始终只是上限，实际宽度仍不得超过可用空间。对话框是否全屏属于组件行为：一旦选择全屏形态，由该形态的样式决定占满可用区域，不能继续用 560px 将其限成窄条。

正文在三档中保持同一字号是有意的设计选择。标题可以分档或采用经过验证的流动字号，但不能让响应式缩小规则抵消用户放大。

5.1.1 领域合法值与解析失败合同¶

格式正确不等于本专题的语义成立：regular=1100px, wide=900px 都是合法 dimension，却使区间表与两个 min-width 查询的实际顺序不再一致；fontSize=0px、maxWidth=0px 也能通过"非负"检查，却不可作为可用默认值。

领域合法值

缺失与非法分开处理

• 缺省上下文：按已声明的默认值解析，属正常路径。
• 未知上下文名称、未解析别名、循环引用、类型不匹配、倒置断点：一律不得静默生效，须输出可预测的错误或落到已定义的回退。

解析失败时的界面行为

• 已运行的界面遇到配置更新失败时，保留上一份通过校验的配置，不丢任务状态、不清空草稿。
• 首次即无有效配置时，采用预先定义并已验证的基础布局，不临时猜值。

默认值、回退值与上一有效配置属于配置管理信息，与配置来源一同记录；实测窗口宽度、焦点对象、任务状态不得写入 Token。

反向样本（用于验收本合同）：倒置断点、相等断点、font.size 为 0、未知的 viewport.tablet、缺失 space.6、同一路径的异类型覆盖、循环引用——每种都应得到可预测的错误或明确回退。默认 compact／regular／wide 分别解析为 16／24／32px 页面边距。用表格演算即可验收，不必先建自动执行器。

5.2 断点、组件和交互尺寸¶

组件断点仅在组件确实需要结构切换时新增，例如 breakpoint.container.recordPanel.inline；其值必须从该组件的最小空间约束推导，本文不预设全站通用的组件阈值。

阅读正文宽度、导航栏宽度、工作台三栏约束等按产品内容增加。不会使用的 Token 无需预先建立。

5.2.1 记录面板的条件字段¶

以下四项仅在采用规范中的记录面板示例时一起启用；示例内容约束尚需产品验证。面板最小尺寸按外框需求计算，父工作区按内容盒测量。

修改三项约束后，构建校验必须重新检查阈值。例如间距由 24 改为 28，704px 已不足，至少需要 708px；不得只有间距生效而保留非法阈值。可以用构建派生计算阈值，但输出为标准 dimension 数值，并保留推导依据，不输出数学表达式别名。

不为“正在编辑”“返回列表”建立尺寸 Token；是否打开详情及焦点接续仍由组件状态管理。

5.3 固定要求与可调值¶

命中区域还涉及间距、形状和相邻目标，不能只比较一个 minSize 数字就宣布通过 WCAG。来源 S08

6. DTCG 交换格式示例¶

以下是页面横向边距这一小部分 Token的完整默认文件示例。dimension 使用带单位的数值对象，别名引用整个 Token 值。完整字典的其他值按同样方式导出；这些示例并非整套产品 Token。

{
  "space": {
    "4": { "$type": "dimension", "$value": { "value": 16, "unit": "px" } },
    "6": { "$type": "dimension", "$value": { "value": 24, "unit": "px" } },
    "8": { "$type": "dimension", "$value": { "value": 32, "unit": "px" } }
  },
  "layout": {
    "page": {
      "padding": {
        "inline": {
          "$type": "dimension",
          "$value": "{space.4}",
          "$description": "页面横向内边距，默认用于 compact 空间状态"
        }
      }
    }
  }
}

regular 上下文的覆盖文件示例：

{
  "layout": {
    "page": {
      "padding": {
        "inline": { "$type": "dimension", "$value": "{space.6}" }
      }
    }
  }
}

wide 上下文的覆盖文件示例：

{
  "layout": {
    "page": {
      "padding": {
        "inline": { "$type": "dimension", "$value": "{space.8}" }
      }
    }
  }
}

覆盖文件依赖默认文件提供的基础值，不能作为独立、引用齐全的 Token 集使用。构建工具按 §3.3 的加载顺序、Token 节点替换与合并后别名解析执行；DTCG Format 本身不会根据文件名自动推断视口状态。

如采用 DTCG Resolver，应另行输出符合 Resolver Schema 的上下文配置并验证。不要把任意自定义的 modes 对象或字符串型 clamp(...) 标为标准 dimension 值。S04、S05

7. Web 输出示例¶

下面是与默认字典对应的 CSS 输出示意，不是完整页面或已经实测的组件。字号按设计换算基准 16px 输出为 rem，不固定用户根字号。断点保留 CSS px，分别代表视口测量阈值。

:root {
  --space-4: 16px;
  --space-6: 24px;
  --space-8: 32px;
  --space-12: 48px;
  --layout-page-padding-inline: var(--space-4);
  --layout-grid-gutter: var(--space-4);
  --layout-section-gap: var(--space-6);
  --layout-content-max-width: 1200px;
  --layout-collection-item-min-width: 240px;
  --type-body-font-size: 1rem;
  --type-body-line-height: 1.5;
  --type-heading-page-font-size: 1.75rem;
  --type-heading-page-line-height: 1.25;
}

/* 从 breakpoint.viewport.regular 编译得到具体查询条件。 */
@media (min-width: 640px) {
  :root {
    --layout-page-padding-inline: var(--space-6);
    --layout-grid-gutter: var(--space-6);
    --layout-section-gap: var(--space-8);
    --type-heading-page-font-size: 2rem;
  }
}

/* 从 breakpoint.viewport.wide 编译得到具体查询条件。 */
@media (min-width: 1024px) {
  :root {
    --layout-page-padding-inline: var(--space-8);
    --layout-section-gap: var(--space-12);
    --type-heading-page-font-size: 2.5rem;
  }
}

.page {
  box-sizing: border-box;
  inline-size: 100%;
  padding-inline: var(--layout-page-padding-inline);
  font-size: var(--type-body-font-size);
  line-height: var(--type-body-line-height);
}

.page__content {
  inline-size: 100%;
  max-inline-size: var(--layout-content-max-width);
  margin-inline: auto;
  min-inline-size: 0;
}

.page__title {
  font-size: var(--type-heading-page-font-size);
  line-height: var(--type-heading-page-line-height);
  overflow-wrap: anywhere;
}

.collection {
  display: grid;
  gap: var(--layout-grid-gutter);
  grid-template-columns: repeat(
    auto-fit,
    minmax(min(100%, var(--layout-collection-item-min-width)), 1fr)
  );
}

.collection > * {
  min-inline-size: 0;
  overflow-wrap: anywhere;
}

min(100%, ...) 允许卡片在窄于首选最小宽度的容器中回退，避免固定最小宽度撑开页面；卡片中的图片、表格等仍需各自处理约束。组件结构切换可使用容器查询，页面断点不能替代该层判断。S03

原生 CSS 的尺寸查询条件不能直接使用 var()：不要输出 @media (min-width: var(--breakpoint)) 或同类容器尺寸条件。由构建工具输出具体数值，并保留来源映射。这与容器样式查询查询自定义属性是不同机制。S11

7.1 容器尺寸消费与基础回退¶

下面与记录面板四项字段一致；704px 是构建输出，不在 CSS 查询中使用 var()。容器自身不切换网格，它的后代 .record-panel 才消费查询。

.record-workspace {
  container: record-workspace / inline-size;
  min-inline-size: 0;
}
.record-panel {
  --record-list-min: 280px;
  --record-detail-min: 400px;
  --record-gap: 24px;
  display: grid;
  grid-template-columns: minmax(0, 1fr);
  gap: var(--record-gap);
}
.record-panel > * {
  min-inline-size: 0;
  box-sizing: border-box;
}
/* data-active 来自用户当前工作状态，非 Token。 */
.record-panel[data-active="list"] > .record-detail,
.record-panel[data-active="detail"] > .record-list {
  display: none;
}
@container record-workspace (inline-size >= 704px) {
  .record-panel {
    grid-template-columns: var(--record-list-min) minmax(var(--record-detail-min), 1fr);
  }
  .record-panel[data-active] > .record-list,
  .record-panel[data-active] > .record-detail {
    display: block;
  }
}

组件只维护一个有效的列表实例与详情实例；若采用多实例实现，隐藏实例不得可聚焦、重复暴露给辅助技术或产生重复 ID。上述 CSS 仅说明排布；跨阈值前由组件按接续表确定 data-active 和焦点去向，返回按钮、输入法状态与模态语义需要行为实现。单靠 display: none 不能证明状态连续。

容器查询不可用时，上述规则保持单区形态；基础的打开详情和返回交互仍由组件提供。不要为了兼容而同时显示两套可提交的表单。S03

7.2 安全区、可见高度与命中区域¶

/* 环境值是运行时输入，不是持久化 Token。安全区采用物理方向。 */
.page {
  padding-left: max(var(--layout-page-padding-inline), env(safe-area-inset-left, 0px));
  padding-right: max(var(--layout-page-padding-inline), env(safe-area-inset-right, 0px));
}
.dialog__scroll {
  max-block-size: 100vh; /* 基础回退 */
  max-block-size: 100dvh;
  overflow: auto;
  padding-bottom: max(16px, env(safe-area-inset-bottom, 0px));
  box-sizing: border-box;
}
.touch-action {
  min-inline-size: 44px;
  min-block-size: 44px;
  padding: 8px;
  font: inherit;
  white-space: normal;
}
.touch-action__icon {
  inline-size: 20px;
  block-size: 20px;
}

安全区示例采用“基础留白与安全距离取大者”，不是重复相加；若设计要求在安全区之外额外留白，另行声明 calc() 策略并测试。仅当产品采用边到边布局时评估 viewport-fit=cover，不能假设 inset 总为非零。上述对话框示例是横排、独立可滚动区域；真实浮层还需扣除外边距与其他固定区域，并在目标设备测试键盘打开后的可达性。dvh 不保证避让软键盘，env(safe-area-inset-bottom) 也不等于键盘高度。S16

控制热区示例输出项目 44px 目标和 20px 图标，允许文字增长，不将最小高度设为固定高度。密度模式不能缩小到违反适用要求；热区重叠要以实际命中测试判定。

8. 设计与工程交付¶

1. 设计源：维护基础值、语义引用和已启用的上下文；在组件记录中说明哪一个容器负责局部适配。
2. 设计工具映射：将基础值与语义值区分管理；工具支持 modes 时，可映射页面空间状态。设计工具中的 mode 不等于浏览器运行时会自动检测宽度，仍需工程映射。
3. 导出：输出 DTCG Token 数据，以及项目所用工具需要的上下文或构建配置。CSS、平台常量等均从同一来源生成。
4. 解析：按 §5.1.1 的领域合法值与解析失败合同校验——未知上下文、缺失基础值、循环引用、类型错误、覆盖冲突与倒置断点分别处置；默认上下文必须明确。
5. 运行验证：依据《设计规范》第 5 章检查真实界面。JSON 可解析、Token 可解析与界面可用是不同的验证层次。
6. 影响检查：记录值的选择理由、关联规则与消费范围；覆盖断点、字号、宽度或固定留白后，复查受影响的任务和语言组合。

建议记录模板：

本次仅建立文档与示例；未进行工具链集成、浏览器运行、设计工具导入或设备验证。

9. 配置验收样本¶

以下是文档级输入／预期合同，不代表已经运行浏览器或设计工具。

验收分三步：JSON 结构与类型 → 所有启用上下文的引用、作用域和数值依赖 → 实际界面的任务、缩放、焦点及输入。前两步通过不能替代第三步。

配置交付与校验¶

示例使用标准 dimension 的 px／rem 表达数值，不能把 dp、pt 或物理米值直接写成同一种交换类型。示例只是一项解析后的页面内边距；视口、容器与密度选择仍由实际布局合同承担，不能据此推定一组断点已经适配。

随附的可执行样例只覆盖 layout.page.padding.inline，其余字段按本字典逐项校验；未覆盖不等于不适用或已通过。样例是所选字段的格式正反例，不是可直接启用全部能力的产品预设。完整产品交付另外包含适用性、依赖、证据、执行映射及进行中操作的生效边界。

字段名、类型或含义变更时更新引用方与验收样例；仅修改说明且不改变合法行为的，保留已有字段名。调用方读取解析后的有效配置，不由 UI 控件、动画或模型文字反推权限、测量或完成事实。参见对应场景。