Material3Provider

Material3Providerは完全なMaterialテーマのスコープを作り、入れ子にもできます。テーマデータと解決済みのカラーモードを管理しますが、ドキュメントルートを変更したり、実行時にスタイルシートを注入したりしません。

import {
  Material3Provider,
  useResolvedColorMode,
} from '@language-lit/material3-expressive'
import '@language-lit/material3-expressive/styles.css'

function ModeLabel() {
  const mode = useResolvedColorMode()
  return <output>Resolved mode: {mode}</output>
}

export function App() {
  return (
    <Material3Provider colorMode="system">
      <ModeLabel />
    </Material3Provider>
  )
}

構造、バリアント、状態

• プロバイダーはchildrenを囲む.m3e-themeのdivをレンダーします。標準のdiv属性、className、style、ID、data属性、ARIA属性はこのルート要素に渡されます。
• themeの既定値は変更不可の完全なdefaultThemeです。カスタムテーマは公開テーマAPIで作成または解析してください。
• colorModeにはlight、dark、systemを指定できます。既定値はsystemです。ルート要素は設定されたモードと解決済みモードを安定したdata属性で公開します。
• systemModeFallbackはサーバーとハイドレーションで使う決定的なスナップショットで、既定値はlightです。
• preventColorSchemeFlashを指定すると、スコープ付きの初期化スクリプトを出力できます。nonceはこのスクリプトにCSP nonceを渡します。スクリプトがなくても静的CSSがシステムのカラースキームを選びます。
• 入れ子のプロバイダーは完全に独立したスコープを開始してから、独自のテーマ差分を適用します。

アクセシビリティ

プロバイダーはウィジェットロール、フォーカス動作、キーボード操作を追加しません。ラッパーは受動的なdivです。内部のセマンティックなランドマークは利用側で適切に指定してください。カラースキームは文書化されたロール間コントラスト要件に照らして検証されます。強制カラーとモーション低減への対応は各コンポーネントが担います。

プロバイダーのラッパーを隠す目的でroleを追加しないでください。ラッパーがレイアウトに関係する場合は、子要素の意味を変えずに通常のclassNameまたはstyleを使います。

トークン

完全なスタイルシートは既定の--m3e-ref-*、--m3e-sys-*、--m3e-comp-*カスタムプロパティを.m3e-themeに割り当てます。カスタムプロバイダーは検証済みの差分だけをインラインカスタムプロパティとして設定します。ライト／ダークのエイリアスにより、ハイドレーション前でも静的メディアクエリーでシステムモードを解決できます。

テーマ作成とトークンユーティリティは、Reactに依存しない/themeおよび/tokensエントリーから利用できます。テーマ設定ガイドとSSRガイドも参照してください。

SSRと境界

初回クライアントレンダーにも同じtheme、colorMode、systemModeFallbackを渡すと、サーバーマークアップは決定的になります。useResolvedColorModeとuseMaterial3Themeは別々のコンテキストを使うため、モードだけを使うコンポーネントはテーマ全体の変更を購読しません。

プロバイダーはフレームワークアダプターをインポートしません。Next.js、Vite、ルーター、リンク、画像、フォント、ストレージ、アプリケーション状態は利用側が管理します。