デザインシステムの記述

完全な例、ソース、操作部品は一緒に置きます。共通 UI が周囲の表示を提供し、例自体が CSS のすべての前提と測定する関係を持ちます。

マーク、金色、書体、言葉づかいはブランドガイドを参照します。このハンドブックはコンポーネントのインターフェースと例の構築を扱います。

#共通コンポーネントを読み込む

Astro と MDX では、明示的な @master/internal-site/demo/*.astro または *.svelte サブパスから基本部品を import します。Astro が静的な構造を描画し、Svelte アイランドが測定、再生、ビューポートの操作を追加します。CSS を伴う例はサーバー上の公開コンパイラーを使い、完全なソースと生成結果を残します。

Demo

インターフェース： title, description, caption, controls, source, background, padding, align, frame

1つの例は1つの ui-tray です。ヘッダー（title、description、controls）、ui-stage、source（コードウィンドウと閉じた DemoGeneratedCSS）、キャプションで構成します。class と style はステージに、frameClassName はトレイに適用します。DemoViewport のブラウザーや比較など、内容自体に枠がある場合は frame="none" を使います。

子要素が独自に余白を持つ場合は padding="none" を使います。ステージは対象を中央に置き、align="start" で始端へ寄せます。枠のために測定対象へレイアウト、包含、クリッピング、寸法を追加してはいけません。

DemoSurface

インターフェース： elevation="flat" | "raised", ネイティブ div props

角丸10pxの ui-sheet です。暗黙のレイアウト、余白、クリッピングはありません。明示した角丸ユーティリティで上書きでき、raised は rise-1 の高低差を使います。

DemoItem

インターフェース： tone, variant, ネイティブ div props

最小サイズ3remの ui-item タイルです。ユーティリティで形状とレイアウトを設定します。既定の色調は neutral で、blue、violet、amber、green、red は明示的な教材の役割です。必ず凡例かラベルで名付けます。

DemoComparison

インターフェース： label と children を持つ items、ネイティブ div props

ui-compare は条件ごとにキャプション付きステージを1つ置き、幅に余裕があれば横に並べます。

DemoMedia, DemoSwatch

インターフェース： Media は任意の tone を持つ SVG props、または src と alt を受け取ります。スウォッチは label が必須で、value は省略できます。

再利用できる SVG アートワークと名前付きの色見本です。見本の文字はプリセットのユーティリティを直接使います。

DemoLabel, DemoLegend

インターフェース： テキスト。凡例は label と tone を持つ items。

注釈は対象に添え、対象のレイアウトには加えません。

DemoMeasure

インターフェース： label, children

ResizeObserver で内容のラッパーを測定し、独立した表示部に幅と高さを更新します。示している親要素の外に置いてください。

DemoAxes

インターフェース： inline, block, children

例の周囲に、右向きの水平軸と下向きの垂直軸のラベルを付けます。独自の名前は、その物理方向が場面と一致する場合だけ使います。

DemoControls

インターフェース： label, variant="plain" | "segmented", children

名前付きのネイティブ操作部品のグループです。segmented はボタンに aria-pressed を持つ ui-segmented トラックを描画します。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

信頼できる1つの見本を、独立した配色と内容に応じた寸法を持つ2つの文書へコンパイルします。

DemoPalette

インターフェース： 任意の families

固定されたプリセット色の一覧と、ネイティブのクリップボード操作です。

DemoCopyButton

インターフェース： value, label, 任意の feedback="value" | "compact", ネイティブ button props

処理中のリクエスト、続いて実際のクリップボード結果を通知し、キーボードフォーカスを保ちます。既定の通知には値を含めます。値が操作部品の隣にすでに見えている場合は compact を使い、短い状態表示の場所を確保します。

DemoTokenTable

インターフェース： rows, 任意の descriptionTitle

2列の文書用一覧です。長いトークンは表の内部でスクロールします。

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 でネイティブに保ちます。独自の山形アイコンは描きますが、ブラウザーの選択 UI やキー操作は置き換えません。選択肢のラベルは簡潔にし、文字サイズ200%でも全文が見えることを確認します。

両モードでアイコンと範囲入力のハンドルを実際の表示サイズで確認します。小さなハンドルは、トラックに対して見えるよう、大きなパネルより強い輪郭が必要です。非対称のアイコンを視覚的に中央へ寄せる場合は、固定した領域内の字形だけを調整します。無効な操作部品は選択位置を保ちますが、アクティブな文字色と接地の影を外します。

クライアントコンポーネントでは、レイアウトと描画される操作部品の間にアイランドのホストが入ることがあります。その境界をまたぐ直接の子関係に頼らず、コンポーネントの 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で、プリセットの1280pxの lg に届きます。幅に合わせた狭いビューポートは240px未満にもなり、スライダーは実際の幅を示します。より広い境界が必要なら maxWidth を設定します。信頼できるサイト記述の文書だけを渡してください。iframe はレイアウトを分離しますが、安全性の境界ではありません。initialTheme="light" または "dark" で初期配色を固定し、省略すると周囲のページに従います。操作部品はプレビューの準備後に使えます。コンパイルされるユーティリティ例には Reference のレシピを使います。

#名前付きビューポート幅

responsive と widthPresets を組み合わせ、範囲調整の隣に意味のある境界を示します。最初のプリセットが 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）に置き、重複しない説明的な名前を付けます。広いフレームはキャンバス内でスクロールします。メディアクエリーをまねるために対象を縮小したりスタイルを書き換えたりしないでください。構文チュートリアルは、余白と条件付きホバーにプリセットの sm 境界を使います。

#実際の動作を保つ

ラベルを中央に置くためだけに、対象へレイアウト、containment、変形、クリッピングを加えないでください。教材の動作が変わることがあります。操作部品はシーンの外に置き、ビューポートに依存する例には iframe を使います。

#教材に合わせてキャンバスを設定する

小さな画面で縦に並ぶ通常フローの比較には sizing="content" を使います。画像の読み込みや文字の折り返しによる自然な文書高にフレームが従うため、読者は2つ目の縦スクロール領域なしですべての見本を見られます。

固定配置、スクロール、ビューポート単位、高さによる条件では、既定の sizing="viewport" を保ちます。このモードでは height が実際のビューポートを定義します。例の高さが iframe 自身の高さに依存する場合、content サイジングは使えません。

<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() を呼びます。nearest-container オプションを無視するブラウザーでも、周囲の文書のスクロール位置を保ちます。スナップ停止には data-scroll-by="container-id" と data-scroll-distance="600" を使います。相対移動は途中のスナップ位置で止まれますが、終点への直接移動は通り過ぎることがあります。相対的なスナップ停止要求は即時に実行して行き先を比較しやすくします。スムーズスクロールのレシピは動きを抑えるシステム設定に従います。

#レイアウトの外で flex の寸法を測る

Flex のレシピは、表示した完全な HTML に親、項目、basis、gap、制約を持たせます。装飾の輪郭は余白、最小寸法、flex の動作を追加しません。軸ラベルと測定値は検証するコンテナーの外に置き、余分な flex 項目にしないでください。

信頼できる iframe 見本では data-size-readout="element-id" が実際の border-box 寸法を小数1桁で示します。ResizeObserver は、フォント読み込み後に変わる固有寸法も含めて各対象を追跡します。data-layout-axis="container-id" は算出された主軸を inline または block として示し、該当すれば反転も示します。レスポンシブ iframe は実際のメディアクエリー条件を変更します。

初期 basis と最終寸法を区別します。grow の係数は正の余白を分配し、shrink の係数は内側の flex basis で重み付けします。単純な外寸比が必要な教材では、測定する項目の内側に余白付きラベルを入れます。方向や順序の例では tabindex="0" のネイティブボタンでソース順のフォーカスを示し、独自のキー処理や正の tab index を使いません。

#揃えと分配を区別する

揃えのレシピは flex 寸法の例と同じレイアウトの描画を使います。表示する HTML に完全な親、トラック、項目、gap、自動寸法の制約を記述します。共通の装飾は輪郭と色調だけを追加し、これらの前提を補いません。比較ごとに名前を付け、ラベルと測定値は検証コンテナーの外に置きます。

data-alignment-axis="container-id" に data-axis-kind="main"、"cross"、"both" を組み合わせ、算出済みレイアウトの論理軸を示します。Grid では main は inline、cross は block に対応し、Flexbox では現在の flex direction に従います。data-style-readout="element-id" と data-style-property="property-name" は、解決済みの grid 列も含むネイティブの算出値を示します。

data-position-readout="item-id" と data-position-origin="container-id" は、コンテナー内側の左上から対象の border-box までのオフセットを示します。これは見えている物理オフセットであり、grid-area の原点や未スクロールの内容座標ではありません。負の値で unsafe な揃えや実際のスクロールを見せられます。寸法と組み合わせ、どの要素やトラックを揃えるか説明します。

伸長は、自動寸法の項目と明示寸法の兄弟要素を並べて示します。safe な揃えは収まる内容と実際に溢れる内容を比べ、スクロールポートにフォーカスとアクセシブルな名前を与えます。ネイティブのオーバーフローを保ち、どの端へ移動できるか読者が確認できるようにします。

#grid のトラックと配置を示す

Grid のレシピは、記述した親と子を完全に描画します。その HTML に明示的トラック、暗黙の寸法、フロー、gap、項目配置を定義します。共通の枠は装飾と外部の測定値を加えるだけで、トラックを作ったり、不足する項目を補ったり、不完全な親に Grid を設定したりしてはいけません。

既存の寸法・位置表示に加え、data-style-readout で grid-template-columns、grid-template-rows、grid-auto-flow を示します。ブラウザーは暗黙のトラックも含む解決済み寸法を返します。値だけでは明示・暗黙の区別は付かないので、例の中で境界と対象項目を説明します。線番号は境界を数えるため、明示的な3トラックには4本の線があります。

小数のピクセル値で注釈が読みにくい場合は、スタイル表示に data-round-pixels を加えます。表示する長さを小数1桁に丸め、output の title に完全な算出値を残します。測定レイアウトは変わりません。キャンバス内にすでにプロパティの値がある場合は、空の inspect リストでツールバーの重複表示を省きます。

dense 配置には、実際の穴を残す span と、後からその穴に入る小さな項目を使います。ネイティブ操作部品でソース順のフォーカスを示します。割合トラックで実測比が必要なら、利用可能な空間を確定させます。トラックの最小値と内容の overflow 処理は分け、意図した切り抜きは説明します。名前付き領域では領域マップとトラック寸法の両方を記述し、リサイズで実際の iframe のメディアクエリーを変化させます。

#制約と内容を示す

寸法のレシピは、包含ブロック、希望寸法、最小・最大寸法、実際の内容を含む完全な表示 HTML を描画します。パーセントの参照先が分かるよう、青い対象と親を別に測ります。ビューポート高の例には高さを限定した iframe を使います。内容に合わせて伸びるフレームでは、自身の高さ単位を確実に示せません。ブレークポイントがなくても、流動的なラッパーにはビューポート幅操作を有効にします。

固有寸法には実際の文章を、比率と fitting の例には元の寸法が分かる実際のメディアを使います。比較では内容と overflow 方針をそろえます。スクロール可能な overflow 値は Flex の自動最小寸法を取り除くことがあるため、最小値ゼロの効果だけを示すならスクロールしないクリッピングを使います。最大値は伸長や切り抜きを意味せず、上下限をそろえても正方形とは限りません。

余白のレシピはラベルと値を検証レイアウト外に保ちます。ニュートラルな子要素で青い padding 内の content-box を示し、親はボーダーを加えない outline で示します。既存の寸法・位置表示で内容寸法と物理的な内側距離を比較します。必要な flow-root、Grid、Flex は明示し、margin の相殺が教材なら通常の相殺を残します。実際の writing-mode や direction の変更で inline/block の動作を示します。固定高の見本で意図的に可視 overflow を示す場合は、外部表示の前に余白を確保し、測定ボックスの外に置きます。

#書体、字形、継承を保つ

タイポグラフィのレシピは、記述した文字、入れ子、インラインボックス、完全な表を描画します。表示 HTML に文字サイズ、太さ、行高、字間、揃えを残します。共通の装飾は、これらを変更せず控えめな輪郭と色調を足すだけです。比較名と算出値は文字のコンテキスト外に置き、行の内容を増やしたり検証中の字間を継承したりしません。

処理を比較するときは文章と読書幅をそろえます。算出 line-height は字形の高さではなく、font-family の一覧も要求した候補でしかありません。数字の機能では data-size-readout で実際の字形列を測り、選択書体が指定の字形を持つことを確認します。等幅数字の比較にはプロポーショナル書体を使います。既定が等幅書体だと変化が隠れるためです。

data-font-status="Family name" は、該当する FontFaceSet 項目を loaded、loading、unavailable として示します。font-family だけで成功を推測したり、全文字がその書体で描画されたと主張したり、ホストされたリソースをローカル書体で置き換えたりしません。文書全体の見本はスタイルシートリンクを保ち、記述した body class を実際の iframe body に適用します。

任意のプラットフォームプロパティでは、算出値が空のときに data-empty-value="Not exposed" で明確なラベルを示せます。空の inspect リストはプロパティ検査を省き、それ自体ではツールバーを作りません。

通常の文章プレビューは内容に合わせて伸ばします。流動的な文字サイズの式には、メディアクエリーがなくても実際のビューポート操作を有効にします。reset の例は入れ子に、ベースラインの例はインラインに保ちます。block の代用品では vertical-align を示せません。プラットフォーム固有の描画ヒントには、ピクセル効果の模擬ではなく、見える対応制約を付けます。

#文字のフローと読む経路を保つ

文字フローのレシピは同じ書体サーフェスと外部表示を使います。表示 HTML に lang、dir、正確な空白、入れ子の書字コンテキスト、overflow の完全な前提を残します。CJK や RTL の内容を英語の代用品に置き換えたり、空白に敏感な見本へ見える注釈を入れたりしないでください。

同じ文章と制約で比較します。固有の折り返しの差は実際の min-content ボックスで示し、意図した overflow には名前付きのスクロール領域を記述します。ネイティブ Range の形状は検証に使い、改行を上書きしたり合成文字へ置き換えたりしてはいけません。

隠れた情報が重要な省略の例では、全文へ至る見える経路が必要です。説明的な summary を持つネイティブの開閉操作を使い、必須の指示は見えるままにして、キーボードのフォーカスと展開を検証します。ツールチップだけでは不十分です。

教材のプロパティが疑似要素に適用される場合は、スタイル表示に 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、クリッピング、blend-mode を追加しません。ラベルと算出値は描画領域外に置きます。

attachment には実際に溢れる内容と固定高の iframe ビューポートを用意します。内側のパネルと文書のスクロールを個別に検証し、変形したレイヤーで置き換えません。前景の文字は独立した不透明の面で読みやすくし、固定背景のプラットフォーム依存の動作をエクスポートする本文でも説明します。

レシピは完全に記述した例へリンクします。HTML と付随するテーマ宣言をコピーしてください。グラデーション文字には対応判定付き text-fill パターンを使い、未対応ブラウザーと印刷では単色の前景を残します。

#端の描画とレイアウトを分ける

border の幅、スタイル、色を明示します。同じボックス寸法を比較し、box-sizing のモデルを示します。border はレイアウト上の場所を取り、outline と shadow は取りません。論理辺は writing-mode を比較して教えます。透明な border は使用幅を保ちますが、通常のボックスで none や hidden のスタイルは保ちません。

plain の見本は対象へ border、outline、radius、shadow を追加しません。リアルタイムの値とラベルは対象外に置きます。radius だけで子孫の内容は切り抜かれません。切り抜きが例の一部なら、別途 overflow のルールを示します。

記述したテーマ宣言は例と一緒にコンパイルします。shadow のレシピは配色操作を明示的に有効にし、両モードの実際のトークン値を比較できます。テーマ依存のトークンや条件を指定しない限り、生の描画値はリテラルのままです。

#元画像と断片の形状を保つ

表の見本には意味構造を持つ隣接セルと明示的なセルのボーダーが必要です。border-collapse の表では無視されるので、算出された spacing だけで隙間を証明できません。キャプションと注釈は測定する継ぎ目の外に置きます。

border-image には、寸法が分かり、角と辺の模様が見える読み込み可能な画像を使います。通常の border、slice、画像幅、repeat を記述します。元の座標と出力の描画を区別してください。ネイティブの width と outset の数値は倍率です。外へ描画する領域には実際のレイアウト空間を確保します。

インライン断片の見本は、明示寸法のコンテナー内に1つの実際のインライン要素を保ちます。文字、行高、padding、装飾を指定し、ネイティブの折り返しで断片を作ります。文字を別々のボックスへ置換せず、標準・接頭辞付きの対応を比較します。

#メディアの寸法と描画コンテキストを保つ

画像の見本には、自然寸法が分かる読み込み可能なソースと、明示的な content-box を用意します。fitting と position は注釈から分離します。明らかに丸い特徴を持つ画像なら、引き伸ばしと切り取りの違いが分かります。

SVG の見本には実際の path、viewBox、ビューポート寸法、明示的な描画の前提が必要です。算出 stroke-width は viewBox 変換後の最終的な太さを示しません。non-scaling 効果は描く形状に設定します。ネイティブ操作部品で装飾アイコンの状態とアクセシブル名を提供し、配色比較でも形状は一定に保ちます。

#描画コンテキストと操作を保つ

filter の例には、見えるソースの細部とレイアウトボックス外の描画領域を用意します。透明な画像で、アルファ形状に従う drop-shadow と矩形の box-shadow を区別します。backdrop の例には実際の背景内容と前景パネルを含め、半透明と読みやすい文字を明示します。

クリッピングとマスクの形状は記述する HTML に残します。clip の境界はポインターのヒットテストを変えますが、CSS ボックスの mask は変えません。注釈と必須の操作は、隠す可能性のある効果の外へ置きます。フェードするスクロール領域には実際の overflow、ネイティブのアクセシブル名、キーボードフォーカス、読み続けられる説明が必要です。

ブレンドするグループと完全な背景を明示的に記述します。isolation は範囲を限定するグループが必要な例だけに使います。要素全体の opacity は子孫も薄くしますが操作は無効にしません。面だけを薄くしたいなら色の alpha と比較します。ネイティブ操作部品の動作を検証し、印刷では適切な描画へ戻します。

#ネイティブの図形回り込みを保つ

shape の見本には実際の float、明示寸法、隣接するインライン内容が必要です。ラベルと測定値はその整形コンテキスト外に置きます。描く形状は別途記述します。shape-outside は回り込みを変えますが、画像を切り抜いたりリサイズしたりしません。margin で座標がずれる場合は参照ボックスを明記します。

shape-margin は float の margin-box 内で回り込みの輪郭を広げます。より大きな輪郭には通常の margin で空間を確保します。画像のしきい値は、アルファ値が分かる読み込み済みのソースを使い、比較間で見た目を変えません。グラデーションや透明な同一オリジン画像なら、文字を位置指定で置き換えずにしきい値の動作を示せます。

#変形の形状とヒントを保つ

元のレイアウト領域と回転中心のガイドは、変形する要素の外に置きます。hover、focus、pressed は実際のネイティブ操作部品で示します。client の境界とレイアウト寸法は別々に報告します。getBoundingClientRect は変形を含み、SVG の stroke はその矩形外にも描かれることがあります。

SVG の例には明示的な viewBox、元の座標、参照ボックスの違いが必要です。3D では perspective、変形する親、移動する子を一緒に記述します。装飾のためだけに親へ opacity、filter、isolation、クリッピングを加えないでください。グループ化する効果は子孫を平面化することがあります。算出値だけでなく実際の奥行きも比較します。

will-change の見本は、宣言したヒントとその有効期間を示します。操作部品を見えるままにし、適切な場合は示す変化の前にヒントを準備し、後で解除します。算出されたヒントは性能向上を証明しません。時間を伴う操作は動きの設定に従い、補間なしでもネイティブ状態を検査できるようにします。

#ネイティブのトランジション時間軸を保つ

比較では距離と終点を明示します。待ち時間と状態別 easing も含めて、実際の CSS transition を使います。動きを抑える設定では duration と delay の両方を制御し、印刷は即時の状態を保ち、設定変更時もネイティブの transition を終了させます。再生操作で停止するのは、明示的に対象となったデモだけです。

#ネイティブアニメーションの段階を保つ

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 とベンダー固有 drag のプラットフォーム制約を説明します。ネイティブ drag の表示は dragstart と dragend を観察するだけで、要素をドラッグ可能にしたりイベントをキャンセルしたりしません。ベンダー固有プロパティに依存する例には、明示的な対応注意と、可能なら可搬の代替を付けます。

#例を持ち出せる状態に保つ

DemoExample はユーティリティのページとセクションを、記述した HTML と CSS スニペットに結び付けます。表示する構造自体に再現に必要なすべての前提を持たせ、共通レシピは装飾、注釈、操作を提供します。Rust レンダラーが実際のユーティリティ class をコンパイルします。完全な説明とフレームワークに依存しない例をデモの隣に置き、Markdown と検索も役立つものにします。長い HTML class 属性は完全なユーティリティ間で改行し、教材のプロパティを本文幅で読めるようにします。1つの class の途中で改行してはいけません。

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

#プロジェクト CSS を使う例

プレビューにプロジェクトトークンや管理する class が必要なら DemoConfiguredExample を使います。同じプロジェクト CSS とリテラル HTML を、実際の iframe、表示コード、完全な生成 CSS に使います。各プレビューは独自のスタイルシートを持ち、周囲の文書のテーマ、コンポーネント class、カスケードを変えられません。

<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 は実際の document class の切り替えを加えます。その動作を教える場合はプロジェクト CSS の @theme 外に明示的な .light、.dark セレクターを定義します。既定では操作部品はありません。code={false} は、完全なソースへの使用例リンクを持つギャラリー見本向けです。これらはサーバーコンポーネントで、既存 iframe の操作部品だけがハイドレーションされます。リテラルの class を持つ信頼できるサイト記述の HTML を使います。通常の文書フローには内容寸法のプレビューを使い、限定したスクロール、fixed 配置、ビューポート形状には DemoViewport を直接使います。

shadow は HTML と生成ユーティリティルールを、実際の 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 を含みます。

#動作するレシピ

教材に合うコレクションを開きます。各コレクションは完全なソースと実際のブラウザー動作を保ちます。