Migrating to Vivliostyle Themes v3

The presets are gone

theme-all.css and theme-basic.css no longer exist, and neither do the css/common/, css/partial/ and css/lib/ directories. The package entry carries only the basic modules: the CSS reset, the variable defaults and the styles of basic HTML tags. Every other feature is a module imported by its own subpath.

Import the package by name rather than through a path relative to the themes directory such as @import url(../theme-base/theme-all.css).

In CSS

/* Before */
@import url(@vivliostyle/theme-base/theme-all.css);

/* After: the entry, then the modules you use */
@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';

The list above reproduces what theme-all.css used to load, with two differences:

• footnote-external-link.css was part of theme-all.css. To keep turning external links into footnotes, add @import '@vivliostyle/theme-base/footnote/external-links';.
• utility-classes.css was removed; see utility classes.

New in v3, and worth adding if you use the corresponding markup: listing, equation, theorem, appendix, math, sidenote. See What's new.

In vivliostyle.config.js

The import option resolves the same subpaths. import: 'theme-all.css' and import: 'theme-basic.css' no longer resolve.

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

// After: the entry is the package itself, each module is a separate import
export default {
  theme: [
    '@vivliostyle/theme-base',
    { specifier: '@vivliostyle/theme-base', import: 'footnote' },
    { specifier: '@vivliostyle/theme-base', import: 'page' },
  ],
};

Since Vivliostyle CLI 11.3.0 installs the Vivliostyle Themes imported from CSS automatically, a custom stylesheet with @import rules that the config points at is the shorter option.

Design tokens

The document-wide colors and typefaces are now eight role-based tokens. -alt tokens describe a secondary role (muted text, shaded panels, lighter rules, a second typeface) and default to the primary token, so a theme that sets none of them looks the same as before.

The basic stylesheet does not use the -alt tokens as element defaults. To use them, point the element variables at them in your theme, e.g. --vs--figcaption-text-color: var(--vs-color-foreground-alt).

Names you can infer from the CSS property

Color variables use the property name (text-color for color, background-color), and the remaining renames spell out the logical side they apply to or fix a misspelling.

Page margins and margin boxes

The per-box variables read --vs-page--mbox-<box>-<property>, and variables for pages that mirror between left and right were added.

Running heads that differ between left and right pages no longer need @page :left / @page :right: the variables named inside / outside, such as --vs-page--mbox-top-outside-content and --vs-page--mbox-bottom-inside-content, resolve to the left or right box depending on the page side.

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

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

The -on-screen / -on-print / -on-hover suffixes are gone

Instead of a dedicated variable per medium and state, redefine the base variable inside a media query or on the hovered element.

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

/* After */
@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;
  }
}

Cross-references: one module and namespace per type

crossref.css was split into the figure, table and citation modules (plus the new listing, equation, theorem, appendix and page references). The --vs-crossref-- namespace is gone: per-type variables moved into their own namespaces, and the shared defaults became root-level variables that ship with the basic stylesheet.

/* Before */
@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;
}

/* After */
@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;
}

List indentation

The top level of ul / ol used to be laid out with max(var(--vs--ul-padding-inline-start), var(--vs--ul-minimum-inline-indent-size)). Neither variable had a default, so the declaration was dropped and top-level lists had no indent, with their markers hanging outside the text block. Lists are now indented by --vs--lists-padding-inline-start (default 2rem). Set it to 0 to keep the old rendering.

Rules a theme writes now take effect

• th, td { border-width: … } in a theme was outranked by tr:not(:last-child) and th:not(:last-child), td:not(:last-child). Those selectors are now wrapped in :where().
• figure > * no longer receives padding-inline unless it is a replaced element (img, video, …), so the used size of pre, div and table inside a figure no longer changes.
• b, strong and th no longer fall back to --vs--heading-font-family. Setting one typeface for all headings no longer changes bold body text or table headers.
• Unset --vs-footnote--* properties are inherited from the call site instead of being pinned to the document default.

Named pages are assigned on html or body

Named pages for document roles (chapter, part, appendix, toc, cover, bibliography, colophon, …) are matched with :is(html, body):is(.<name>, [role='doc-<name>']). A role="doc-*" attribute on an element inside the document no longer switches the named page: put the class or the role on html or body (for example through VFM frontmatter). A mid-document cover keeps its element-level hook (.cover, section:has(> .cover:first-child)). The DPUB-ARIA roles doc-chapter and doc-part now drive the chapter / part counters in addition to the classes, and the toc / cover detectors match html as well as body.

Heading counters reset under their parent section

vs-counter-sec-h2 … vs-counter-sec-h6 are now reset by the parent section, so the first h3 under every h2 counts from 1. Themes that relied on the counters running through the whole document must define their own counters:

: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;
}

Hover styles only where hovering exists

Hover styles (anchor underline, table-of-contents and note links) apply only where @media (hover: hover) matches, so they no longer take effect on touch-only devices.

Cross-reference calls

• Every a[data-ref], including theme-defined types, drops the default underline. Restore it with --vs--crossref-call-text-decoration: underline.
• The screen-only placeholder [???] for citation references was defined but never used, so a[data-ref='cite'] rendered nothing on screen. It now renders.
• The default --vs-<type>--call-content values were rendering as empty in Vivliostyle because the counter-prefix var() had an empty fallback. They now render.

External links are no longer footnoted by default

footnote-external-link.css was part of theme-all.css. In v3 the stylesheet is the footnote/external-links module and is not imported by the entry or by any official theme. Add @import '@vivliostyle/theme-base/footnote/external-links'; to keep it.

Utility classes

utility-classes.css, which provided one class per value of break-before, break-after, break-inside, writing-mode, text-orientation, text-combine-upright and font-variant-numeric, was removed. Declare the property in a rule of your own instead:

/* Before: <h2 class="break-before-page"> */

/* After */
h2 {
  break-before: page;
}

The footnote area rule

The footnote area is styled with the standard @footnote at-rule instead of the Vivliostyle-specific @-adapt-footnote-area. Custom rules that targeted @-adapt-footnote-area should use @footnote.

Running heads and page numbers

theme-bunko, theme-techbook and theme-gutenberg configure running heads and page numbers with the page variables of theme-base. Their theme-specific variables are removed:

Variables replaced by the variables of theme-base

Theme-specific variables that can be set with the variables of theme-base are removed.

Renamed theme-specific variables

The theme-specific variables --vs-theme--* are renamed to --vs-theme-<name>--*.

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

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

Other changes

• theme-academic, theme-bunko, theme-gutenberg and theme-techbook loaded theme-all.css, so external links were footnoted. They no longer are; add the footnote/external-links import in a custom stylesheet to restore it.
• theme-slide no longer imports the utility classes (break-before-page and friends). See utility classes.
• The variables of theme-base that the official themes expose follow the renames above.