<aside> ⚠️ This page is a work-in-progress for Bloom 6.0. Information subject to change.

</aside>

<aside> ℹ️ Please see this page for a more introductory explanation of the Bloom Appearance system:

The Appearance System

</aside>

<aside> ⚠️ This is a very technical note, intended only for Publishers with technical staff.

</aside>

How the Appearance System works

Each Theme is a CSS file that sets the value of one or more Appearance properties.

Each book has an appearance.json file that can contain the same set of properties in JSON form. It also includes a property to indicate the currently selected theme*.*

As you customize settings in the “Book Settings” dialog, Bloom updates that appearance.json. Note that the user interface only shows a small number of available Appearance settings. Instead, most settings are controlled by the theme that you choose.

When Bloom displays a book, it converts that appearance.json and the chosen theme into a CSS file named appearance.css.

The HTML page then applies these stylesheets in this order (last wins, all other things being equal):

  1. basePage.css or basePage-legacy.css
  2. appearance.css
  3. customBookStyles.css, customBookStyles2.css

Precedence

A challenge in modern Bloom is that there are a number of things that each influence the final display of a page. These things may even be wanting opposite things to happen. What happens if the Book Settings Dialog is used to turn something on, but a custom css is used to turn it off? Who wins?

Since ultimately CSS is involved, the answer is complicated by CSS specificity rules. But given the same specificity, here is the order of precedence for the various sources ( >> here means “has precedence over”):

<aside> ℹ️ xmatter HTML >> customBookStyles.css >> xmatter.json >> branding.json (.appearance) >> Book Settings (appearance.json) >> Theme (foobar.css)

</aside>

Why is xMatter pug the ultimate winner? This is because, if an xMatter doesn’t have an HTML element for something, it can’t be CSS’ed or JSON’ed into existence.

Notice that Theme’s position in the list. Not only is it last, but actually any property that appears in Book Settings will win over that described in the Theme, unless CSS specificity rules cause it to overcome the Book Settings.