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 theasset-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 thePage
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
- Tag each
customStyles
block with a short comment explaining the intent (# Set up engineering faculty layout
). - When variants add CSS, prefer
type: conf
patches so you do not change schema defaults. - 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
, andback
regions.
Document the testing steps in your PR or change log so other teams can repeat them.