数据与可视化契约

数据显示不是把示例文字填进矩形。可交付的设计应说明数据含义、来源、格式、用户可执行的操作，以及理想数据不可用时的行为。

同一个月收入示例生成 actual 与 target 值相同的图表和表格，下方列出数据状态 — 从示例数据读到两种呈现：actual 为 120 USD，target 为 150 USD，在图表和表格中含义一致。选择呈现前先声明单位、聚合、格式化或其他转换；还须定义 loading、empty、error、partial 和 stale 行为。示例数值不是运行时数据来源，也不是完整数据契约。查看原图。

同一组语义数据可以有多种明确声明的呈现方式，但格式化和响应式布局不能改变数据含义。

契约应包含什么

先确定表格、网格、指标、列表或图表要回答的问题，再按以下项目描述数据、呈现和异常情况：

事项	必需决策
目的	回答什么问题，支持用户做什么决定。
数据结构	字段键、值类型、是否允许空值、标识符和关系。
数量	最小、典型、最大数量，分页或窗口策略，总数是否已知。
来源	源系统或负责人、聚合方式、刷新时间和过期规则。
呈现	列或数据系列的含义、顺序、分组、排序、筛选、比较基准和精度。
格式	语言区域、时区、货币、单位、正负号、舍入、缺失标记和日期数字格式。
状态	加载、空、错误、部分结果、过期、离线和无权限时的行为。
响应式	保持同一逻辑树，或声明保留语义的变换。
无障碍	名称、描述、表头关系、键盘操作和非视觉等价信息。
可信度	数据限制、估算、样本量、隐私或数值隐藏规则、最后更新时间。

Figma 中的值是测试样例，不等于数据结构、最大长度、精度规则或运行时数据源。

角色：内容、数据显示和控件

内容是编写的产品文案，如标题、解释、脚注或注释。
运行时数据来自服务、CMS、计算、传感器或用户输入。
数据显示把运行时数据呈现为表格、网格、指标、列表、地图或图表。
控件改变查询或呈现方式，如筛选、排序、日期范围、分页、下钻或系列显隐。
来源说明让用户和实现者知道一个值为何可信、是否仍然有效。

不要混淆这些角色。图表标题不是数据字段；突出显示最大值不会产生新值；筛选标签不是结果集合的一部分。

图层标签简短，完整契约结构化

图层名称和现有 DFC Bridge 标签只保留评审所需的定位信息：

revenue [section=revenue-overview]
  period-filter
  revenue-chart
  revenue-table
  data-status

不要用 [series-revenue]、[currency-usd]、[timezone-utc] 等大量标签编码整个数据结构。把完整的结构化契约关联到 revenue-chart：

非独立模块片段。 此例只展示 bridge.data，省略了必需的外层字段。交换数据或验证完整契约前，将其放入交付契约规定的完整 bridge 结构。

{
  "bridge": {
    "data": {
      "displays": [{
        "displayId": "revenue-chart",
        "purpose": "Compare recognized revenue with target by month",
        "source": { "owner": "finance-analytics", "dataset": "recognized-revenue", "refresh": "daily", "staleAfter": "PT36H" },
        "dimensions": [{ "key": "month", "type": "year-month", "timeZone": "UTC" }],
        "measures": [
          { "key": "actual", "type": "decimal", "currency": "USD", "aggregation": "sum" },
          { "key": "target", "type": "decimal", "currency": "USD", "aggregation": "sum" }
        ],
        "format": { "locale": "user", "notation": "compact", "maximumFractionDigits": 1 },
        "states": ["loading", "empty", "error", "partial", "stale"],
        "accessibleEquivalent": "revenue-table"
      }]
    }
  }
}

这里的 revenue-chart 和 revenue-table 提供同一组实际值与目标值。改变 period-filter 还需要反应契约：加载什么、保留什么、如何报告失败。仅有数据记录并未定义这次交互。

结构化元数据可版本化、可评审，并且不依赖目标平台。它可以存于 Figma 插件数据、伴随文件或适配器载荷中，但必须引用稳定的 DFC Bridge 标识，并与设计一起交付。

表格

数据表格契约应声明：

标题或无障碍名称，以及必要的简短摘要；
行标识和列键；
表头作用范围、分组表头及其与数据单元格的关系；
默认排序，以及在客户端还是服务器执行；
筛选含义、当前筛选的播报和重置行为；
分页、无限加载或虚拟化，以及总数的显示规则；
选择模型、批量操作范围和跨页选择是否保留；
可编辑单元格的验证、保存和还原行为；
窄屏溢出规则，不能悄悄隐藏重要字段。

需要跨行列比较数值时，保留表格语义。视觉上改成卡片并不允许丢弃关系。表头关联方式参见 WAI 表格教程。

网格、列表和重复卡片

不要按 Figma 画框刚好容纳几条样例来定义数据结构。应独立描述稳定条目标识、排序、分组、最小或最大或未知数量、分页、重复项、缺失媒体，以及长值和本地化值。

响应式列数改变不等于条目数量改变：

product-grid
  product-card-oak-chair
  product-card-wool-lamp
  product-card-steel-desk
  product-card-cork-stool

这些是稳定的设计样例实例键，不是数组位置，也不是生产数据库 ID。重复条目有不同层次的标识：templateKey 标识可复用卡片模板，designInstanceKey 标识设计样例，runtimeDataKey 或其他产品记录键用于排序、筛选、分页和实时更新后的条目匹配。关系由结构化映射决定，不由 -1、-2 图层后缀决定。不要为了填写契约而暴露机密后端标识符。

若移动端确实加载另一段记录，查询或分页契约必须写明。不要为了让末行整齐而删除样例卡片。

图表和地图

每个图表契约应说明：

分析问题和合适的图表形式；
维度、度量、单位、值域、聚合、基准线和排序；
刻度的完整规则，包括需要时的零基准线和异常值处理；
颜色、形状、线型、尺寸和注释的含义；
悬停、焦点、选择、缩放、平移、下钻和重置行为；
提示框的内容与格式；
无障碍名称，以及概括主要规律的简短说明；
如何通过表格、列表或可下载的等价内容读取数值。

不要只用颜色区分系列或状态。标签与图形标记须满足对比度要求，提示框须能用键盘和指针到达，canvas 或 SVG 图片不能成为唯一信息来源。参见 WAI 复杂图像教程。

格式即语义

声明区域相关的格式规则，而非照抄可见标点：

金额包含币种和货币显示方式；
百分比区分原始值 0.25 与 25；
测量值包含单位、换算和舍入规则；
时间戳包含来源时区、显示时区、夏令时和精度；
范围说明是否包含边界，以及起点和终点含义；
缺失、零、隐藏、估算和不适用的值，含义不同时不能混为同一状态。

缩写、舍入或截断不能导致总数自相矛盾。用户需要精度时，必须能取得完整值。

必需的数据状态

状态	契约问题
加载	是否保留旧数据？进度是否可量化？播报什么？
空	查询有效但没有结果吗？用户如何继续？
错误	哪一步失败？什么仍可用？能否重试？
部分结果	缺少哪部分？是否允许根据不完整结果操作？
过期	数据有多旧？为何继续显示？如何请求刷新？
离线	缓存什么？哪些操作排队？如何报告重新连接？
无权限	隐藏内容、遮蔽敏感部分，还是显示权限申请入口？

骨架屏应接近最终结构，但不能冒充真实数据。实时更新要保留焦点和选择，仅在对用户任务有实质影响时播报。

响应式数据变换

默认保留同一逻辑树。表格滚动、列宽变化、图表重排、图例移动和标签换行，本身不需要结构例外。

若呈现结构确实改变，例如表格变为卡片、多系列图表变为分面小图、内嵌详情变为展开区，则声明响应式变换，记录：

原结构与结果结构的标识；
容器或视口触发条件；
不丢失含义的字段或系列映射；
阅读、焦点和操作顺序；
未直接显示的详情在哪里、如何到达；
状态、选择、筛选及 URL 和历史的保留方式；
每种呈现方式的无障碍等价信息。

屏幕变小不是删除比较字段、来源说明或恢复操作的理由。参见响应式断点。

数据评审条件

以下问题检查数据显示契约是否完整，不是整页 Ready 结果，也不能证明应用已经实现：

能否不猜测任何字段或格式就实现？
样例是否覆盖零条、一条、典型量、最大量、长值、缺失、过期、部分结果和失败？
来源、刷新、单位、精度和时区是否明确？
排序、筛选、分页、选择和下钻是否有完整反应与状态？
窄屏是否保留含义并允许完成同一任务？
键盘或屏幕阅读器用户能否获得同样的值和结论？
必要的隐私限制、隐藏规则、估算和数据限制是否可见？