Skip to content

Styling conventions

Each template ships with baseline styles that keep exports consistent across formats, mostly generated by the component configurations. Decide early whether rules live in styles.scss, component customStyles, or both, and document the decision in the template readme.

Using styles

You should use custom styles and a styles.scss as a last resort if none of the component configurations are enough. Custom styles are traditionally more work to maintain over time and across software versions but they may be necessary for custom requirements.

Global stylesheet (styles.scss)

  • Best for: Shared utilities (brand colours, spacing helpers) and rules that apply to every export.
  • Journal example: generic-journal/styles.scss holds a few rules for the title metadata and the Reader header. The loader registers it as the asset-styles asset and inlines it.
  • When to avoid: Long-form monographs where different front/back matter sections require separate tuning.

Loading order

styles.scss is injected first during export. Components can layer additional styles on top, so keep the global sheet minimal and avoid overriding component-specific selectors unless necessary.

Component-level customStyles

  • Best for: Runner-specific tweaks or sections that vary between variants.
  • Journal example: generic-journal adds one rule to Page.spec.customStyles (space after the table of contents on the cover) and one to HtmlPage.spec.customStyles (space after top-level sections). Variants can replace or extend such blocks via JSON patches. The monograph uses no customStyles.
  • HTML-specific: Use HtmlPage.spec.customStyles to introduce responsive rules without affecting PrinceXML.

Tips for maintainers

  1. Tag each customStyles block with a short comment explaining the intent (# Keep the cover table of contents apart from what follows).
  2. When variants add CSS, prefer type: conf patches so you do not change schema defaults.
  3. Keep selectors scoped to data-role or region classes to avoid cross-runner conflicts.

Testing changes

  • Run at least one export per runner (PrinceXML, HTML, EPUB) after touching SCSS or CSS.
  • Validate that InDesign-style features (e.g., page: named pages) still render; PrinceXML is strict about unknown rules.
  • For monographs with multiple header/footer blocks, confirm that typography stays consistent between front, body, and back regions.

Document the testing steps in your PR or change log so other teams can repeat them.