@k8ordo/color-scheme

トラブルシューティング

よくある症状の原因と直し方です。エラー文で探すときは、ページの中を検索してください。

このページの内容

再読み込みで一瞬出るライト

原因

インラインスクリプトが、最初の描画の前に走っていません。多いのは、CSPがスクリプトを止めている場合と、スクリプトがスタイルシートの後ろにあってその読み込みを待つ場合です。

直し方

コンソールにCSPの違反が出ていれば、次の「CSPで止まるスクリプト」を見てください。出ていなければ、<ColorSchemeScript />をルートレイアウトの<head>に置きます。@k8ordo/frameworkを使っていないときは、送られるHTMLでスクリプトがどのスタイルシートよりも前にあるかを確かめます。

CSPで止まるスクリプト

原因

スクリプトを制限するポリシーが、インラインスクリプトを許可していません。ハッシュで許可している場合は、ColorSchemeScriptと違うdefaultPreferenceやthemeColorで計算したハッシュか、古いバージョンのハッシュを書き写していることがあります。

直し方

nonceで許可するなら、ColorSchemeScriptのnonceにリクエストごとのnonceを渡します(@k8ordo/frameworkのserverモードではnonce())。ハッシュで許可するなら、ColorSchemeScriptと同じdefaultPreferenceとthemeColorをcolorSchemeScriptHash()に渡し、ポリシーを組み立てるたびに計算します。'unsafe-inline'は使いません。ほかのインラインスクリプトまで許可してしまいます。詳しくはCSPを見てください。

A tree hydrated but some attributes of the server rendered HTML didn't match

原因

インラインスクリプトが付けたclass="dark"は、サーバーのHTMLにはありません。開発ビルドのReactは<html>の属性をpropsと比べ、このclassの食い違いを警告します。

直し方

<html>にsuppressHydrationWarningを付けます。止まるのは<html>自身の属性の警告だけです。ページの中の食い違いは、これまでどおり報告されます。ハイドレーションは属性を書き戻さないので、クラスは残ります。

配色に従わないフォーム部品

原因

ブラウザが自分で描く部品の配色は、CSSのcolor-schemeプロパティで決まります。このパッケージはこのプロパティを設定しません。@k8ordo/uiを使っていない場合は、自分で宣言します。color-scheme: light darkと書いている場合は、ブラウザがOSの設定で選ぶので、訪問者の選択とずれます。

直し方

:rootにcolor-scheme: lightを、.darkにcolor-scheme: darkを宣言します。詳しくはdarkクラスのスタイルを見てください。

クラスを読まないTailwind CSSのdark:

原因

Tailwind CSS 4のdark:は、既定ではprefers-color-schemeを読みます。OSの設定には従いますが、訪問者が選んだ配色には従いません。

直し方

スタイルシートで@custom-variant dark (&:where(.dark, .dark *));を宣言します。dark:がクラスを読むようになります。@k8ordo/uiのtailwind.cssを読み込んでいれば、すでに宣言されています。詳しくはdarkクラスのスタイルを見てください。

読み込み直後に反転するアイコン

原因

サーバーは保存した選択を読めないので、既定値で描きます。schemeで出し分けたマークアップは、ハイドレーションが終わるまで既定値の配色のままです。

直し方

両方を描いてdark:で片方を隠すか、use(browser())を<Suspense>の中で呼んでブラウザでだけ描きます。詳しくは切り替えボタンを見てください。

useColorScheme needs <ColorSchemeProvider> above it

原因

useColorScheme()を呼んだコンポーネントの上に、プロバイダがありません。よくあるのは、プロバイダが入れ子のレイアウトにある場合と、テストでwrapperを渡していない場合です。

直し方

プロバイダをルートレイアウトの<body>の中に置き、ページ全体を包みます。テストでは、プロバイダをrenderHookのwrapperに渡します。

OSの設定に従わない配色

原因

OSの設定に従うのは、訪問者が何も選んでいない間だけです。一度ライトかダークを選ぶと、その選択が優先されます。プロバイダのdefaultPreferenceが'system'でない場合も、OSの設定は使われません。

直し方

setPreference('system')を呼ぶと、保存した選択が消えて既定値に戻ります。訪問者が自分で戻せるように、切り替えには「システム」を含む3択を用意します。

localStorageの書き換えを無視する配色

原因

タブの間では、storageイベントで選択を伝えます。このイベントは、書き込んだタブ自身では発火しません。同じタブでlocalStorage.setItemを直接呼んでも、プロバイダは再読み込みまで新しい値を読みません。

直し方

選択はsetPreferenceで変えます。同じオリジンのページを開いているほかのタブにも伝わります。詳しくは設定の保存先を見てください。

Encountered a script tag while rendering React component

原因

テストのようにブラウザだけで描くと、ReactはColorSchemeScriptが描くインラインの<script>を実行しません。開発ビルドのReactは、そのことをコンソールにエラーとして出します。

直し方

テストではColorSchemeScriptを描かず、プロバイダだけをwrapperに渡します。テストで見る<html>のクラスは、プロバイダのeffectが付けています。詳しくはテストを見てください。

k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。