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 defines PDF tweaks and is registered as the asset-styles asset so the loader 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.
  • Monograph example: generic-monograph stores column layouts and blank-page handling inside the Page component so variants can replace or extend them via JSON patches.
  • 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 (# Set up engineering faculty layout).
  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 assets, 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.