設計系統撰寫

完整範例、原始碼與控制項應放在一起。共用 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。

#可用組合範例

請開啟符合教學內容的集合。每份集合都保留完整來源與真實瀏覽器行為。