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.scssholds a few rules for the title metadata and the Reader header. The loader registers it as theasset-stylesasset 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-journaladds one rule toPage.spec.customStyles(space after the table of contents on the cover) and one toHtmlPage.spec.customStyles(space after top-level sections). Variants can replace or extend such blocks via JSON patches. The monograph uses nocustomStyles. - HTML-specific: Use
HtmlPage.spec.customStylesto introduce responsive rules without affecting PrinceXML.
Tips for maintainers
- Tag each
customStylesblock with a short comment explaining the intent (# Keep the cover table of contents apart from what follows). - When variants add CSS, prefer
type: confpatches so you do not change schema defaults. - Keep selectors scoped to
data-roleor 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, andbackregions.
Document the testing steps in your PR or change log so other teams can repeat them.