设计系统编写

完整示例、源代码与控件应放在一起。共用 UI 负责周围的呈现，示例本身则负责所有 CSS 前提与被测关系。

标志、金色、字体与文字语气请参阅品牌指南。本手册负责组件接口与示例构建。

#导入共用组件

在 Astro 与 MDX 中，通过明确的 @master/internal-site/demo/*.astro 或 *.svelte 子路径导入基本组件。Astro 渲染静态结构，Svelte islands 添加测量、播放与视口控件。需要 CSS 的示例在服务器使用公开编译器，并保留完整源代码与生成输出。

Demo

接口： title, description, caption, controls, source, background, padding, align, frame

一个示例就是一个 ui-tray：标题栏（title、description、controls）、ui-stage、source（代码窗口与默认折叠的 DemoGeneratedCSS），以及图注。class 和 style 应用到展示区；frameClassName 则设置托盘样式。内容已有自身外框时，例如 DemoViewport 浏览器或比较画面，请使用 frame="none"。

子元素自行管理间距时，请使用 padding="none"。展示区将主体居中；align="start" 则从起始侧排列。外框不可为被测主体额外添加布局、containment、裁剪或尺寸。

DemoSurface

接口： elevation="flat" | "raised", 原生 div props

圆角为 10px 的 ui-sheet，不会隐式添加布局、内边距或裁剪。可用明确的圆角 utilities 覆盖；raised 选项使用 rise-1 高度。

DemoItem

接口： tone, variant, 原生 div props

最小尺寸为 3rem 的 ui-item 图块，由 utilities 设置几何与布局。默认色调为 neutral；blue、violet、amber、green 和 red 是明确的教学角色，必须以图例或标签命名。

DemoComparison

接口： items，包含 label 和 children, 原生 div props

ui-compare 为每种条件提供一个附图注的展示区，空间足够时并排呈现。

DemoMedia, DemoSwatch

接口： Media 接受 SVG props 与可选的 tone，或接受 src 和 alt；色样需要 label，并可提供 value。

可复用的 SVG 图像与具名色彩样本。示例文字直接使用 preset utilities。

DemoLabel, DemoLegend

接口： 文字；图例的 items 包含 label 和 tone。

注释放在主体旁，不参与其布局。

DemoMeasure

接口： label, children

通过 ResizeObserver 测量内容外层容器，并在独立读数区更新宽高。请放在示例父元素之外。

DemoAxes

接口： inline, block, children

在示例周围标明向右的水平轴与向下的垂直轴。只有这些物理方向仍符合场景时，才可自定义标签。

DemoControls

接口： label, variant="plain" | "segmented", children

具名的原生控件分组；segmented 会渲染 ui-segmented 轨道，按钮带有 aria-pressed。请通过 controls 放入托盘标题栏。

DemoScrollArea

接口： 原生 div props

可聚焦且限制溢出范围的区域。

DemoMotion

接口： children

使用浏览器动画，明确提供播放、暂停与重播。

DemoViewport

接口： title, document 或 src, responsive, chrome, widthPresets, theme, print, motion, initialTheme, inspect, height, maxWidth, sizing

隔离的 iframe；宽度控件会调整实际视口。浏览器外框（只有窗口圆点，不显示地址）随 responsive 启用，其他预览保持 plain。只有教学需要比较配色模式时，才添加 theme。

Fit 使用可用宽度，最高到 maxWidth。滑块与即时读数描述同一个物理视口。DemoContainer 将相同限制应用到自身外层容器，页面视口则保持不变。

DemoThemeComparison

接口： name, title, html, css, caption, height, print

将一份可信任的示例编译成两份各自应用主题、按内容决定尺寸的文档。

DemoPalette

接口： 可选 families

固定的 preset 色彩列表，搭配原生剪贴板操作。

DemoCopyButton

接口： value, label, 可选 feedback="value" | "compact", 原生 button props

先报告待处理请求，再报告实际剪贴板结果，并保留键盘焦点。默认反馈包含值；值已显示在控件旁时，可使用 compact，并为简短状态预留空间。

DemoTokenTable

接口： rows, 可选 descriptionTitle

双列文档列表；较长 tokens 会在表格内滚动。

DemoContainer

接口： title, caption, children, maxWidth

完整托盘，标题栏提供可通过键盘操作的宽度控件，用于调整被测外层容器；containment 则由子元素负责。

DemoPageViewport

接口： src, title, height

在真实、可滚动的视口中显示可信任的网站示例页。

#选择刚好够用的外框

background 接受 plain（默认）、hatch、grid、dots 或 checkerboard。padding 接受 lg（默认）、sm 或 none。嵌入视口、满幅场景或自行管理内边距的组合应使用 none。

#配合各层表面

圆角按托盘 4px 内缩量逐层配合：14px 托盘内放置 10px 展示区、代码窗口或面板，8px 菜单内放置 4px 条目。高度遵循 sink < flat < rise-1 < rise-1h < rise-2 < rise-3 < overlay 的顺序，各层使用 --ui-elevation-* 角色，不自行编写阴影。内凹区域通过 --ui-elevation-sink 低于周围表面。

选中、按下与复制反馈期间，控件方框、图标槽位与标签起点应保持稳定。悬停时上升半个像素，按下时沉入内凹区域。文字变大时，允许控件与标签换行，并保持键盘焦点可见。

行内教学需要超过文档可用宽度时，请以具名、可通过键盘聚焦的滚动区域包裹完整主体。保留主体的 float、flex 与尺寸规则。网站的 data-preview-scroll 边界使用左右方向键横向滚动；标签与控件仍在主体之外。

菜单使用 ui-select 并保留原生行为；组件自行绘制箭头，不取代浏览器选择器或键盘操作。选项标签应简短，并确认文字放大到 200% 时仍可完整显示。

图标与范围滑块手柄应在两种模式下以实际显示尺寸检查。小手柄需要比大面板更明确的边缘，才能在轨道上保持可见。非对称图标需要视觉居中时，只调整稳定槽位内的图形。禁用控件保留选中位置，但移除活动状态的文本颜色与接触阴影。

客户端组件可能在布局与实际控件之间添加 island host。设置组件 class 的作用范围时，不要依赖跨越该边界的直接子元素关系。反馈出现前后都应检查实际控件。

#最小组合

下方所有示例都可直接在 MDX 使用。周围示例负责几何布局，这些小型组合则说明注释与控件应放在哪里。

<DemoSurface className="p-md">  <DemoLabel>Layer</DemoLabel>  <p className="mt-xs mb(0) text-sm">Form follows function.</p></DemoSurface><DemoComparison items={[  { label: 'Before', children: <DemoItem>Before</DemoItem> },  { label: 'After', children: <DemoItem tone="violet" variant="outline">After</DemoItem> },]} /><DemoMedia tone="blue" className="w-full h-auto" /><DemoMedia src="/demo/landscape.svg" alt="Sun above mountains" /><DemoSwatch label="Subject" value="bg-blue-60" className="bg-blue-60" /><DemoAxes>  <DemoMeasure label="Container">    <div className="flex gap-sm">{/* measured layout */}</div>  </DemoMeasure></DemoAxes><DemoLegend items={[{ tone: 'blue', label: 'Subject' }]} /><DemoControls label="Alignment" variant="segmented">  <button type="button" aria-pressed="true">Start</button></DemoControls><DemoScrollArea aria-label="Layers" className="(height:10rem)">  {/* overflowing content */}</DemoScrollArea><DemoMotion>  <DemoItem className="(width:4rem) (height:4rem) (animation-name:rotate) (animation-duration:2s) (animation-timing-function:linear) (animation-iteration-count:infinite)" /></DemoMotion><DemoViewport title="Responsive layout" document={htmlDocument} responsive />

DemoComparison 将每种条件放在独立且附图注的展示区；垂直比较时，使用原生堆叠父元素。DemoScrollArea 会有意建立溢出。DemoViewport 接受具有自身 CSS 的完整 HTML 文档，支持原生事件、主题检查与打印预览。默认上限为 1600px，因此可到达 preset 中 1280px 的 lg 断点。适配可用宽度的窄视口可能小于 240px，滑块会报告真实宽度。需要更宽阈值时，请设置 maxWidth。只可传入可信任、由网站编写的文档；iframe 隔离布局，但不是安全边界。设置 initialTheme="light" 或 "dark" 可固定初始模式，省略时则跟随周围页面。控件在预览就绪后启用。需要编译的 utility 示例请使用 Reference 组合示例。

#具名视口宽度

将 widthPresets 搭配 responsive，可在范围控件旁提供有意义的边界。第一个预设值设置 iframe 初始宽度，Fit 则恢复为可用画布宽度。断点值应取自项目当前的主题。每个预设值都会改变实际视口，即使宽度超过显示它的手机也一样。

<DemoViewport  title="A breakpoint comparison"  document={htmlDocument}  responsive  widthPresets={[    { label: 'Below the boundary', width: breakpoint - 1 },    { label: 'Above the boundary', width: breakpoint + 1 },  ]}/>

预设宽度应保持在范围内（240px 至 maxWidth），并使用不同且具有说明性的标签。宽框架在画布内滚动；不要缩放示例主体或改写其样式来模拟媒体查询。语法教程使用 preset 的 sm 边界演示内边距与条件式悬停行为。

#忠实呈现行为

不要只为了让标签居中，就在主体添加布局、containment、变换或裁剪，这些属性可能改变正在讲解的行为。控件应放在场景之外；依赖视口的示例则使用 iframe。

#配合教学内容设置画布尺寸

小屏幕上会堆叠的普通文档流比较，请使用 sizing="content"。图片加载或文字换行时，框架会跟随文档自然高度，让读者不需要第二个垂直滚动区域就能看到全部示例。

固定定位、滚动、视口单位与高度条件，请保留默认的 sizing="viewport"。此模式中，height 定义实际视口。示例高度依赖 iframe 自身高度时，不可使用内容尺寸模式。

<DemoViewport title="Image fitting" document={comparisonDocument} sizing="content" /><DemoViewport title="Sticky navigation" document={scrollingDocument} height={300} />

#明确呈现定位与绘制边界

定位示例应在显示的 HTML 中提供包含块。标签必须放在被测布局之外，插入 flex 行或文字流会改变教学内容。虚线轮廓可标明原始位置与父元素边界，不增加边框尺寸。

堆叠示例需要实际重叠的定位方框。讲解 z-index 时，应同时呈现子元素与父级上下文。isolation 示例则将比较背景放在被测元素之外，让读者看出哪些像素未参与混合。

裁剪示例应区分滚动容器与裁剪边界。视口中可信任的示例控件支持 data-scroll-container="element-id" 搭配 data-scroll-edge="start" 或 "end"，会调用元素的原生 scrollTo()。控件应放在被裁剪元素之外；独立示例使用普通 DOM 事件监听器。

#呈现实际滚动几何

显示的 HTML 应保留滚动视口尺寸、overflow、轨道方向与吸附候选。滚动组合示例只装饰该结构，不会用共用样式补上缺少的轨道或滚动高度。目标导航控件与位置读数应放在滚动视口之外。

请以嵌套的外、内滚动区域比较滚动链。即使平台隐藏滚动条，原生位置读数仍能让结果可见。data-scroll-readout="element-id" 报告实际偏移；data-scroll-offset="target-id" 搭配 data-scrollport="container-id" 及 data-scroll-axis="x" 或 "y"，报告目标相对滚动视口边缘的内缩距离。

带有 data-scroll-to="target-id" 的目标控件使用原生 scrollIntoView()，并采用目标的计算后吸附位置；即使浏览器忽略最近容器选项，也会保留周围文档的滚动位置。演示吸附停止时，使用 data-scroll-by="container-id" 搭配 data-scroll-distance="600"：相对移动可能停在中间吸附点，直接前往终点则可能略过。相对吸附停止请求会立即执行，方便比较目的地。平滑滚动示例遵循系统减少动态效果的偏好。

#在布局外测量 flex 尺寸

Flex 组合示例用完整、显示出的 HTML 提供父元素、条目、basis、间距与约束。装饰轮廓不会添加内边距、最小尺寸或 flex 行为。轴标签与测量值应放在被测容器之外，避免成为额外 flex 条目。

在可信任的 iframe 示例中，data-size-readout="element-id" 会以小数一位报告实际 border-box 尺寸。ResizeObserver 跟踪每个被测元素，也包括字体加载后变化的内在尺寸。data-layout-axis="container-id" 将计算后的主轴描述为 inline 或 block，适用时也标明反向。响应式 iframe 会改变真实媒体查询条件。

起始 basis 与最终尺寸应明确区分。grow 系数分配正的剩余空间；shrink 系数则以内侧 flex basis 加权。教学需要简单外部尺寸比例时，可在被测条目内放入带内边距的标签。方向与顺序示例用 tabindex="0" 的原生按钮呈现源代码焦点顺序，不添加自定义键盘处理或正值 tab index。

#区分对齐与分配

对齐组合示例沿用 flex 尺寸示例的布局外观。显示的 HTML 应完整编写父元素、轨道、条目、间距与自动尺寸约束。共用外观只添加轮廓与色调，不提供上述前提。每个比较都应具名，标签与读数则放在被测容器之外。

data-alignment-axis="container-id" 搭配 data-axis-kind="main"、"cross" 或 "both"，可从计算后布局描述相关逻辑轴。在 Grid 中，main 对应 inline，cross 对应 block；Flexbox 则遵循当前 flex 方向。data-style-readout="element-id" 搭配 data-style-property="property-name"，报告原生计算值，也包括解析后的网格列宽。

data-position-readout="item-id" 搭配 data-position-origin="container-id"，报告条目 border-box 相对容器内侧左上角的偏移。这是物理、可见的偏移，不是 grid-area 原点或未滚动内容坐标。负值可让不安全对齐与实际滚动清楚可见。偏移应搭配尺寸，并说明正在对齐哪个元素或轨道。

拉伸效果应以自动尺寸条目搭配明确尺寸的同级元素演示。安全对齐则比较可容纳内容与真实溢出内容；滚动视口应可聚焦且具有无障碍名称。保留原生溢出，让读者检查哪些边缘仍可到达。

#呈现网格轨道与放置方式

Grid 组合示例会渲染完整编写的父元素与子元素。请在该 HTML 中定义显式轨道、隐式尺寸、流向、间距与条目位置。共用外框只添加外观与外部读数，不可创建轨道、补上缺少条目，或在不完整父元素上建立 Grid。

除了既有尺寸与位置读数，请使用 data-style-readout 显示 grid-template-columns、grid-template-rows 与 grid-auto-flow。浏览器报告解析后的轨道尺寸，包括隐式轨道。这些读数本身无法区分显式与隐式轨道，示例中须说明边界并指出相关条目。网格线编号计算边界，因此三个显式轨道有四条线。

小数像素值会让注释过于复杂时，可在样式读数中添加 data-round-pixels。显示的像素长度会四舍五入至小数一位，完整计算值则保留在输出的 title 中，被测布局不变。画布已有属性读数时，请用空的 inspect 列表省略工具栏重复数值。

密集排列应使用会留下真实空隙的跨轨设置，以及后续足以填入空隙的小条目。通过原生控件显示源代码顺序的焦点。分数轨道若需要测量比例，应让可用空间明确。轨道最小值与内容溢出处理要分开，并说明有意的裁剪。具名区域示例必须同时编写区域映射与轨道尺寸；调整大小会改变真实 iframe 媒体查询。

#呈现约束与内容

尺寸组合示例会渲染完整的显示 HTML，包括包含块、首选尺寸、最小值、最大值与实际内容。父元素应与蓝色主体分开测量，让百分比有可见的参考。视口高度示例应使用有边界的 iframe；随内容增高的框架无法可靠演示自身高度单位。即使没有断点，流动外层容器也应启用视口宽度控件。

内在尺寸应使用真实文字，比例与适配示例则使用已知源尺寸的真实媒体。比较时保留相同内容与溢出策略。可滚动 overflow 值可能移除 Flex 自动最小值；教学需要单独呈现零最小值的效果时，请使用不可滚动的裁剪。最大值不代表会增长或裁剪，相同上下界也不保证正方形。

间距组合示例将标签与读数放在被测布局之外。中性子元素显示蓝色 padding 内的 content-box；outline 标明父元素，不增加 border。用既有尺寸与位置读数比较内容尺寸及物理内缩。需要 flow-root、Grid 或 Flex 时应明确编写；教学主题若是 margin 折叠，则保留正常折叠行为。使用真实 writing-mode 或方向变化显示 inline/block 行为。固定高度示例若有意显示可见溢出，请在外部读数前预留空间，且将空间放在被测方框之外。

#保留字体、字形与继承

排版组合示例呈现编写的文字、嵌套结构、行内方框与完整表格。显示 HTML 应保留字号、字重、行高、间距与对齐。共用外观只添加细致轮廓与色调，不改变这些属性。比较名称与计算读数应放在文字上下文之外，不要成为额外行内容或继承被测字距。

比较处理方式时，应使用相同文字与阅读宽度。计算后行高不是字形高度，字体家族列表也只是请求的候选序列。数字功能应以 data-size-readout 测量实际字形序列，并确认所选字体支持要求的替代字形。等宽数字比较应使用比例字体；默认等宽字体会掩盖变化。

data-font-status="Family name" 报告匹配 FontFaceSet 条目的 loaded、loading 或 unavailable 状态，不会从 font-family 推断成功、不会声称每个字符都使用该字体，也不会用本地字体取代托管资源。整份文档示例保留样式表链接，并将编写的 body classes 应用到实际 iframe body。

可选的平台属性若计算值为空，data-empty-value="Not exposed" 可提供清晰标签。空的 inspect 列表会停用属性检查，本身不会创建工具栏。

普通文字预览应随内容增长。流动字号公式即使没有媒体查询，也应启用真实视口控件。reset 示例保持嵌套，基线示例保持行内；block 占位物无法演示 vertical-align。平台专属渲染提示需要清晰的支持限制，不能以模拟像素效果代替。

#保留文字流与阅读路径

文字流组合示例使用相同字体表面与外部读数。显示 HTML 应保留 lang、dir、精确空白、嵌套书写上下文与完整溢出前提。不要用英文占位文字取代 CJK 或 RTL 内容，也不要将可见注释插入对空白敏感的示例。

比较时使用相同文字与约束。用真实 min-content 方框演示内在换行差异，有意溢出则使用自行编写、具名的滚动区域。原生 Range 几何属于验证用途，不可覆盖换行或以合成文字替代。

截断示例若隐藏了重要信息，就必须提供完整、可见的阅读路径。请使用具有描述性摘要的原生展开控件，重要指示保持可见，并验证键盘焦点与展开行为。只有工具提示并不足够。

教学属性应用到伪元素时，请在样式读数使用 data-style-pseudo="::first-letter"。相同测量组件会读取原生计算样式。提示被接受不代表渲染质量或性能已改善。

#隔离字形绘制

typeSpecimens(section, {  appearance: 'plain',  properties: ['text-decoration-line', 'text-decoration-style'],  measure: true,  caption: 'Compare the same words and font with two line styles.',})

透明文字需要明确编写可见的绘制来源，例如裁剪渐变或非零轮廓。打印可能省略背景时，应提供实色回退。plain 示例不会补上这些前提。可交互主体保留共用键盘焦点轮廓。

#保留列表与生成内容

完整渲染编写的列表、文章与后代元素。plain 文字表面不可自行添加计数器名称、重设值、标记、条目或伪元素。阅读标签应在文章或列表之外，属性则报告实际拥有它的元素。原生计数器前缀在计算样式中可能仍是未解析的 counter() 表达式；请检查实际渲染文字，不要用脚本数字替代。

重要链接名称与指示保留在 HTML 中。生成指示符补充原生锚点，也可能进入其无障碍名称。请测试实际伪元素，并保留键盘焦点。平台相关语法应显示浏览器真实支持分支，并清楚标明自行编写的回退。

<DemoExample page="counter-set" section="set-a-counter-on-one-item" /><DemoExample page="list-style-position" section="place-markers-inside-the-content-box" />

#保留背景绘制前提

可见 HTML 应编写图片来源、方框尺寸、位置、大小、重复行为与底色。plain 示例不会替主体添加图片、边框、padding、裁剪或混合模式。标签与计算读数放在绘制区域之外。

attachment 应提供真实溢出内容与固定高度的 iframe 视口。内层面板滚动与文档滚动分开测试，不要用变换图层替代。前景文字应位于自身不透明表面上，保持易读；平台相关的固定背景行为也要写入导出的正文。

组合示例链接到完整编写的示例，请复制其 HTML 与随附主题声明。渐变文字使用带支持检查的 text-fill 模式，让不支持的浏览器与打印保留实色前景。

#区分边缘绘制与布局

请明确提供 border 宽度、样式与颜色。比较相同方框尺寸，并说明 box-sizing 模型：border 占用布局空间，outline 与 shadow 则不会。讲解逻辑边缘时使用 writing-mode 比较。透明 border 保留已用宽度；普通方框上的 none 或 hidden 样式则不会。

plain 示例不会替主体添加 border、outline、radius 或 shadow。即时读数与标签应置于主体外。radius 本身不会裁剪后代内容；裁剪是示例一部分时，应另外显示 overflow 规则。

编写的主题声明应与示例一起编译。shadow 组合示例明确启用预览主题控件，让用户比较两种模式的实际 token 值。除非作者提供依主题变化的 token 或条件，原始绘制值都保留为字面值。

#保留源图与片段几何

表格示例需要相邻且具有语义的单元格，以及明确的单元格边框。只有计算后间距不足以证明空隙，因为合并边框表格会忽略它。图注与注释应放在被测接缝之外。

border-image 应使用可加载、已知尺寸且角落／边缘图案清晰的来源。请编写普通 border、切片、图片宽度与重复行为。源坐标与目标绘制必须区分；原生 width 与 outset 数字是倍数。向外绘制需要空间时，应预留实际布局空间。

行内片段示例应在明确尺寸容器内保留一个真实行内元素，提供文字、行高、padding 与装饰。让原生换行创建片段，并比较标准与前缀支持，不要将文字替换为分离方框。

#保留媒体尺寸与绘制上下文

图片示例应提供可加载、已知自然尺寸的来源，以及明确的 content-box。适配与定位需独立于注释。源图若包含明显圆形特征，就能区分拉伸与裁剪。

SVG 示例需要真实 paths、viewBox、视口尺寸与明确绘制前提。计算后 stroke-width 不代表经过 viewBox 变换后的最终粗细。non-scaling 效果应放在绘制形状上。原生控件为装饰图标提供状态与无障碍名称；主题比较保持几何不变。

#保留绘制上下文与交互

filter 示例需要可见的源图细节，并为布局方框外的绘制预留空间。使用透明图像，区分沿 alpha 轮廓的 drop-shadow 与矩形 box-shadow。backdrop 示例必须包含真实背景内容与前景面板，明确设置半透明并保持文字易读。

裁剪与遮罩几何应保留在编写的 HTML 中。clip 边界会改变指针命中测试，CSS 方框的 mask 则不会。注释与必要控件应放在可能将其隐藏的效果之外。淡出滚动区域需要真实溢出、原生无障碍名称、键盘焦点，以及持续可读的说明。

混合分组与完整背景应明确编写。只有示例需要有边界分组时才使用 isolation。整个元素的 opacity 也会让后代淡化，但不会禁用它们；只需淡化表面时，应与色彩 alpha 比较。测试原生控件行为，并在打印时恢复适当绘制。

#保留原生形状环绕

shape 示例需要真实 float、明确尺寸与相邻行内内容。标签与测量应放在该格式化上下文之外。绘制形状另外编写：shape-outside 改变环绕，不会裁剪或调整图像大小。margin 可能移动形状坐标时，应指出参考方框。

shape-margin 会在 float 的 margin-box 内扩大环绕轮廓。较大轮廓需要空间时，请预留普通 margin。图片阈值应使用已加载且已知 alpha 值的来源，比较时保持相同绘制外观。渐变与同源透明图片可清晰呈现阈值行为，不必以定位文字替代。

#保留变换几何与提示

原始布局位置与枢轴参考线应放在变换元素之外。hover、focus 与 pressed 状态使用真实原生控件。client 边界与布局尺寸分开报告：getBoundingClientRect 包括变换，SVG stroke 也可能画到其报告矩形之外。

SVG 示例需要明确 viewBox、源坐标与参考方框差异。3D 场景应一起编写 perspective、变换父元素与平移子元素。不要只为装饰就在父元素添加 opacity、filter、isolation 或裁剪；分组效果可能使后代平面化。除了计算属性，也要比较实际深度几何。

will-change 示例呈现声明的提示与其存续时间。控件保持可见，适当时在示例变化前准备提示，之后再解除。计算后提示不能证明性能提升。定时交互遵循动态效果偏好，其原生状态在没有插值时仍可检查。

#保留原生过渡时间轴

比较时明确保留距离与端点。使用真实 CSS transitions，包括等待间隔与各状态 easing。减少动态效果时，同时控制 duration 与 delay；打印保留即时状态，偏好变更时则让原生过渡完成。播放控件只应暂停明确选择加入的示例。

#保留原生动画阶段

讲解 fill 时，应区分普通值、起始 keyframe 与结束 keyframe。明确声明 duration、delay 与 count；比较时序或方向时使用相同路径。保留完整 SVG，状态文字保持静止。

播放控件操作浏览器真实的 CSS Animation 对象。已完成的单次时间轴应保留以供重播，默认暂停，手动 Play 视为明确的动态预览。CSS play-state 示例则自行拥有原生 checkbox 与 focus 选择器，工具栏不可覆盖正在讲解的属性。运行规则同时需要 screen 媒体与动态效果偏好。

时间轴读数报告已经过的时间与原生进度；属性读数仍报告编写的 CSS 值。keyframe 层级 easing 可能在特定区间覆盖元素 easing。两种读数都不是性能测量。

#保留原生输入与无障碍

显示 HTML 应保留完整原生控件、选项、标签与说明。appearance、accent、caret 和 cursor 只改变呈现，不提供激活或禁用行为。使用真实 checkbox、展开区域或表单动作，让结果可观察。独立比较示例会将 ID 连同 for、ARIA 与本地链接引用一起设置作用范围，让名称与说明保持连接。

指针命中测试与键盘访问是不同机制。保留真实覆盖几何与继承的子元素规则，同时测试指针输入与键盘激活。观察原生调整手柄与文字选择手势，不要设置尺寸或选择范围来制造预期结果。

touch-action 必须使用触控输入测试；鼠标拖动无法重现手势协调。保留具名滚动区域与键盘访问，并说明 resize 与厂商拖动行为的平台限制。原生拖动读数只观察 dragstart 与 dragend，不会将元素设为可拖动，也不会取消事件。依赖厂商属性的每个示例，都需要明确支持说明，并在可行时提供可移植替代方案。

#保持示例可移植

DemoExample 将 utility 页面与章节连接到编写的 HTML、CSS 片段。显示结构本身应具备重现行为所需的所有前提，共用组合示例只提供外观、注释与控件。Rust 渲染器编译实际 utility classes。完整教学说明与框架中立示例应放在示例旁，让 Markdown 与搜索导出仍有用。较长 HTML class 属性应在完整 utilities 之间换行，让教学属性在文档栏中清晰可读；不可将单一 class 拆成多行。

<DemoExample  page="clear"  section="clearing-both-left-and-right-floats"/>

#使用项目 CSS 的示例

预览需要项目 tokens 或受管理 classes 时，请使用 DemoConfiguredExample。同一份项目 CSS 与字面值 HTML 同时提供实际 iframe、可见代码与完整生成 CSS。每个预览拥有自己的样式表，不能改变周围文档的主题、组件 classes 或层叠。

<ProjectStyleExample name="tokens" /><ProjectStyleExample name="modes" /><ProjectStyleExample name="components" /><ProjectStyleExample name="layers" />

新教学应提供真实项目 CSS 与完整 HTML：

<DemoConfiguredExample name="project-spacing" title="A project spacing token"  source="@theme { --spacing-card: 1.5rem;  }"  html={'<article class="p-card">Collection details</article>'}  caption="p-card references --spacing-card." />

theme 添加真实文档 class 切换；讲解该行为时，请在项目 CSS 的 @theme 之外定义明确的 .light、.dark 选择器。默认没有控件。code={false} 用于通过使用链接前往完整源代码的展示集示例。这些是服务器组件，只有既有 iframe 控件需要 hydration。请使用可信任、由网站编写且具有字面值 classes 的 HTML。普通文档流适合内容尺寸预览；有界滚动、固定定位或视口几何则直接使用 DemoViewport。

shadow 将 HTML 与生成 utility 规则放进真实的 open shadow root。基础变量从 iframe 文档继承。此变体只预览样式，不会加载框架或测试 runtime 生命周期。图注应保留这项区分，链接的教学则记录 runtime 设置。

<button type="button" class="px-md py-sm r-sm bg-blue fg-white">Hello Lit</button>

@layer theme {  :root,  :host {    --color-blue-60: oklch(51.83% .2687 266.1)  }  :root,  :host {    --color-blue: var(--color-blue-60)  }  :root,  :host {    --color-white: oklch(100% 0 none)  }  :root,  :host {    --radius-sm: .25rem;    --spacing-sm: .75rem;    --spacing-md: 1rem  }}@layer utilities {  .bg-blue {    background-color: var(--color-blue)  }  .r-sm {    border-radius: var(--radius-sm)  }  .fg-white {    color: var(--color-white)  }  .py-sm {    padding-block: var(--spacing-sm)  }  .px-md {    padding-inline: var(--spacing-md)  }}

<DemoConfiguredExample name="shadow-button" title="Shadow-root styling"  source="" html={'<button class="px-md py-sm bg-blue fg-white">Hello</button>'}  caption="Generated CSS inside a shadow root." shadow />

用于 Lit 安装。相同默认预览也支持 React 与 Vue 的渲染标记。

正式规则需要代码但不需要实时预览时，ConfiguredExample 提供与预览相同的原生属性支持，并包含完整生成 CSS。

#可用组合示例

请打开符合教学内容的集合。每份集合都保留完整源代码与真实浏览器行为。