Best Practices

Best Practices

Rules that have proven themselves in SRL projects. The details are on the linked pages.

Rules

1. Never edit generated files. .srl/, srl/, .srl/imports/*.scss and livingdocs.config.json are regenerated by srl prepare, the Vite plugin and srl build. Change the sources: component folders, ld-conf.json, properties.json, srl.config.json, src/assets/scss/**. See Project Structure#generated-files.
2. Design tokens live in srl.config.json, not as literal values in SCSS. Use srl.typography-<name>(), srl.colors-<name>(), srl.spacer-get(<n>), srl.system-size-unit(<n>) (unitless numbers only) and map.get(srl.$meta, …). Change an existing text style in the config instead of overriding it in SCSS. See Design Tokens.
3. Keep names identical: folder name without prefix = ld-conf.json name = <name>.html = BEM block srl-<name>. Number prefixes only define the order. See Components#naming-and-order.
4. One SCSS file per target in <component>/scss/. general.scss does not reach XBRL; xbrl.scss must @use 'general';. Shared web/editor styles go into web.scss. See Components#scss-per-target.
5. Branch with srl.$system-build (app, editor, pdf, word, xbrl) when one general.scss needs target-specific rules.
6. Never write var(--srl-…) by hand in code that also compiles for Word. Use the token functions or srl.system-root-style().
7. Treat the build output as the source of truth. srl build exits with 0 even on errors. Scan the log and check that the files in .output/ are new. See Build#check-the-result.
8. Raise the design version only when livingdocs.config.json changes in content. Revert pure reorders of that file; commit real changes together with the component change that caused them. See Build#design-version.
9. Nothing but folders directly in livingdocs/. The group mapper deletes plain files there.
10. Restart the dev server or run npx srl map after changing ld-conf.json or component HTML, after adding component folders or target SCSS files, and after srl remove. See Getting Started#develop.
11. Check for updates yourself with npm outdated @simple-reporting/base; the dev server's update notice misses minor and major versions.
12. Build the affected targets after every SCSS or config change. npm run build-pdf is fast; build all targets for token changes.

Example: one component, different output per channel

Example: Multi-Channel Accordion walks through the accordion component: editor-only wrappers, a minimal web skeleton for the Vue component and plain content in PDF, Word and XHTML, all controlled with data-remove-from-<target>.

Checking whether a token or component is unused

Remove a token or component only after you have checked every access path. Search livingdocs/, src/, the PDF scripts and the library's own SCSS and components.

A text style <name> can be used through:

Path	Pattern
Mixin	srl.typography-<name>(
Getter functions	srl.typography-get-font-size('<name>') etc.
CSS variables	var(--srl-typo-<name>-…) in SCSS, Vue, TS or inline styles
Utility class	.srl-typo-<name> in HTML templates, properties.json options, Vue, exported content
SCSS map	map.get(…$typography…, '<name>') or loops over the map
Runtime config	useSrlConfig() (the whole srl.config.json is embedded into the app bundle)

Colors follow the same pattern (srl.colors-<name>(), srl.colors-get('<name>'), --srl-color-<name>, .srl-color-<name>, .srl-bg-<name>), spacers too (srl.spacer-get(<n>), --srl-spacer-<n>, keys in spacer.margins.group).

For components, also search global SCSS (src/assets/scss/*.scss), PDF @page rules (element(…) names), spacer.margins.group and scripts for their classes.

Then verify with the built output:

1. Build all targets before and after the change.
2. Diff the CSS as selector/declaration pairs. Minifiers regroup selectors and app assets have hashed names, so a plain text diff does not help.
3. Only the rules of the removed token may disappear.

In built CSS, a var(--srl-typo-<name>-…) that appears only inside .srl-typo-<name> is the generated utility class, not a real usage.