文件呈現模式

參考資料需要穩定錨點與清楚易讀的值時，請使用 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 保留原始雙欄表格與所有值。