文档呈现模式

参考资料需要稳定锚点与清晰易读的值时，请使用 DocumentValueList。阅读栏有足够空间时，组件会采用紧凑的键值布局；窄屏幕则将每个条目垂直堆叠。较长的值会换行，不会隐藏内容。

fast

--duration-fast

Default .15s

raised

--color-surface-raised

Default light-dark(var(--color-white), var(--color-zinc-90))

smooth

--easing-smooth

Default cubic-bezier(.4, 0, .2, 1)

<DocumentValueList rows={[  { id: 'duration-fast', title: 'fast', identifier: '--duration-fast',    values: [{ label: 'Default', value: '.15s' }] }]} /><DocumentKeyList keys={['animation-duration:', 'transition-duration:']} />

每行使用真实标题与普通锚点链接。ID 在页面中必须唯一；headingLevel={4} 可将条目置于既有三级标题下方。值保持为可选择文字。附有视觉示例的 token 角色使用 DemoTokenTable，完整源代码示例则使用既有代码渲染组件。这两种文档组件都是静态内容，应放在测量用示例布局之外。

#命名空间的使用方

DocumentNamespaceTable 将命名空间映射到完整的公开使用方。较长的行先显示六个 keys，其余可通过鼠标、触控、Enter 或空格键展开原生区域查看。所有 keys 都保留在 HTML 与可移植 Markdown 中。这是服务器组件，不需要客户端状态，应放在教学测量区域之外。

<DocumentNamespaceTable rows={[  { namespace: 'font-family', consumers: ['font:', 'font-family:'] }]} /><DocumentKeyList keys={consumerKeys} previewCount={6} />

DocumentKeyList 默认显示所有 keys。较长的查询列表会中断阅读时，可设置 previewCount；重要指示应放在展开区域之外。请参阅完整的命名空间注册表。

#Utility 命名空间表

NamespaceUtilityTable 将 token 命名空间关联到接受该命名空间的 utility keys。分组有说明时，表格会保留原 Guide 分开的“分组”“Utility keys”和“说明”列。优化后的共用样式使用细致分隔线与一致的阅读节奏。窄屏幕上，表格只在自身可通过键盘聚焦的区域内滚动，页面宽度保持固定。

请参阅完整 utility 表示例。

<NamespaceUtilityTable groups={[  { label: 'Surfaces', namespace: 'color-surface',    keys: ['surface'], description: 'Panels, cards and overlays.' }]} />

请提供面向读者的分组名称，以及来自 manifest 的源 keys；namespace 或 namespaces 会过滤不支持的 keys。没有说明时，表格使用两列。这是文档阅读辅助，应放在示例的测量布局之外。实际用法请参阅色彩、间距、排版及 Utility 表查看页。

#数值 Token 表

ThemeNumberVariableTable 从 preset 读取数值 tokens 和单位。spacing 呈现方式通过斜线背景与浮起对象显示每个实际间距。表格具有稳定的 token 与数值列、细致的行分隔线，以及窄屏幕下可通过键盘聚焦的滚动区域。

请参阅完整间距表示例。

<ThemeNumberVariableTable namespace="spacing" representation="spacing" />

representation prop 可以省略。断点和容器使用同一份数据驱动表格，附上说明但不显示间距示例。请以文字保留原生 token 值与参考单位，并将这份列表放在测量用布局示例之外。数值表查看页呈现当前的共用表格。

#文件结构

文件与目录结构请按照 Monorepo 指南使用 ExplorerView。原生嵌套列表保留层级，文件夹与文件类型图标仅作装饰。说明应写在周围正文中。

<ExplorerView items={[  { name: 'package.json' },  { name: 'master.css' },  { name: 'assets', children: [] }]} />

这是只读列表，因此条目不提供 Tab 停靠点、展开状态或树形控件的键盘行为。普通代码区块应用于文件内容与命令，不应用于呈现目录树。

导出纯文本树形结构时，请使用相同的 items。完整示例请参阅 Monorepo、路由级样式和编写包。

#资源发现瀑布图

DemoWaterfall 以文字说明和具名资源行呈现示意性的请求顺序，不包含实测时间轴或动画播放。可选标记可指出首次绘制等条件，但也须在图注中解释该条件。实测结果应使用基准测试组件。

<DemoWaterfall  title="A dependency discovered later"  description="The second request becomes known after the first resource loads."  rows={[    { label: 'Entry', start: 0, end: 40, tone: 'violet' },    { label: 'Dependency', start: 50, end: 90, tone: 'blue' }  ]}/>

位置值介于 0 到 100，只表示绘图几何。请以文字说明依赖关系；装饰性长条对辅助技术隐藏。容器较窄时，标签会堆叠在各轨道上方。请参阅关键资源。 瀑布图查看页呈现当前的请求顺序图。

#CSS 应用前后

DemoStyleComparison 将相同且可信任的 HTML 放入两份隔离的浏览器文档。一份使用浏览器原生默认样式，另一份应用提供的 CSS，让布局变化清楚可见，同时不会闪烁内容或改变周围页面。

<DemoStyleComparison  html='<p class="message">Saved to your workspace.</p>'  css='.message { padding: 1rem; font: 500 1rem/1.5 system-ui; }'  height={160}/>

默认情况下，两个预览使用相同固定高度，必要时以原生方式滚动。对于上方首次绘制比较这类普通文档流内容，可传入 sizing="content"，让每个框架随文档内容伸缩，包括原生 margin。固定定位、粘性定位或依赖视口的几何布局，请保留默认 viewport 尺寸模式。比较网格只负责各 iframe 外的布局；未应用样式的文档不会收到示例 reset 或对象样式。只可传入网站自行编写的标记。请参阅首次绘制样式。

#文档流程

DocumentFlow 使用真实文字与原生列表语义，呈现简短、有顺序的流程。编号阶段在宽屏幕共用阅读栏，空间不足时则垂直堆叠。这是静态说明，布局不表示时间尺度或当前进行中的步骤。

<DocumentFlow  title="Publish a document"  steps={[    { title: 'Write', description: 'Prepare the source content.' },    { title: 'Publish', description: 'Deliver the reviewed output.' }  ]}/>

请使用二到四个精简阶段。可选图注可在阶段下方解释共通限制。组件自行管理网格、间距与边框，应放在任何被测布局之外，不会添加控件、焦点停靠点或动画。

DeliveryFlow 提供共用且可导出的组合示例，涵盖 runtime 与 hydration、源代码扫描、原生 CSS 裁剪和路由样式。有顺序的文字也会包含在搜索与 Markdown 中。

#文档选项导航

阅读栏中有少量相关目标时，请使用 DocumentChoices。每个链接都有标题、简短说明和可选的装饰图标。各行具有充足的点击范围、可见的键盘焦点轮廓和原生导航语义。整行应保持为单一链接，不要在其中嵌套控件。

<DocumentChoices label="Related guides" entries={[  { title: 'Theme tokens', description: 'Shared product values.', href: 'https://rc.css.master.co/guide/theme' }]} />

MigrationGuides 等产品适配器会将自己的图像与条目提供给共用导航组件。需要分类与字母导航的大型目录，请使用 DocumentationIndex。这些导航组件应放在教学布局之外。

#阅读内容比较

读者需要在文档栏中比较文字或 class 语法时，请用 DocumentComparison 包裹双列 Markdown 表格。窄屏幕仍保留两列可见，长语法则换行。需要多段说明的决策使用列表，必须保留格式的源代码使用代码区块。这个静态外层保留原生表头，并负责与独立表格相同的外部间距和响应式延伸；内层表格不会再次延伸。在 figure 或托盘中，表格会保持在该表面的框架内。

<DocumentComparison>| Master CSS class | Native CSS effect || --- | --- || `(border-radius:.75rem)` | Sets `border-radius: .75rem`. |</DocumentComparison>

请参阅 token family 映射与渲染方式选择。

#语法映射

短语法 tokens 与原生 CSS 的对照请使用 DocumentCodeTable。行标题保留完整 token，CSS 则在自然空白处换行。较长的生成规则应放在代码区块中。表格是静态阅读辅助，应放在示例测量区域之外。

<DocumentCodeTable label="Token" rows={[  { syntax: '@layer(components)', css: '@layer components' },  { syntax: '@motion-reduce', css: '@media (prefers-reduced-motion: reduce)' }]} />

第一列的默认标签为“Syntax”。条件参考文档在具名变体与任意查询中都使用此模式。可移植 Markdown 保留原始双列表格与所有值。