Vivliostyle Themes v3への移行

プリセットの廃止

theme-all.cssとtheme-basic.cssはなくなり、css/common/・css/partial/・css/lib/ディレクトリもなくなりました。パッケージエントリが含むのは基本モジュール、つまりCSSリセット・変数の既定値・基本的なHTMLタグのスタイルだけです。それ以外の機能はすべて、固有のサブパスでインポートするモジュールになりました。

@import url(../theme-base/theme-all.css)のような、themesディレクトリからの相対パスではなく、パッケージ名でインポートしてください。

CSSの場合

/* 変更前 */
@import url(@vivliostyle/theme-base/theme-all.css);

/* 変更後：エントリに続けて、使うモジュールを並べる */
@import '@vivliostyle/theme-base';
@import '@vivliostyle/theme-base/figure';
@import '@vivliostyle/theme-base/table';
@import '@vivliostyle/theme-base/citation';
@import '@vivliostyle/theme-base/endnote';
@import '@vivliostyle/theme-base/footnote';
@import '@vivliostyle/theme-base/page';
@import '@vivliostyle/theme-base/section';
@import '@vivliostyle/theme-base/toc';

上のリストはtheme-all.cssが読み込んでいたものを再現しますが、2点だけ異なります。

• footnote-external-link.cssはtheme-all.cssに含まれていました。外部リンクを脚注にする挙動を残すには@import '@vivliostyle/theme-base/footnote/external-links';を追加してください。
• utility-classes.cssは削除されました。ユーティリティクラスを参照してください。

v3で新しく追加され、対応するマークアップを使うなら追加する価値のあるモジュール：listing・equation・theorem・appendix・math・sidenote。新機能を参照してください。

vivliostyle.config.jsの場合

importオプションも同じサブパスを解決します。import: 'theme-all.css'とimport: 'theme-basic.css'は解決できなくなりました。

// 変更前
export default {
  theme: { specifier: '@vivliostyle/theme-base', import: 'theme-all.css' },
};

// 変更後：エントリはパッケージそのもの、モジュールはそれぞれ別のimportで指定する
export default {
  theme: [
    '@vivliostyle/theme-base',
    { specifier: '@vivliostyle/theme-base', import: 'footnote' },
    { specifier: '@vivliostyle/theme-base', import: 'page' },
  ],
};

Vivliostyle CLI 11.3.0以降はCSSからインポートされたVivliostyle Themeは自動でインストールされるようになったため、@importを並べたカスタムスタイルシートを用意して設定ファイルからそれを指す方が短く済みます。

デザイントークン

文書全体の色とフォントは、役割ベースの8つのトークンになりました。-altトークンは副次的な役割（控えめな文字色・網掛けの背景・薄い罫線・第2のフォント）を表し、既定では主トークンの値を継承するため、何も設定しないテーマの見た目は変わりません。

基本スタイルシートは-altトークンを要素の既定値として使用しません。使う場合は、--vs--figcaption-text-color: var(--vs-color-foreground-alt)のようにテーマ側で要素変数から参照してください。

CSSプロパティから推測可能な名前への改名

色の変数はプロパティ名（colorにはtext-color、background-colorはそのまま）を使います。残りの改名は、適用される論理的な辺を明示するか、綴りの誤りを直すものです。

ページ余白とマージンボックス

ボックスごとの変数は--vs-page--mbox-<box>-<property>の順になり、左右で反転するページのための変数が追加されました。

左右ページで異なる柱に@page :left／@page :rightは不要になりました。--vs-page--mbox-top-outside-content・--vs-page--mbox-bottom-inside-contentなどのinside／outsideと名のつく変数は、ページの左右に応じて左右どちらのボックスかに解決されます。

/* 変更前 */
@page :left {
  --vs-page--mbox-content-top-left: counter(page);
}
@page :right {
  --vs-page--mbox-content-top-right: counter(page);
}

/* 変更後 */
:root {
  --vs-page--mbox-top-outside-content: counter(page);
}

-on-screen／-on-print／-on-hover接尾辞の廃止

メディアや状態ごとに専用の変数を用意する代わりに、メディアクエリの中やホバーされる要素で元の変数を再定義します。

/* 変更前 */
:root {
  --vs--pre-white-space-on-print: pre-wrap;
  --vs-toc--anchor-text-decoration-on-hover: underline;
}

/* 変更後 */
@media print {
  :root {
    --vs--pre-white-space: pre-wrap;
  }
}
@media (hover: hover) {
  :is(#toc, [role='doc-toc']) li > a:hover {
    --vs-toc--anchor-text-decoration: underline;
  }
}

相互参照：種類ごとにモジュールと名前空間を分離

crossref.cssはfigure・table・citationモジュールに分割されました（さらに新規のlisting・equation・theorem・appendixとページ参照が加わります）。--vs-crossref--名前空間は廃止され、種類ごとの変数はそれぞれの名前空間へ、共通の既定値は基本スタイルシートに含まれるルートレベルの変数へ移りました。

/* 変更前 */
@import url(@vivliostyle/theme-base/css/partial/crossref.css);
:root {
  --vs-crossref--counter-style: upper-roman;
  --vs-crossref--marker-fig-content: 'Fig. ' counter(vs-counter-fig) ' ';
  --vs-crossref--marker-display: none;
}

/* 変更後 */
@import '@vivliostyle/theme-base/figure';
@import '@vivliostyle/theme-base/table';
@import '@vivliostyle/theme-base/citation';
:root {
  --vs-counter-style: upper-roman;
  --vs-figure--marker-content: 'Fig. ' counter(vs-counter-fig) ' ';
  --vs-figure--marker-display: none;
  --vs-table--marker-display: none;
  --vs-citation--marker-display: none;
}

リストのインデント

ul／olの最上位はmax(var(--vs--ul-padding-inline-start), var(--vs--ul-minimum-inline-indent-size))で配置されていました。どちらの変数にも既定値がなかったため宣言全体が無効になり、最上位のリストにはインデントが付かず、マーカーが本文ブロックの外にはみ出していました。リストは--vs--lists-padding-inline-start（既定2rem）でインデントされるようになります。以前の表示を保つには0を設定してください。

テーマが書いた規則が効くようになった

• テーマのth, td { border-width: … }はtr:not(:last-child)とth:not(:last-child), td:not(:last-child)に負けていました。これらのセレクタは:where()で包まれました。
• figure > *は置換要素（img・videoなど）以外にはpadding-inlineを受けなくなり、figure内のpre・div・tableの使用サイズが変わらなくなりました。
• b・strong・thは--vs--heading-font-familyにフォールバックしなくなりました。見出し全体のフォントを設定しても、本文の太字や表見出しは変わりません。
• 未設定の--vs-footnote--*プロパティは文書の既定値に固定されず、呼び出し元から継承されます。

名前付きページはhtmlまたはbodyで指定する

文書の役割に対応する名前付きページ（chapter・part・appendix・toc・cover・bibliography・colophonなど）は:is(html, body):is(.<name>, [role='doc-<name>'])で照合されます。文書内部の要素に付けたrole="doc-*"属性では名前付きページが切り替わらなくなったので、クラスかroleをhtmlまたはbodyに付けてください（例：VFMのフロントマター経由）。文書途中の表紙は要素レベルのフック（.cover、section:has(> .cover:first-child)）をそのまま使えます。DPUB-ARIAのrole doc-chapter・doc-partもクラスに加えて章／部のカウンタを進めるようになり、toc／coverの検出はbodyだけでなくhtmlにも一致します。

見出しカウンタは親セクションでリセットされる

vs-counter-sec-h2〜vs-counter-sec-h6は親セクションでリセットされるようになり、各h2配下の最初のh3は1から数えます。カウンタが文書全体を通して進む挙動に依存していたテーマは、独自のカウンタを定義してください。

:root {
  --vs-document-root-counter-reset: non-reset-h2 non-reset-h3;
  --vs-section--h2-marker-content: counter(non-reset-h2);
  --vs-section--h3-marker-content: counter(non-reset-h2) '.' counter(non-reset-h3);
}
section:has(> h2:first-child) {
  counter-increment: vs-counter-sections vs-counter-sec-h2 non-reset-h2;
}
section:has(> h3:first-child) {
  counter-increment: vs-counter-sections vs-counter-sec-h3 non-reset-h3;
}

ホバースタイルはホバーできる環境だけで適用

ホバー時のスタイル（アンカーの下線、目次や注のリンク）は@media (hover: hover)が一致する環境だけで適用され、タッチ専用デバイスでは効かなくなりました。

相互参照の呼び出し

• テーマ独自の種類を含むすべてのa[data-ref]から既定の下線がなくなりました。--vs--crossref-call-text-decoration: underlineで戻せます。
• 引用参照の画面向けプレースホルダ[???]は定義されていたのに参照されておらず、a[data-ref='cite']は画面で何も表示していませんでした。表示されるようになります。
• 既定の--vs-<type>--call-contentは、カウンタ接頭辞のvar()のフォールバックが空だったためVivliostyleでは空として描画されていました。表示されるようになります。

外部リンクは既定では脚注にならない

footnote-external-link.cssはtheme-all.cssに含まれていました。v3ではこのスタイルシートはfootnote/external-linksモジュールとなり、エントリからも公式テーマからもインポートされません。維持するには@import '@vivliostyle/theme-base/footnote/external-links';を追加してください。

ユーティリティクラス

break-before・break-after・break-inside・writing-mode・text-orientation・text-combine-upright・font-variant-numericの値ごとにクラスを提供していたutility-classes.cssは削除されました。代わりに自分の規則でプロパティを宣言してください。

/* 変更前：<h2 class="break-before-page"> */

/* 変更後 */
h2 {
  break-before: page;
}

脚注領域のat-rule

脚注領域はVivliostyle独自の@-adapt-footnote-areaではなく標準の@footnote at-ruleでスタイル付けされます。@-adapt-footnote-areaを対象にしていた独自の規則は@footnoteに書き換えてください。

柱とノンブル

theme-bunko・theme-techbook・theme-gutenbergは柱（ランニングヘッド）とノンブルをtheme-baseのページ変数で設定するようになりました。テーマ固有の変数は削除されています。

theme-baseの変数に置き換えられた変数

テーマ固有の変数のうち、theme-baseの変数で設定可能なものは削除されました。

テーマ固有の変数の改名

テーマ固有の変数名--vs-theme--*は--vs-theme-<name>--*に変更されました。

/* 変更前 */
:root {
  --vs-theme--inline-code-color-bg: #ecf0f1;
}

/* 変更後 */
:root {
  --vs-theme-techbook--inline-code-color-bg: #ecf0f1;
}

その他の変更

• theme-academic・theme-bunko・theme-gutenberg・theme-techbookはtheme-all.cssを読み込んでいたため、外部リンクが脚注になっていました。この挙動はなくなります。戻すにはカスタムスタイルシートにfootnote/external-linksのインポートを追加してください。
• theme-slideはユーティリティクラス（break-before-pageなど）をインポートしなくなりました。ユーティリティクラスを参照してください。
• 公式テーマが公開しているtheme-baseの変数は、上記の改名に従います。