Theme Root と Attributes
このページは テーマ作成の詳細 の一部で、Theme Root と Theme 固有 Attribute を扱います。
15. Theme Root
Theme CSS は Document 全体へ無条件に適用しません。
基本 Selector は、
:is(:root, .rb-theme-root)
[data-theme-name="<name>"]です。
<name> には Theme の Identity Name が入ります。
組み込み Theme では、たとえば、
riebeckite
minimal
gruvbox
sakura
tokyonight
rerurateがあります。
16. Theme Root が必要な理由
通常の Site では Application が <html> に Theme 名を付けます。
<html data-theme-name="minimal">この場合は :root が Theme Root になります。
一方、Theme Gallery では、
<div
class="rb-theme-root"
data-theme-name="minimal"
>
...
</div>
<div
class="rb-theme-root"
data-theme-name="gruvbox"
>
...
</div>のように、同じ Document 内で複数 Theme を表示できます。
Diagram source
flowchart TD
CSS["同じTheme CSS"]
CSS --> Site["実Site<br/>:root"]
CSS --> PreviewA["Preview<br/>.rb-theme-root"]
CSS --> PreviewB["別Theme Preview<br/>.rb-theme-root"]そのため Theme CSS を裸の、
:root {
/* ... */
}として定義しないでください。
17. Theme Rule の Scope
Color Mode、Typography、Theme Option、Element Rule も同じ Theme Root に閉じ込めます。
/* Light */
:is(:root, .rb-theme-root)
[data-theme-name="<name>"] {
/* ... */
}
/* Dark */
:is(:root, .rb-theme-root)
[data-theme-name="<name>"]
[data-theme="dark"] {
/* ... */
}
/* System */
@media (prefers-color-scheme: dark) {
:is(:root, .rb-theme-root)
[data-theme-name="<name>"]
:not([data-theme]) {
/* ... */
}
}
/* Typography */
:is(:root, .rb-theme-root)
[data-theme-name="<name>"]
[data-typography="serif"] {
/* ... */
}
/* Theme Option */
:is(:root, .rb-theme-root)
[data-theme-name="<name>"]
[data-example-option="on"] {
/* ... */
}
/* Elements */
:is(:root, .rb-theme-root)
[data-theme-name="<name>"]
:focus-visible {
/* ... */
}data-theme-name は Application が出力します。
Preview では .rb-theme-root と同じ Theme Name を指定します。
18. Theme 固有 Attributes
Theme 固有 Option を CSS へ渡したい場合は、安全な data-* Attribute を利用します。
return defineTheme({
name: "newspaper",
attributes: {
"data-newspaper-density":
"compact",
},
});CSS では、
:is(:root, .rb-theme-root)
[data-theme-name="newspaper"]
[data-newspaper-density="compact"] {
/* ... */
}のように利用できます。
Theme API から、
class
style
id
langなどを自由に変更する設計にはしません。
Framework が所有する Attribute と Theme 固有 Attribute を分離してください。
ThemeRoot と themeRootAttributes
Framework は ThemeRoot という UI primitive を提供し、<html> 要素への theme 属性の付与を担当します。
import { ThemeRoot } from "@riebeckite/honox/ui";
<ThemeRoot
theme={config.theme}
lang={c.get("htmlLanguage") ?? config.site.locale}
>
{children}
</ThemeRoot>ThemeRoot は次のように <html> 要素を描画します。
<html
lang="ja"
data-theme-name="minimal"
data-theme="dark"
data-typography="system"
data-article-layout="article"
>Framework は themeRootAttributes(theme) を使って、theme の attributes に加え、以下の予約属性を <html> へ出力します。
data-theme: Color Mode の状態 ("light"/"dark"/ 未設定の場合は削除)data-theme-name: Theme の識別子data-typography: Typography Preset の値data-article-layout: Article Layout Preset の値
独自の <html> 属性を追加したい場合は、ThemeRoot の代わりに themeRootAttributes を直接使えます。
import { themeRootAttributes } from "@riebeckite/honox/ui";
<html
lang={c.get("htmlLanguage") ?? config.site.locale}
{...themeRootAttributes(config.theme)}
data-custom-attr="..."
>
...
</html>ただし、Framework が予約する data-theme, data-theme-name, data-typography, data-article-layout は theme 側の attributes では上書きされません。
Plugin や Theme が独自に themeAttributes() を実装していた場合は、Framework が提供する ThemeRoot / themeRootAttributes() への移行を検討してください。Framework が所有する attribute namespace と Theme 固有の namespace を明確に分離できます。