Libraries
A library holds components, a theme, page templates, images and fonts that reports share. Reports import a library by a version range (library:billing@^1.2), and publishing a report pins the release it used, so a new release changes nothing until a report takes it up. This page is about making and changing libraries in the studio, and taking a library's component, theme or page template into a report.
The Libraries page
Open it from the sidebar's Libraries, Alt+2 or Go to libraries in the command palette from any page, or from the designer's Library tab (Open the libraries). Its address is /libraries/<name>?env=<environment>&tab=<tab>.
The sidebar lists the environment's libraries, each with its latest release and whether it has a draft. A library's page has these tabs, in this order. A library opened without a tab in the address opens on the first, Theme:
- Theme: the default font, chart colours and tokens that reports importing the library with its theme build on, edited with the Theme panel's editors.
- Classes: the theme's classes, each edited as a class (see below).
- Fonts: the font families reports pick from, and the font files reports use as
library:<name>/<path>. Import and declare families, upload font files (they go underfonts/) and remove them (see below). - Images: the images reports use as
library:<name>/<path>. Upload them (they go underimages/) and remove them. - Pages: page sizes, margins, headers, footers and backgrounds that new reports and page templates start from (see Page templates).
- Defaults: the theme's element defaults, the styles every element of a type takes (see below).
- Components: what the library exports. Add, rename, describe and delete components, edit their props, and open one in the component editor (Edit).
- Elements: recipes reports copy in (see below).
- Settings: the locale, currency and formats that reports linking the library with Settings on take (see Document settings).
- Releases: each release with its notes, who released it and when, and its copy in each environment.
- Used by: the reports that use the library, and updating them to a release (see below).
Fonts and Images were one Assets tab until 9 November 2026; an old link to it (&tab=assets) opens Fonts.
With no library picked, the page shows a card for each library with how many reports use it, and the library browser below them.
New library… asks for a name and a description. The name is lower-case letters, digits and hyphens, starting with a letter. It can't be one that any environment already has, because promoting a release would meet the other library. The new library is a draft with no components, whose theme holds the starter defaults.
Linking a library to a report
A report links a library by a version range, and the link brings what the report takes from it. The draft follows the library's new releases in the range: it uses the newest release the range matches, and publishing pins that release, so a published version keeps rendering it until the report is published again or updated.
The designer's Library tab starts with Linked libraries, one card per link. Open it with Manage linked libraries in the command palette; Link a library… goes to the form that adds one.
Each card shows:
- the library, the release its range uses here ("Uses brand 1.4.0"), and the Version range, checked before it is written. When a newer release is out that the range leaves out, the card says so ("2.0.0 is out, outside ^1.2"); widen the range to take it.
- Theme: whether the report takes the library's theme, with how many tokens and classes it has. The theme is the report's starting point: its own tokens, defaults, classes and each element's style override it, property by property. Only one link gives the theme, as the engine uses the first link's: turning Theme on for one link turns it off for the others. Taking it adds the font assets for the families the theme names that the library declares.
- Settings: whether the report takes the library's document settings, its locale, currency and default formats ("en-AU · AUD · 2 formats"; see Document settings). As with the theme, one link at most gives them. Settings are RFML 0.3: the first link that takes them makes the report declare it.
- Components: All of the library's, None, or the ones you Choose. A link that takes the theme and brings all components lists them, since in RFML a theme link without a list brings none; a component a later release adds then needs choosing.
- Images and Fonts: what the library declares. A link always brings its declared images, and its declared font families are offered in the font pickers.
- the components the link brings, each with Make a local copy and Detach (see Copy and detach).
- Open library, Copy the theme in (see below) and Unlink….
In the other panels: the Style tab tags each value that comes from the library, and resets a node's own value to the library's (styling.md). The Theme tab says which library gives the theme ("Theme from brand 1.4.0 (^1.2)", with Manage links), and lists the library's tokens and classes beside the report's: a library token shows its value and Override, which adds the report's own token with that value to change; an overridden one shows the library's value beside the report's and Reset, which removes the report's. The default font says whether it is the library's or replaces it. (The panel's old Builds on field, which set styles.extends, is gone: no host resolves it. A report that still names one sees it there, read-only.)
Link at the end adds a link: the library, its range (^ the latest release to begin with), whether it takes the theme and the settings, and whether it brings all components or none. A link that brings none still brings the library's declared images and fonts.
Unlink… removes the link at once when the report uses nothing it brings. Otherwise it says first what would stop working: the link's components the report uses (and how often), the images only this link declares, and its theme. Make local copies and Copy the theme in keep them as the report's own, and Unlink removes the link. Images and fonts the report names directly from the library's files (library:brand/images/wave.svg in its own assets) stay, drawn from the library's latest release.
Each change is one undo step.
A release while the report is open
A report open in the designer takes up a library's new release as opening it would, without being opened again: when someone releases the library in another browser, or promotes a release into the report's environment. reportd tells each signed-in studio that can read templates in that environment (library-released on GET /v1/events). A studio whose connection dropped, or that was asleep, missed it, so the report reads the libraries again when the connection is back and when its page is shown again.
What happens depends on the link's range:
- A release the range takes (1.3.0 for
^1.2): the report uses it at once. A toast says which library and release, the one before, and the release's notes ("This report now uses brand 1.3.0 (was 1.2.0): Changed token colour.accent"), with Show the link. The document doesn't change, since it names the range, not the release, so there is nothing to undo. Page templates copied from the library follow it too (below): a merge that needs no choice is one undo step per template, with the toast opening the report gives and its Undo. - A release the range leaves out (2.0.0 for
^1.2): nothing changes. A toast says so, "brand 2.0.0 is out, outside ^1.2: this report keeps 1.4.0", with Show the link, whose card says it too; widen the range to take it. A copied page template the release changes says "update page template letterhead from its Inspector", with Select it: the Template section offers Update to 2.0.0…. - A link pinned to one release (
1.2.0): no toast. Its card says that a newer release is out.
Nothing comes in while you are in the middle of something: while a mouse button is held (a drag or a resize), while text is edited on the canvas, within a moment of a key press, while a dialog is open, or while the page is hidden. It comes in once you stop, after what the panels hold is applied, so no edit is lost; unsaved edits stay in the queue and are saved as usual. A read-only report takes a link's new release too, but merges no page template.
A library's own draft doesn't take part: a library links no other library, so its page templates and components follow no one else's releases.
Document settings
A library can give the reports that link it, with Settings on, their locale, currency and default formats (RFML 0.3): the patterns numbers, dates, times and timestamps are shown with when the report gives none, as #,##0.00 or d MMM yyyy. A report's own meta always wins: the library's settings fill in what it leaves out.
On the Libraries page, the Settings tab edits them: Locale and Currency, and the default formats for Numbers, Dates, Times and Dates and times. A preview shows a number, an amount and a date as a report would show them. They are saved to the draft's settings.json, which the manifest names under settings, and ship with the next release: adding them is a minor change, a changed value a patch, removing them a major one. A release checks them as it checks a report's meta: a locale and currency it can read, and patterns Format reads.
In a report, the Output panel's Document settings says which link gives them ("From brand 1.4.0", with Manage links), and lists each one: the library's value with Override, which makes it the report's own to change in the Document section below, or the report's own ("Set here", with the library's value it replaces) with Reset, which removes the report's.
A library's locale makes the report format the same for every reader, as a report's own locale does. A report meant to follow its reader's locale doesn't take settings.
A report can also take its locale or currency from its data or a parameter (Locale and currency). The library's value is then what it falls back to when the data gives none: the card says "From data; falls back to brand's en-AU when it gives none". A library's own settings are always fixed values, since a library has no data or parameters: a release refuses a {{ }} formula there.
The library browser
One browser shows what the libraries offer. It is in the designer's Library tab, under Linked libraries and In this document, and on the Libraries page under the library cards. It lists each released library's latest release, with what the release has:
- Components, each with a thumbnail, its description and its props (a
*marks a required one). - The theme, with its colour tokens as swatches and how many tokens, classes and defaults it has.
- Page templates, once libraries have them.
- Images and fonts, each with the name a report uses for it (
library:brand/images/wave.svg), and a thumbnail for an image.
Each release says how many reports use the library ("used by 12 reports"): the reports whose published version pins one of its releases, or whose draft refers to it. On the Libraries page this opens the Used by tab. Release notes opens the notes of every release, newest first. A library with only a draft isn't listed, as it has nothing to import yet.
Search the library finds the items that have every word you type, in any order. It looks in names, the library's name, descriptions, prop and slot names, the theme's token and class names, and the kind of item: "theme", "page template", "image" and "font" find those. Within a release, items whose name has a word you typed come first. Library to show keeps one library, and Kind of item to show keeps components, themes, page templates, or images and fonts. Show everything clears the search and both filters.
A thumbnail is the component laid out by the engine with placeholders for its props, on a small page of its own, in its release's theme. It doesn't depend on the report that is open. Thumbnails are laid out one at a time as they scroll into view, and each is kept for the rest of the session for that release's contents, so the same release in another environment, or on the other page, isn't laid out again. A component that doesn't lay out says "No preview".
In the Library tab:
- Insert puts the component after the selection, with placeholders for its required props, and imports it at
^<release>in the same undo step (or adds it to the library's import, if the report has one). - Preview lays the component out among the report's own pages and styles, as it would look once imported. Nothing is imported or inserted.
- A component's menu (right-click, or Shift+F10) has Insert, Open (the preview) and Show the release. For a component the report imports already, it also has Make a local copy and Detach (copy and inline) (see Copy and detach).
On the Libraries page, Open takes you to the item's library: a component opens in the component editor, and the theme, an image or a font opens on its tab.
Refresh reads the libraries again. Releasing or promoting from the Libraries page refreshes them too.
Editing a draft
A library has one draft per environment: its working copy. The page shows the draft, or the latest release when there is no draft. Your first change starts a draft from the latest release.
The draft is edited as a document of its own: its components, its theme as the document's styles, and its page templates as the document's. The component editor and the Theme panel change it with the same commands as a report, so Undo and Redo (and Ctrl+Z, Ctrl+Y) work on it. Changes are saved to the draft's files after a short pause, as a report's are, and the page says when everything is saved. Each save is a commit on the environment's branch. When saving fails, leaving the library's page or one of its designers for another page of the studio asks first, as the report's designer does (studio.md): Stay keeps the changes, and Leave and lose them leaves, and a message says they were lost. Another tab of the same library doesn't ask.
A component opened in the component editor is laid out on its own, with preview values for its props, as in a report.
The Code view
Code, in the library's header, opens the draft's files beside the tabs, as JSON: the manifest (library.json), the settings, the theme, and each component, page template and element. They are what the draft saves, so what's shown is what a release holds. The file picker lists them; a settings or theme file the draft doesn't have yet is listed as "(new)", and editing it starts one. Without a file picked, the view follows the tab: the Settings tab shows the settings, the Theme, Defaults and Classes tabs the theme, and the Components, Pages and Elements tabs their first file. The file shown is in the address (&code=<path>).
Each file has the RFML schema of what it holds, so the editor suggests keys and values, describes them, and marks what doesn't fit. Edits go into the draft on Apply or Ctrl+S (Cmd+S on a Mac), and before a release or when the view closes:
- The settings, the theme, a component, a page template or an element are checked by the engine as any edit is, and applied as one undo step. One the engine rejects isn't applied, and the view says why. The draft saves them as it saves the tabs' edits.
- The manifest's own fields, such as the description and the declared fonts, are saved to
library.jsonat once. They aren't part of the draft's undo. Itsassetsare applied as one undo step. - The manifest's
nameis the library's, and can't change. Its lists of files (components,pages,elements,theme,settings) follow the draft: add, rename and remove components, page templates and elements in their tabs.
A change made in a tab while the view is open shows in the text, unless the text holds edits not applied yet; then the view says so, and Discard my edits brings the file back. Discard does the same for your own edits. Without library.write the files can be read but not changed.
Releasing
Release… compares the draft with the latest release and lists what changed. From that, it suggests the next version:
| Change | Version |
|---|---|
| A component, prop, slot, part, report, the theme, one of its classes, a font family or one of its styles, or a file is removed, a page template's slot is removed or renamed, or a prop becomes required (a new required prop too) | Major |
| Anything is added | Minor |
| Anything else (a template, a style, a token's value, a theme default changed or removed, a description, a page template removed, a font family updated from its source) | Patch |
Removing a page template is a patch, since no report imports one: reports have copies of it. The theme's defaults are listed per element type and part ("defaults table::header-cell added"). Removing one is a patch too, since no report names a default; it only changes how reports look. A class renamed (removed, with the same style back under a new name) reads "class a renamed to b", and is major too: reports that name the old one lose its style.
You can change the version. It must be a new major.minor.patch, since releases can't be changed. The notes start as the list of changes, and you can edit them. The engine checks the library before it is released, each page template too, and its errors stop the release.
On the Releases tab, Promote to environment copies a release to the next environment that lacks it. Promoting needs the licence's environments and library.release in the target.
Page templates
A library's page templates are RFML page templates (spec §9.1): a size and orientation, margins, and a header, footer, background and overlay, with variants for first, left, right, last and blank pages. They are starting points. A report gets a copy of the one it starts from, so changing or removing it in the library later changes no report until the report takes the change (below). Nothing imports a page template.
On the Pages tab:
- New page template asks for a name, a size and an orientation, and starts it with 20mm margins. The name is lower-case letters, digits and hyphens, starting with a letter, and it is also the template's id in the reports that copy it.
pageis kept for the page a library's components are laid out on. - Edit opens it in the designer on a stage of three pages, with the template selected, so the Inspector shows it as a report's page templates are shown (pages.md): size, orientation, bleed, margins, footer distance, variants, and the nodes in each band. Rename there renames it in the library. Done goes back to the list.
- Delete removes it from the draft. Reports that copied it keep their copies.
Each change is one undo step of the draft, saved to pages/<name>.json, and the manifest lists the templates under pages. A release checks each page template as a document of its own, with the library's theme and components, so a header that names a class the theme has, or uses one of the library's components, is fine.
A library has no RFML version of its own: its files don't declare one, and the engine checks its components, theme, settings and page templates at the newest version it reads. So a page template, a component or a class may use what a newer RFML version added, such as an overlay or a layer lock (RFML 0.2, canvas-tools.md), and nothing needs upgrading. The designer opens a draft at that version too, so it shows no version errors. A report that copies a page template that uses an overlay, a lock or a page stamp declares RFML 0.2 in the same undo step as the copy.
Classes, tokens, components and declared images a page template uses come from the library. A report that copies the template gets the classes, tokens and components only by importing the library (with its theme, for classes and tokens). An image in the template names one of the library's declared images by asset id (asset: "logo"; see Images, and Picking an image in a library for how it gets there). The copy brings those itself: the report declares each in its own assets as the library's file ("logo": { "kind": "image", "src": "library:stationery/images/logo.svg" }), in the same undo step as the copy, so the image is drawn without a link to the library. Nothing is added when the report already names that file under that id, or links the library (the link brings the id). When the report uses the id for another image and doesn't link the library, the copy's images are renamed (logo-2), so neither image changes. This holds for every copy: the New report wizard, Add as a new template, Use for default, and Update to ….
Slots
A page template can mark where each report that uses it puts its own content: a slot in its header, footer, background or overlay (RFML 0.3, spec §9.1). A letterhead keeps its logo and address, and leaves the reference line to the report. The report's content for a slot is its own, so it stays when the template's new releases come in, and a locked copy keeps its slots open.
- Add one: edit a band (Edit in the Inspector), then in the Insert panel's Page slot group, name the slot and click or drag Slot to where it goes: in the band, or in a box or frame in it, not in a repeated region. The name is lower-case letters, digits and hyphens. In the Inspector, a selected slot's label and description (its
meta) say what it is for, to people and to AI agents. - Its default content is what goes inside the slot in the band's scope: drop a text into the slot's box. Reports show it until they give their own. On the canvas, an empty slot shows as a dashed box with its name.
- The Inspector's Slots section lists the template's slots and their default content.
- A slot name appears once among the bands a page draws, and in bands of one kind: a name in a header and a footer is two slots on one page, and a name in a header and an overlay would be laid out in flow in one and positioned in the other. Either is an error (
schema/duplicate-slot). - A library's page template has no content of its own for its slots: a release refuses one with
slots. Defaults belong in each slot.
Adding a slot is a minor release. Removing or renaming one is major, since reports put content in it: a report that links the library by a range such as ^1.2 doesn't take it up by itself.
Starting from one
- A new report: the Page step of the catalog's New report wizard (new-report.md) lists the page templates of the libraries the environment has released, under each library's name and release, after Plain page. The report's first draft has a copy of the one you pick as its only page template, under its name in the library.
- A report's page templates: From a library… lists them too, in the designer's Pages tab and in the Template section of a selected page in the Inspector. Add as a new template adds a copy after the report's templates (
letterhead, orletterhead-2when the report has one already) and selects it. Use for default puts a copy in place of the selected template, keeping its id, so the sections and page breaks that use it follow. Either is one undo step. The nodes in the copy's bands get ids that the report doesn't use yet.
Drafts aren't offered: a report starts from what a library has released.
Following a library's newer releases
A copy remembers where it came from: the library, the template's name there and the release, in the report's meta.designer.libraryPages (designer state, which engines ignore; RFML §19.1). The new-report wizard records it too. The template's Template section in the Inspector says so ("From stationery 1.0.0 · letterhead · a copy"), and a rename keeps it.
When the library releases a version that changes the template, the section offers Update to 1.1.0…. The update is a three-way merge against the release the copy came from:
- what only the library changed comes in ("Takes 1.1.0"; "Removed in 1.1.0" for something it took out);
- what only the report changed stays ("Keeps yours");
- where both changed it, the dialog asks: Keep yours (the default) or Take 1.1.0.
A band (a header, footer, background or overlay, or a variant's) is compared as a whole, leaving out its nodes' ids, and one taken from the library gets ids the report doesn't use yet. The report's content for the template's slots is always its own, so filling a slot never conflicts. A new release that drops or renames a slot the report has content for is a conflict: opening the report doesn't take it, and the dialog asks Keep my content aside (the default: it stays with the template, not drawn) or Move it to name, a slot the release adds. Update is one undo step, and the template then says it is from the new release. Stop following library forgets where it came from; the template stays as it is.
Opening the report takes such a release by itself when the copy's range takes it (the report's link to the library, else ^ the copy's release) and the merge needs no choice: each template is one undo step, and a toast says "Page template letterhead to stationery 1.1.0: updated from the library", with Undo. One where both changed something isn't merged: a toast says to update it from the page's Inspector. The same happens when the library releases while the report is open (A release while the report is open), once you are idle; and a release the range leaves out then says to update from the Inspector, with Select it.
The presets reportd had before page templates (page sizes, layouts, styles and colours) became library items: the presets library and a style-<id> library per style. operations/migrations.md lists how each one maps.
Elements
An element is a recipe: a set of nodes kept as a preset in a library, such as a box with two grid columns and a 2rem gap holding a field's label and its value. A report that links the library inserts one from its Insert panel as a copy. From then on the copy is the report's own nodes, edited one by one, and a later release of the library doesn't change it. A component is different: a report uses it through one use node that follows the library's releases.
On the Elements tab:
- New element asks for a label (what the Insert panel shows) and a name (lower-case letters, digits and hyphens, starting with a letter, up to 54 of them). It starts as a box with two grid columns and opens in the designer, where its nodes are edited on a canvas as a component's template is, with the Insert panel, the Outline, the Inspector and the Style tab. Done goes back to the tab.
- The card's panel sets the label, the icon the Insert panel shows, and a description. Edit opens the element on its canvas again, Rename gives it another name, and Delete takes it out of the draft. Reports keep the copies they inserted.
- Save as element in a library… on a report's nodes (the Library submenu of their menu, beside Extract a component…, or the command palette) saves a copy of the selected nodes, outermost only, as an element of a library's draft. The classes and images they name stay in the report: give the library the same ones, so a copy looks the same in other reports.
Each change is one undo step of the draft, saved to elements/<name>.json as { "label", "icon"?, "description"?, "nodes" }, and the manifest lists the elements under elements. A release checks each element's nodes as the body of a document of its own, with the library's theme and components, and an error stops the release ("Element field: …"). Adding an element is a minor release; changing or removing one is a patch, since reports keep their copies.
In a report, the Insert panel lists each linked library's elements after the built-in groups, in a group named after the library and its release ("billing · library · 1.3.0"). A library linked for its theme or its images alone lists its elements too. Elements from other libraries, under them, lists the elements of the environment's other libraries at their latest releases ("· not linked"); they are read only when you ask. A click (or Enter) inserts an element after the selection; dragging it onto a page or the outline puts it where it drops, wherever a box could go. Either is one undo step:
- its nodes get ids the report doesn't use yet;
- when the report doesn't take the library's theme, the classes and tokens the nodes use are copied into the report's styles, unless the report has one of that name already;
- when the nodes show one of the library's images, or use one of its components, the report's link to the library brings them: the components join the link, and a report that doesn't link the library gets a link that brings no components (
"components": []), for the images alone.
Defaults
The Defaults tab edits the theme's element defaults (styles.defaults, RFML §8.2): the styles every element of a type takes in the reports that take the library's theme, unless a class, the element's own style or a rule sets them. A report's own defaults win over the library's, property by property. The type picked is in the address (&type=<type>).
The list shows each element type with defaults ("Table", "Report text" for document), the parts each styles and how many properties it sets. Under the list, together at the foot of the column however long the list gets, are both ways of adding: + Add defaults for… picks a type and opens its editor (nothing is written until a property is set), and Add starter defaults (below).
The editor beside the list is the class editor (below) on defaults.<type>: the type itself or one of its parts, the property search, the spacing box, colours from the theme's tokens, and the engine's problems at each field. The parts offered are the type's own (RFML §8.6). The Preview draws the defaults on a sample of that type with no class on it. Over the editor:
- Copy from class… copies a class's properties, its parts' included, into the type's defaults. The class's value replaces the default's where both set a property.
- Save as class… makes a new class from the type's defaults, and links to it in the Classes tab.
- Remove removes the type's defaults, parts and all.
RFML's defaults can't name a class, so both copies stand alone: a later change to the class doesn't reach the defaults, nor the other way round.
A value in a field that isn't a token yet can become one: the field's token button (Make a token from…) asks for a name, adds the token with that value, and puts var(--<name>) in the field, in one undo step. The Classes tab's fields have it too.
Each change is one undo step of the draft (Ctrl+Z, Ctrl+Y, or the tab's Undo and Redo), saved with the theme. A release names each default added, changed or removed (Releasing).
Starter defaults
Add starter defaults fills in what the theme doesn't set yet, property by property, in one undo step, and keeps everything it sets already:
| Type | Starter defaults |
|---|---|
Report text (document) | color: var(--ink), line-height: 1.3 |
| Heading | font-size: 12pt, margin-top: 8pt, margin-bottom: 4pt |
| Rule | border-top: 0.5pt solid var(--line), margin-top: 4pt, margin-bottom: 4pt |
| Table | width: 100%, border-collapse: collapse; ::cell padding: 3pt 4pt and border-bottom: 0.5pt solid var(--line); ::header-cell font-weight: 600 and background-color: var(--table-header-bg); ::footer-cell font-weight: 600 and border-top: 0.75pt solid var(--ink) |
The colours are tokens, added when the theme has none of that name: --ink #1f2933, --line #c9ced6 and --table-header-bg #eef1f4. A brand changes them on the Theme tab. A property counts as set when the theme sets it, a shorthand of it or one of its longhands: a rule with border-top-color keeps it and gets only the margins. A new library starts with all of them.
Classes
A class is a named style that elements take with class (RFML §8.2): a set of properties, and optionally styles for parts of the element that carries it (::header-cell of a table). In a library, classes are part of the theme, so reports that take the library's theme can use them.
The Classes tab lists the library's classes. Each row shows the colours the class sets, how many parts it styles, and how often the library names it. A class with a problem says so. Search classes (or /) finds classes by name, part, property or value: "6b72" finds the class that sets #6b7280. The class picked is in the address (&class=<name>).
- New asks for a name (lower-case letters, digits and hyphens, starting with a letter) and opens the empty class with the cursor in its property picker. Save as class in a component's Style tab still makes one from an element's style.
- Rename (F2) renames the class and every
classlist in the library that names it, in components, page templates and rules, in one undo step. When reports name it, it asks first and lists them: they keep the old name. - Duplicate copies it as
<name>-copyand starts renaming the copy. - Delete… (Delete) removes it at once when nothing names it. Otherwise it asks first and lists where the class is named, in the library and in reports. Those elements keep the name, which then styles nothing. Undo brings the class back.
The editor beside the list edits the class:
- Styles picks the element itself or a part. The parts the class styles come first, with how many properties each sets. + Part… offers every element's parts (table, repeat, matrix, list, table of contents, chart, barcode), the page template's, the parts any element has, and the parts the library's components expose. An element without the part ignores it. A chart part or a list's marker takes only some properties, so the picker lists only those.
- Font is the font picker, with the library's declared families.
- Add a property finds a property by name, label or a word people use for it, as in the Style tab (see Finding a property).
name: valuesets one at once. Every group is offered, since a class can go on any element. Position and Table say which elements they work on. - The properties are grouped as the Style tab groups them, each with + Add. A value is checked as you leave the field or press Enter: one that doesn't fit says why and isn't saved. Esc leaves an edit box as it is, as everywhere in the studio. A colour has a swatch, and the palette button lists the theme's colour tokens with their values. Lengths suggest their keywords and the theme's tokens.
- Margin and padding are one box, as in the Style tab: a side writes its longhand, and Same on all sides the shorthand.
- The engine's problems with a value (an unknown token, a value it can't use) show under its field.
Beside the editor, the Preview draws the class with the engine, in the library's theme (its tokens, defaults and other classes), on sample content, and again a moment after each change. It picks the sample from what the class styles: a table for table parts, a list for a list's, and otherwise a heading and a paragraph, with the same content without the class above them. The menu shows it on text, a box, a table, a list, or one of the library's components that names the class.
Under the editor, In library lists the components and page templates that name the class, and opens each one. In reports lists the reports whose drafts take the library's theme and name the class, with how often, and opens each. A report gets the change, or loses a removed class, when it takes the next release, and a removal or a rename is a major release (see Releasing). The list row says how many reports name each class. Seeing the reports needs template.read.
Each change is one undo step of the draft (Ctrl+Z, Ctrl+Y, or the tab's Undo and Redo), saved with the theme. A class has no rules: conditional styles are rules on an element, and a rule can add a class. Nor does one class build on another. An element can take several (["card", "compact"]), applied in its order.
Images
A library declares the images its components and page templates name by asset id in its manifest's assets, as a report declares its own (RFML §15), with each src a path among the library's files:
"assets": { "logo": { "kind": "image", "src": "images/logo.svg" } }Every import of the library brings its declared assets to the report, so an imported component's { "type": "image", "asset": "logo" } is drawn from the library's file. The report has them among its assets as library references (library:brand/images/logo.svg), drawn from the release the import resolves to. The report's own asset of the same id wins, so a report can replace a library's logo. A release checks that each declared asset is an image or a font at a file the library has; declaring one is a minor change, removing one a major one, and pointing one at another file a patch.
Images uploaded on the Images tab aren't declared until a page template or component uses one (below), or Send to library… declares them. Send to library… declares the images it copies, under the ids the component names them by. Make a local copy and Detach declare the images the copy names in the report (still as the library's files, library:<name>/<path>), so they stay drawn once the import no longer brings the component. The draft editor draws a library's components with its declared images.
A report can also name a library image directly, without a declaration in the library: { "kind": "image", "src": "library:brand/images/wave.svg" } in its own assets.
Picking an image in a library
In a library's page template or component (opened from the Pages or Components tab), the designer's Assets tab lists the library's declared images by asset id, then Other images in library: its other image files, by file name, with a thumbnail of each ("Not declared: using it declares it in stationery"). With an image selected, Use, or dragging one onto the page, declares the file in the library's manifest under an id made from its name (images/mark.svg becomes mark) and points the image at it, in one undo step. Upload images… puts the file under the library's images/ and declares it. Remove on a declared image that nothing uses takes the declaration out (the file stays).
The Inspector's Asset picker lists the same: "Declared in stationery", then "stationery's other images (declares it)". The declaration is saved in library.json with the page template or component, and releasing it is a minor change. A library links no other libraries, so these are the only images offered.
Picking a library's image in a report
The designer's Assets tab lists the report's own images, then a group for each linked library ("From brand 1.4.0", with Manage links), with a thumbnail of each image:
- Declared images, by their asset id. The link brings them, so Use (with an image selected) points the image at the id and adds nothing to the report. Dragging one onto the page inserts an image showing it.
- Other image files of the library, by file name ("Not declared: using it adds it to the report"). Use, or dragging one onto the page, adds it to the report's own assets as the library's file (
{ "kind": "image", "src": "library:stationery/images/mark.svg" }) in the same undo step. - Replace… on a declared image uploads the report's own image under the same id, which wins over the library's ("Replaced in this report"; the report's asset says "Replaces brand's wave"). Use brand's again removes the report's, and the library's shows again.
The Inspector's Asset picker for an image lists the same: the report's images, then each library's declared images ("From brand 1.4.0") and its other images ("brand's other images (adds a reference)"). The asset reference fields list the linked libraries' declared ids after the report's own.
Fonts
A library declares the font families it offers: each family's files, with their weights and styles, the documents that came with it (its licence, readme and notes), and where it came from. Reports that import the library offer its families in their font pickers. Declared families are in the manifest's fonts, and their files under fonts/<family>/ (the family's name in lower case with hyphens: fonts/noto-sans/).
Frontforge Report Server formats numbers, dates and currencies for every CLDR locale at modern coverage, but its bundled fonts draw only the Latin, Greek, Cyrillic, Hebrew and Arabic scripts. A report in Chinese, Japanese, Korean, Hindi, Bengali, Tamil, Thai, Armenian, Georgian or another script needs a font that covers it. Add one here with Add fonts…, for example Noto Sans JP or Noto Sans Devanagari from Google Fonts. Without it, that text is drawn as empty boxes.
Adding fonts
Add fonts… on the Fonts tab imports a family from a font source that is on. Sources are managed in Admin (operations/fonts.md); with none on, the tab says that someone with fonts.sources can turn one on.
- Pick a source, and search its families. Each family's name is drawn in its own font, fetched for the results shown, with its category.
- Pick a family. Its styles show as checkboxes, Regular picked. Select all and Select none above them tick or clear every style listed (for a variable family, every weight it lists), beside a count of those picked; styles the library has already stay ticked. Add needs at least one new style. Below them: its licence, whether the files are static (one per style) or variable (one file covering the weights picked), their size, and the documents that come with it. From Fontsource, one subset is fetched (latin unless you pick another), since the engine reads one file per style. A licence that can't be told, or a font that forbids embedding, is said here, before Add.
- Add fetches the files and documents into the draft and declares the family.
A url source takes a link instead of a search: paste the link to a font file or a zip, and Read the link. reportd reads the family, weights and styles from the fonts themselves; a zip that holds several families lists them to pick one. A single font file's licence can be added by its own link.
A family the library has already, from the same source, is added to: the styles it has are kept (shown as "in the library"), and the new ones fetched. A family the library has from another source, or uploaded by hand, has to be removed first.
Declared families
Each family on the tab shows a line drawn in it, where it came from ("From Google Fonts @ 1a2b3c4", or "Uploaded by hand"), its styles, and its documents, which open as text (HTML as its source, so nothing in it runs). Remove takes the family, its files and its documents out of the draft.
Fonts uploaded by hand are listed under Other fonts until they are declared. Declare as a family… asks for the family's name and each file's weight and style, guessed from its name (BrandSans-BoldItalic.ttf is 700 italic; a variable file is 100 900).
Updates
Check for updates compares each imported family with its source now: GitHub's files at the source's ref, Fontsource's release, the index's version, or a link's ETag or hash. Only when you ask: nothing checks in the background. Each family says it is up to date, newer at the source (with what changed: files, documents, styles), gone from the source, or can't be checked (its source is off or removed).
Update fetches the same styles again into the draft, replacing the family's files and documents: a document the source added comes too, and one it no longer has goes. It ships when the library is released. The release notes say so ("Noto Sans updated from Google Fonts @ 1a2b3c4"), and it is a patch. Reports get the new font when they move to the new release, through Used by and its tests, where a change in the font's metrics would show.
Using a family in a report
In a report that imports the library, the Style panel's Font picker (the selected node's font-family) and the Theme panel's Default font (styles.defaults.document) list the families its libraries declare, by library, then the families the report's own font assets name, then the bundled fonts. Picking a declared family adds the font assets the report needs, one per file ({kind: "font", family, src: "library:<lib>/fonts/…", weight, style}), in the same undo step as the style, so the report renders with the font in every output. Taking a library's theme (the link's Theme switch) or copying it into the report adds them too, for the declared families the theme names.
The studio's canvas lays text out in the report's font assets too: a bundle font from the draft, and a library: font from the release the report's import of that library resolves to (else the latest, as reportd resolves a draft's). Where a font's bytes can't be had, text falls back to the bundled fonts.
In the library's own draft, its declared families need no picking: the draft lays its components, page templates and theme out in them, and its checks know them. A family added on the Fonts tab counts at once. The draft keeps these font assets to itself: they aren't saved in library.json's assets, and a report gets its own when it uses the family.
Sending a report's component to a library
In a report's Library tab, Send to library… on one of the report's own components copies it into a library's draft (also on its menu, and as Then send it to a library when you extract a selection). The components it uses go with it, and so do the images from the report's bundle that it shows, to the same paths in the library, declared in its manifest under the same asset ids. If the draft already has a component with that name, the dialog says so before replacing it. The report keeps its own copy.
Once a release has the component, the report's Library tab offers Use billing's contact-card 1.3.0 instead. That removes the report's copy and imports the release, widening the import's range if it must, in one undo step.
A library's component in a report's component editor is shown, not edited. Edit in the library opens it in the library's draft.
Copy and detach
The other way round from sending a component to a library, a report can take a library's component or theme as its own, when it should stop following the library: to change it for this report only, or to keep it as it is whatever the library releases next. Each of these is one step to undo.
Make a local copy
In the Library tab's Linked libraries, each link lists the components it brings. Make a local copy next to one (or in its right-click menu) copies the component's definition, as the release has it, into the report's own components, under the same name:
- The component's instances stay as they are, and now use the report's copy. The page looks the same.
- The import stops bringing that component. If the import named only that component and doesn't take the library's theme, the import goes. An import that brought all of the library's components names the others instead, so a component the library adds in a later release isn't imported until you add it.
- The copy doesn't shadow anything, so there is no
schema/component-shadowedwarning.
The copy is then edited like any of the report's components: open it on its own, rename it, change its props or inline it. The library's later releases don't change it.
On a use node of an imported component, the inspector's Props section has Make a local copy too.
Detach
Detach makes the local copy, then inlines instances of it: each instance becomes a box with the instance's id, holding the component's nodes with its props filled in.
- On a
usenode's props, Detach (copy and inline) inlines that instance. Other instances use the report's copy. - In the Library tab, Detach (and Detach (copy and inline) in the component's menu) inlines every instance in the report's own nodes.
The copy stays in In this document either way, so instances inside other components' templates keep working. Delete it there once it says "not used".
Copy the theme into this report
A link that takes the library's theme (its Theme switch is on) has Copy the theme in, and Copy the theme into this report in its right-click menu. It adds the theme's tokens, defaults and classes to the report's own styles, and stops taking the theme from the library: the Theme switch goes off, and a link that brought only the theme goes. The pages look as they did, because the report's own styles already win over the theme's:
- Tokens and classes: the theme's are added where the report has none of the same name. A report's token or class replaces the theme's whole, so the theme's is left out.
- Defaults: where only the theme has defaults for a type, they are added. Where both have them, they become one block: the report's declarations, and each of the theme's that the report doesn't override.
There are two cases where one block can't say what the two did, and the designer says so after the copy ("These may look different: …"):
- The theme sets a shorthand, and the report's block sets some of its longhands through another shorthand. For example, the theme's
border-topwith the report'sborder-color: before, the report's colour won on the top edge too. - The theme sets a property in one part and the report sets it in another part of the same type. For example, the theme's
header-cellcolour with the report'scellcolour: before, the report's colour won in header cells, since a later source wins whatever the part.
Check those places on the page, and set the value you want on the report's defaults.
Only the theme in use can be copied: the engine styles a report with the theme of its first import that takes one. If another import also takes its theme, it would be used once this one is copied, so the designer asks you to turn its Theme switch off first.
Commands
The commands are in the command palette (Ctrl+Shift+P), under Library, and in the Library tab's right-click menus where they apply:
| Command | On |
|---|---|
| Make a local copy | A component a link brings |
| Detach (copy and inline) | A component a link brings |
| Copy the theme into this report | A link that takes its theme |
| Manage linked libraries | Anywhere in the designer |
| Link a library… | Anywhere in the designer |
Updating the reports that use a library
The Used by tab lists each report in the environment that uses the library. Reports in the trash are left out.
- Published pins: the release the report's published version pins. Publishing a report records this in its lockfile, so the published version keeps rendering that release.
- Draft range: the range the report's draft imports the library by, with the release that range picks now. The draft's preview uses that release.
To move reports to a release, choose them and a release (the latest is offered first), then press Update to 1.3.0 and republish…. Each report whose published version pins another release is chosen to begin with. A report that isn't published can't be chosen: publish it as usual. Its row says why it can't be chosen, for the release picked:
- "Its draft's link already takes 1.3.0; publishing it pins that."
- "1.3.0 is outside its draft's range ^1.2. Change the link in the report to use it."
- "Its draft's link takes 1.4.0, a later release; publishing it pins that."
- "Its draft's range ^3 matches no release. Change the link in the report."
- "Its draft doesn't use billing."
The update runs as a dry run first. It changes nothing, and shows what would happen to each report:
- Will be republished: its published version moves to the release. If the document's range doesn't include the release (an exact
1.0.0, say), the range widens to^1.3.0, and that is the only change to the document. The tab also says how the draft follows. - Tests fail: won't be republished: the report's tests fail with the release, under
tests.publishGate: block. The failing tests are listed. Underwarnthe report is republished, and the tests that failed are listed. - Conflict: the report has errors with the release, or a library report it embeds keeps another release. Its diagnostics are listed.
- Nothing to update: it has no published version, it pins the release already, or it is frozen by the licence.
Republish publishes the reports that can be republished. Each one is a new published version, "Update billing to 1.3.0", made from the report's published version, not its draft. Its other libraries and data sources keep the versions they pinned. Then the report's draft follows: if its range doesn't include the release, the range moves to ^1.3.0 as one draft edit, recorded in the draft's edit log as a library update. The draft's other unpublished changes stay as they are, unpublished.
Other environments get the update when the reports are promoted, as always. Nothing updates by itself: a new release changes no published report until someone runs an update or republishes it.
Moving a library to the trash
Move to trash… on a library's page takes the library out of every environment at once, with its draft. It can be restored from the trash, so the dialog only says what happens, and the notice after it has an Undo.
While a library is in the trash:
- It isn't listed: not on the Libraries page, in the Library tab's browser, or among the components a report can insert.
- Nothing new can use it. A report that imports it, or uses its reports or images, says the library is in the trash: the Library tab's import shows it, and checking or publishing the draft gives the error
ref/library-in-trash. The draft can't be published until the import goes or the library comes back. - Published reports keep working. A published version renders the releases its lockfile pins, from the trash as before. Promoting such a report still takes its pinned release along.
- Its name stays taken: a new library can't have it until this one is restored or deleted for good.
Restore it from the catalog's Trash view, or the administration site's Trash page: the library comes back in every environment, draft and all.
Delete forever (trash.purge) is refused while a published report in any environment still pins one of the library's releases. The Trash view lists those reports, with the environment and the release each one pins. Update them to another library, or make local copies of what they use, and publish them; then delete it. Empty trash keeps such a library too, and the trash's sweep never deletes one, however long it has been there. Deleting it for good removes its releases from every environment branch; git history still holds them. See operations/trash.md.
Permissions
| To | You need |
|---|---|
| See libraries | template.read |
| Create a library, change its draft, send a component to it | library.write |
| Release and promote | library.release (in the target environment, to promote) |
| Import, declare, update or remove font families | library.write, and the source on |
| Turn font sources on and declare them | fonts.sources (never agents) |
| Update the reports that use a library | template.publish (agents only under agents.publish: allow) |
| Move a library to the trash, or restore it | library.write in every environment |
| Delete a library for good | trash.purge |
What you can't do is hidden, or says why.
Where libraries are kept
reportd keeps libraries on each environment's branch: the draft at libraries/<name>/draft/, and each release at libraries/<name>/<version>/, with its notes in the release's library.json. Moving a library to the trash removes its draft from each branch and adds libraries/<name>/trashed/item.json; its releases stay, so published reports keep rendering them.
The routes are in the API reference (libraries, fonts):
| Route | Does |
|---|---|
POST /v1/libraries | Creates a library, as an empty draft |
PUT and DELETE /v1/libraries/{name}/draft/files/{path} | Write the draft's files |
GET /v1/libraries/{name}/changes | Compares the draft with a release and suggests the version |
POST /v1/libraries/{name}/release | Releases the draft, with its notes |
GET /v1/libraries/{name}/releases | Each release, with the commit that wrote it and its status in each environment |
GET /v1/libraries/{name}/dependents | The reports that use the library: published pins and drafts' references |
POST /v1/libraries/{name}/update | {environment, version, templates, dryRun}: republishes each report's published version with the library's pins moved, through the publish tests gate, then moves the draft's range. Each report updated is audited as library.update |
DELETE /v1/libraries/{name} | Moves the library to the trash |