ドキュメントパターン

安定したアンカーと読みやすい値が必要な参照情報には 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 はページ内で重複させず、既存の第3レベル見出しの下に置く項目には headingLevel={4} を使います。値は選択可能なテキストのままです。視覚的な見本を伴うトークンの役割には DemoTokenTable、完全なソース例には既存のコードレンダラーを使います。どちらも静的な文書コンポーネントであり、測定するデモレイアウト外に置きます。

#名前空間の利用先

DocumentNamespaceTable は名前空間と、すべての公開された利用先を対応付けます。長い行は最初の6キーを表示し、残りはマウス、タッチ、Enter、Space でネイティブの開閉領域を開いて表示します。すべてのキーは HTML と可搬 Markdown に残ります。サーバーコンポーネントなのでクライアント状態は不要で、教材の測定領域外に置きます。

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

DocumentKeyList は既定ですべてのキーを表示します。長い一覧が読みの流れを妨げる場合は previewCount を設定し、重要な指示は開閉領域の外に残します。完全な名前空間レジストリを参照してください。

#ユーティリティ名前空間テーブル

NamespaceUtilityTable はトークン名前空間と、それを受け取るユーティリティキーを結び付けます。グループに説明がある場合は、元の Guide と同じく「グループ」「ユーティリティキー」「説明」を別の列に保ちます。共通スタイルは控えめな区切りと一定の読みやすいリズムを使います。狭い画面では表専用のキーボードでフォーカス可能な領域内だけがスクロールし、ページ幅は変わりません。

完全なユーティリティテーブルの見本を参照してください。

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

読者向けのグループ名と manifest 由来のキーを指定します。namespace または namespaces は未対応のキーを除外します。説明がなければ2列の表になります。これは文書を読むための補助であり、測定対象のデモレイアウト外に置きます。色、余白、タイポグラフィでの実際の使用例と、ユーティリティテーブルのレビューを参照してください。

#数値トークンテーブル

ThemeNumberVariableTable はプリセットから数値トークンと単位を読み取ります。spacing 表示はハッチングした面と浮いたオブジェクトで実際の間隔を示します。表には位置の安定したトークン列と値の列、控えめな行区切りがあり、狭い画面ではキーボードでフォーカスできる領域内でスクロールします。

完全な余白テーブルの見本を参照してください。

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

representation は省略できます。ブレークポイントとコンテナーは、間隔の見本を使わず、説明付きで同じデータ駆動の表を使います。トークンの元の値と参照単位をテキストで示し、この一覧は測定用レイアウトのデモの外に置きます。数値テーブルのレビューで現在の共通テーブルを確認できます。

#ファイル構成

Monorepo Guide と同じく、ファイルとディレクトリの構成には ExplorerView を使います。ネイティブの入れ子リストで階層を保ち、フォルダーやファイル種別のアイコンは装飾とします。説明は周囲の本文に書きます。

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

読み取り専用のリストなので、項目にはタブ移動先、展開状態、ツリーウィジェットのキー操作はありません。ファイルの内容やコマンドには通常のコードブロックを使い、ディレクトリツリーには使いません。

プレーンテキストのツリーをエクスポートするときも同じ 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 を分離した2つのブラウザードキュメントへ配置します。一方はブラウザーの標準スタイルを使い、もう一方には指定した 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" を渡すと、ネイティブのマージンも含めて各フレームが内容に合わせて伸縮します。fixed、sticky、ビューポートに依存する配置では標準の viewport サイジングを保ちます。比較グリッドは各 iframe 外のレイアウトを担当し、未装飾のドキュメントにはデモのリセットやオブジェクトスタイルを適用しません。サイトが記述したマークアップだけを渡してください。初回描画のスタイルを参照してください。

#ドキュメントのフロー

DocumentFlow は実際のテキストとネイティブのリスト構造で、短い順序付きのプロセスを示します。番号付きステージは広い画面では本文の列に並び、余地がなければ縦積みになります。静的な説明であり、配置は時間や進行中の段階を意味しません。

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

簡潔な段階を2〜4個にまとめます。任意のキャプションで共通の制約を下に示せます。コンポーネント自体がグリッド、余白、枠線を持つため、測定対象のレイアウト外に置きます。操作部品、フォーカス移動先、アニメーションは追加しません。

DeliveryFlow はランタイムとハイドレーション、ソーススキャン、ネイティブCSSの pruning、ルートのスタイルに、共通でエクスポート可能なレシピを提供します。順序付きのテキストは検索と Markdown に含まれます。

#ドキュメントの選択肢

本文の列内に関連する少数の移動先を示すには DocumentChoices を使います。各リンクにタイトル、短い説明、任意の装飾アイコンを付けます。行は十分なクリック領域、見えるキーボードフォーカス、ネイティブなナビゲーション構造を備えます。行全体を1つのリンクとし、内部に操作部品を入れないでください。

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

MigrationGuides のような製品アダプターは、独自の画像と項目を共通ナビゲーション部品へ渡します。カテゴリやアルファベット順のナビゲーションが必要な大きなカタログには DocumentationIndex を使います。これらは教材のレイアウト外に配置します。

#本文内の比較

文書の列内で文章や class 構文を比較するときは、2列の Markdown 表を DocumentComparison で包みます。狭い画面でも両列を表示し、長い構文は折り返します。複数段落が必要な判断にはリストを、書式を保つ必要のあるソースにはコードブロックを使います。この静的ラッパーはネイティブの表見出しを保ちます。単独の表と同じ外側の余白とレスポンシブな張り出しを管理し、内側の表はさらに張り出しません。figure やトレイ内では、その面の枠内に収めます。

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

トークンファミリーの対応とレンダリングの選択を参照してください。

#構文の対応

短い構文トークンとネイティブ CSS の対応には DocumentCodeTable を使います。行見出しはトークンを途中で分割せず、CSS は自然な空白位置で折り返します。長い生成ルールはコードブロックに置きます。この表は静的な読み取り補助であり、デモの測定領域外に配置します。

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

最初の列の既定ラベルは「Syntax」です。条件の Referenceは名前付きバリアントと任意のクエリーの両方にこの形式を使います。可搬 Markdown は元の2列表とすべての値を保ちます。