Lolly
افتح التطبيق
  1. أتمت
  2. أنشئ أدوات وأنظمة تصميم

Templates and rendering

template.html is Handlebars markup filled with the current input values. The live canvas, the vector and raster files and the print PDF all start from this template, and sibling templates produce data formats such as calendar files.

The template (template.html)

Templates are Handlebars and logic-less by design, so people who are not programmers can read and change them. Logic goes in hooks.js.

<div class="my-tool">
  {{#if heading}}
    <h1>{{heading}}</h1>
  {{else}}
    <p>(enter a heading)</p>
  {{/if}}

  {{#if logo}}
    <img src="{{asset logo}}" alt="" width="{{asset logo "width"}}">
  {{/if}}
</div>

wordmark is about as small as a template gets: one string, one face, one weight. The picture below comes from the link's parameters in {{ }} slots.

The Wordmark canvas rendering the word Handlebars at weight 800, the whole output of a template whose only moving part is one text value signed by Lollyvector SVG55 paths647 nodes37 groups45 KBCheck it yourselfاحصل على الملف الموقَّع

Helpers. The engine registers these in engine/src/template.ts, the authority on the list:

HelperWhat it does
{{default x "fallback"}}x unless it's null/undefined, then the fallback.
{{upper s}} / {{lower s}}Upper/lower-case a string.
{{eq a b}}Strict equality - use inside a condition, e.g. {{#if (eq kind "note")}}.
{{markdown body}}Render a small Markdown subset to safe HTML: #…###### headings, bold, italic, ~~strike~~, bullet and numbered lists, label links and alt images. Author text is HTML-escaped before any tag is introduced, and link/image URLs are scheme-allowlisted (links: http/https/mailto/tel; images add data:/blob:). Any other URL renders as plain text. Images carry class="md-image" so a tool can size them. A list whose lines start with >, <, ^ or v gets a per-direction class (md-arrow, md-arrow-left, md-arrow-up, md-arrow-down) for matching arrow markers. The output is already safe HTML, so {{markdown body}} and {{{markdown body}}} both work. Used for blocks bodies, table cells and pasted Markdown.
{{arrow text}}A leading > < ^ v becomes → ← ↑ ↓ (for directional labels).
{{asset ref}}The resolved URL of an asset input. Use in src/href.
{{asset ref "width"}}A specific field of the asset (width, height, …).
{{media ref}}Emits the right element for any asset kind - <img>, <video> or a Lottie marker - from one call. Options hash: class, style, loop, autoplay, muted, controls, fit (contain/cover), key and framing (an input id, placed as {{framing}} does).
{{framing "imageFraming"}}Emits the placement style and overlay marker for a framed image. Takes the framing input's id; see Framing an image.
{{icsStamp d}} / {{rfcText s}} / {{csvCell s}}Data-format escaping for the sibling text templates; see Data formats below.

Emoji need nothing from you. The runtime draws every emoji in the rendered text from the emoji set the person chose, as pinned vector artwork, after every paint and again at export. That covers emoji typed into a field, in a blocks body or written into the template as a default. The same link therefore looks the same on a phone, in the CLI and in a PDF. Where no set is chosen, or the set lacks a glyph, a neutral placeholder is drawn, never a system glyph. On a device with no set at all, the characters are left as the template wrote them. A template whose root is an <svg> is skipped whole, because SVG cannot put a picture inside a line of text. The export records one source ingredient in the file's Content Credentials for each distinct glyph it placed, so the set's licence travels with the file.

The web sidebar adds an Insert emoji button to plain text, long text and plain block text fields, and a table column declared with columnEditors: ["emoji"] opens the same picker for its cells. URL, number, read-only and managed fields keep their usual controls. The picker asks for an emoji set on first use, can remember the set for new work and respects a set a document or link already pins.

Canvas tools: readiness, the frame clock and GPU rendering

A template may paint into a <canvas> instead of markup, as 3d, synth, gradient and spatial-photo do. The export reads that canvas back as pixels, so three contracts keep exports correct:

ContractWhat to doWithout it
ReadinessWhen the first frame arrives late (a model or library is loading), set window.__toolHasReadySignal = true at the top of the template script, then dispatch tool:ready on document once the first frame is painted. The shell waits for it before capturing.A slow first frame exports blank.
The frame clockFor animated output (GIF, APNG, animated WebP and frame-by-frame video), store canvas.__lollyFrameRender = function (t) { … } on the canvas element. It renders the exact frame at loop time t in [0, 1); a still calls it with 0, as set out below the table. While the shell drives frames it sets canvas.__lollyFrameDriven = true, so stop your own requestAnimationFrame loop from advancing while the flag is set.The export cannot ask for an exact frame. A function stored on window instead of the canvas leaks across tool navigation.
Real-time videoMark the canvas data-capture-stream, and WebM or MP4 export records it live through captureStream() instead of frame by frame.A self-looping animation is recorded frame by frame instead of as one continuous loop with no cut at the join.

The frame clock also receives two optional arguments: the clip length in seconds and the export's pixel size as { width, height }. A function that declares only t ignores them. During a clip every call carries both, including the extra calls an export makes to find which parts of the frame stay still and the repaint that follows. A template drawn in markup can still carry a clock: give it a 0 by 0 <canvas> that paints nothing, as Growth and Certificate do.

A raster still (PNG, JPEG, WebP, AVIF, JPEG XL, TIFF, BMP and CMYK TIFF, and each size of an icon) calls every clock once with t 0, no clip length and the file's pixel size, after your beforeExport hook has run, and sets __lollyFrameDriven only while it makes that picture.

The other stills read the page as it stands, unless your clock declares a still pose. Set stillPose on the function when t 0 with no clip length draws the finished piece:

canvas.__lollyFrameRender = function (t, clipSec) { /* … */ };
canvas.__lollyFrameRender.stillPose = true;

Certificate declares one, so a print file never catches a moment of its reveal.

Which stills a still pose holds, and which it does not

For a clock with stillPose, an SVG, SVGZ, PDF, CMYK PDF, Penpot, EPS (RGB and CMYK), EMF, WMF, DXF, Word, OpenDocument, PowerPoint, HTML, Markdown or plain-text still does two more things:

  • It poses your tool first. The shell sets the flag and calls the clock once, with t 0 and no size, before anything else in the export runs, including your beforeExport hook. The hook therefore sees the finished pose. A capture outside a tool's export, such as the docs pipeline's page capture, makes the same call before it reads the page.
  • It keeps your tool still until the file is written. The flag stays set while the export reads the page and is cleared afterwards, so your own loop cannot move a part under the export.

Not held, declared or not: clips (GIF, APNG, animated WebP, animated SVG, WebM and MP4, which drive the clock frame by frame), sound, Lottie, IDML, Premiere XML and data files (JSON, CSV, calendar, contact, subtitle, stylesheet and palette files, and Markdown from a template.md). A ZIP or a Linux package holds each file inside under that file's own format. A sequence stage's still is the frame at its playhead, so the shell leaves the stage alone.

CLI, TUI and MCP renders that go through the web shell get the same treatment.

Leave stillPose off when t 0 is not a finished piece. Growth's t 0 is the bare seed, and a flat Lolly Chart's is the first frame of its entrance, which would land over the poster its beforeExport hook poses for SVG, SVGZ and PDF and over the self-animating SVG the hook builds for a chart with a frame column. Without the declaration those stills never call the clock or set the flag, and they read the page as your own loop left the page. Chart's 3-D scenes do declare the pose: at t 0 with no clip length, their clock draws the finished scene, with every bar grown and the camera at its starting angle. A directed cinematic chart (a spotlight tour, a countdown, a pull-back reveal, a gate tunnel or a terrain flight) declares the pose too, and its still is the closing wide shot.

GPU rendering (WebGL, WebGPU). Never let the export path read a GPU canvas directly. A WebGPU canvas is cleared as soon as its frame is presented and has no preserveDrawingBuffer, so a later read is blank. A WebGL canvas survives the read only with preserveDrawingBuffer: true, which costs memory and a copy per frame. Render into a detached scratch canvas instead, and draw that canvas onto the visible 2D canvas inside the same frame callback:

var view = document.getElementById('my-canvas');   // the template's canvas, plain 2D
var ctx = view.getContext('2d');
var gpu = document.createElement('canvas');         // never enters the DOM
gpu.width = view.width; gpu.height = view.height;
// … create the WebGPU or WebGL context on `gpu` and render into it …
function present() { ctx.clearRect(0, 0, view.width, view.height); ctx.drawImage(gpu, 0, 0); }

Call present() at the end of every render, including inside __lollyFrameRender. The visible canvas then always holds the last frame, every export reader sees pixels and the tool can use WebGPU or WebGL 2. The web shell needs WebGPU to start, so WebGL 2 is the fallback for a tool that cannot get a working WebGPU device. 3d does this with three.js's WebGPURenderer({ forceWebGL }), falls back when there is no adapter or the device fails to start, and reports its choice as data-backend on the canvas. Feature-detect with navigator.gpu.requestAdapter(): an adapter that resolves to null means no WebGPU, whatever navigator.gpu says.

Styles (styles.css)

Styles are scoped automatically. Write top-level selectors for your own classes. Rules for body or html are rescoped to #tool-canvas and will probably not do what you want.

Design system colours in templates and styles

The canvas carries the design system's colours as CSS custom properties, so a template or styles.css can use them with no hook. The colours follow the artefact's look (light or dark) and colourway. When the person chooses another colourway or look, every variable below takes the new colour as the tool redraws.

A tool written for any design system reads these seven:

VariableHolds
--brand-primaryThe lead colour of the artefact's colourway
--brand-on-primaryText and icons on the lead colour
--brand-secondaryThe partner colour
--brand-surfaceThe background
--brand-textBody text
--brand-mutedQuieter text
--brand-edgeRules and borders

The rest depend on what the design system holds:

VariableHolds
--brand-lead-1 to --brand-lead-<n>Every colourway's lead in the artefact's look, canonical first
--brand-lead-countHow many lead variables the canvas carries
--brand-<id>A colour role the design system declares, by the role's permanent id, such as --brand-accent
--brand-on-<id>The colour that sits on that role, worked out by Lolly unless the token file states one
--brand-token-<hex>Any colour token, by its path
تحذير: Always give a fallback

Write each variable with a fallback, as in var(--brand-secondary, #444). A role the design system does not define is left unset, and the fallback draws. The brand residue test (tests/brand-residue.test.ts) fails a tool template that reads any of these variables with no fallback.

Which token paints which variable

Both shells paint the variables from the same token reads, in the artefact's look and colourway:

  • Every colour token at color.semantic.<name>, where the name is lowercase letters and hyphens, paints --brand-<name>. That covers the seven slots, each declared colour role and its on-<id> colour, and a color.semantic colour written by hand and never declared as a role. A name with a digit or a capital letter paints no --brand-<name>.
  • Every colour token, whatever its path, also paints --brand-token- followed by the hex of the path's UTF-8 bytes, so color.semantic.accent paints --brand-token-636f6c6f722e73656d616e7469632e616363656e74. The name cannot collide with any other variable. Lolly Design writes a linked colour in this form, with the colour it had as the fallback; a tool rarely needs one.
  • The lead variables come from host.tokens.family().

A colour role's id is permanent. Renaming the role changes only its display name, and --brand-<id> keeps the same name. Ids that would clash with a variable Lolly paints for itself cannot be role ids: on- and token- names, lead-count, warn and warn-ink. A slot a role fills keeps its own variable, so on a design system whose role Main fills the lead colour, --brand-primary and --brand-main hold the same colour.

The lead variables exist only when the design system has two or more colourways, and a canvas carries at most 16 of them. With one colourway there are none. This rule draws a second stripe in the second lead, or in the partner colour when there is no family:

.stripe + .stripe { background: var(--brand-lead-2, var(--brand-secondary, #444)); }

The web shell and the CLI paint the same variables, and the lead variables come from one engine function in both, so a template renders the same in each. A Lolly Design page the CLI draws with no browser reads the variables too: var(--brand-primary, #1e293b) draws the design system's colour, and the fallback draws only when no token has that name. A variable with no fallback and no matching token sends the page to the browser tier (Render with the CLI). Until 2026-11-06 that route drew the fallback on every design system, so a CLI SVG, SVGZ or outlined PDF of a Design template used the template's own colours.

A role's variable exists only on a design system that declares that role, so a tool meant for any design system reads the slots above and leaves a role's name to the person choosing a colour. For a colour input that offers only the colourway leads, see Colourway leads as swatches. A tool whose colours are its content can opt out of colourway switching with tokenAxes (Colours that are the content).

Design system fonts in templates, styles and hooks

A tool sets its text in the design system's fonts, never in a font of its own. The canvas carries the fonts as two CSS custom properties:

VariableHolds
--font-brandThe text font (font.brand)
--font-monoThe mono font for code, data and readouts (font.mono)

A design system that declares no text font or no mono font gets the app's default, SUSE or SUSE Mono. Still give a fallback, as in var(--font-brand, 'SUSE', ui-sans-serif, system-ui, sans-serif) or var(--font-mono, 'SUSE Mono', ui-monospace, monospace), because a copy of the file outside the app has no variables.

Three places cannot read a CSS variable and need the font names instead:

تحذير: Never start a font list with a system font

A list that starts with system-ui, sans-serif or another system font draws the font of the device. An export cannot outline that font, so the page and the file disagree even for Latin text.

What the vector export keeps

The SVG and PDF exporter reads each element's computed style and writes the element again as vector. The CSS you choose decides whether a feature stays geometry, is rasterised into the file or is dropped. A row marked raster still exports correctly, but that element becomes a bitmap inside an otherwise vector file.

You writeIn the SVG / PDF
border (one width and colour all round), border-radius, dashed, dottedKept as a stroke, dash pattern included.
A border that differs per sideIn SVG, one solid colour on a rounded or translucent box is kept as one shape with its corners, and one dashed or dotted colour as dashes along each side. Otherwise, and in PDF, it is kept as flat edges: the radius is lost and a dash is drawn solid.
background-clip: padding-boxThe background colour stays inside the border in SVG.
outlineNot exported. Use border, or box-shadow spread, for a visible ring.
box-shadow (outer and inset), text-shadow, filter: drop-shadow()Kept: native SVG filters, or the shape redrawn; PDF bakes only a blurred shadow.
filter: blur()Kept in SVG. PDF rasterises the element.
opacity, mix-blend-modeKept in SVG. Blend modes rasterise in PDF.
overflow: hidden; clip-path with circle(), ellipse(), inset() or polygon()Kept as a clip. clip-path: url() or path() rasterises.
mask-image, maskRaster.
backdrop-filterA plain blur() is kept in snapshot exports; anything richer rasterises.
TextOutlined to paths with the real font, including -webkit-text-stroke and paint-order. Letters that font lacks come from the later fonts in its font-family stack, as in a browser, then from an on-demand fallback font; the export notice says which fallback font drew them. A line holding a character none of these fonts has stays live <text> in SVG, which then needs a font on the viewer's machine. In PDF that text goes in as a picture from the browser's own text renderer, and the export notice lists its scripts. Right-to-left lines keep the browser's order either way: an outline is shaped in visual order, and a live <text> states direction="rtl" and sits on the line's right edge.
background-imageGradients become real gradients and a single image an <image>; conic-gradient rasterises.
transform2-D transforms are kept. 3-D (rotateY, perspective) is not.

The penpot format keeps the same vector set, as editable Penpot shapes instead of SVG elements. The raster column does not decide which shapes survive. The lowering reads the exported SVG, and one <clipPath>, <filter>, <pattern>, <mask>, <use> or inline <style> anywhere in that SVG puts the whole render on the board as a single picture. On an HTML layout those elements come from a rounded overflow: hidden box whose content reaches a corner, an object-fit: cover or circular image crop, a background-image, a clip-path and a blurred text-shadow. box-shadow does not cause this, because the Penpot render draws shadows as geometry, not as an SVG filter.

Letting the document bring its own CSS

A tool can let the person write a stylesheet, as Lolly Design does with its customCss input. A tool that offers user CSS is expected to follow three safety rules (community/design/hooks.js is the reference; tests/design-custom-css.test.ts is the test to copy):

  1. Sanitise in the hook, never in the shell. The hook neutralises </style and strips @import, then hands back a string the template emits inside <style>. This keeps the CLI's output identical to the browser's. A shell-side filter would leave the headless render unfiltered.
  2. Emit, then let the shell scope. The shell scopes template <style> to the tool canvas (scopeTemplateStyles) and handles top-level @keyframes correctly, so put animations at the document level, not nested per element.
  3. Give the CSS something to aim at. Free-text rules need stable handles: Lolly Design stamps data-frame-id on each artboard, sanitised data-frame-state tokens from a per-frame state field and a per-box cls field whose tokens join the element's class list (.callout { … }). These tokens are parsed and re-serialised like any other free text. They are lowercased, cleaned to [a-z0-9_-] and refused where they would collide with the app's own namespaces (lolly-, pr-, seq-, fc-).
تحذير: Custom JS is not offered, and should not be

Hooks are closure-injected, not sandboxed, so a per-document script input would be stored XSS in every shared URL. The alternative is composition: a sandbox tool link placed as a box.

Data formats (json / csv / ics / vcf)

Some tools export data beside the rendered image: a calendar invite, a contact card, the numbers behind a chart. Data formats come from the input model, not the pixels, so they work in every shell, the CLI included, and need no browser.

One input model feeds template.html for the picture, sibling templates such as template.ics and template.csv for text formats, and the JSON export, which needs no template.One input model feeds template.html for the picture, sibling templates such as template.ics and template.csv for text formats, and the JSON export, which needs no template.Open this in Diagram Builder

Example template.ics (see community/meeting-planner/):

BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
DTSTART:{{icsStamp meetingTime}}
SUMMARY:{{rfcText title}}
LOCATION:{{rfcText city}}
END:VEVENT
END:VCALENDAR

Reference wirings: meeting-planner for ICS, timezone for CSV and captions for SRT and VTT. calendar-ics (ICS) and pricing-table (CSV) in the community folder do the same and are not listed on lolly.tools. No public tool ships a template.vcf yet.

On the node CLI, a template whose root is an <svg> also renders to SVG and the other vector formats with no browser, and resvg draws PNG from that SVG. Vector and raster files from a template built from HTML need a browser engine, and so do JPG, WebP, most PDFs and video: the web shell, the desktop app or the node CLI's browser tier. Render with the CLI has the full list. The CMYK formats pair with the Convert paths toggle (The render block) for print files that need no installed fonts; qr-code offers both pdf-cmyk and cmyk-tiff, while org-chart and logo-wall offer only pdf-cmyk.

Animated HTML

A trusted tool can export a self-contained HTML file with play, replay, seek and fullscreen controls by declaring render.portable: true, listing html in render.formats and shipping presentation.js. That runtime marks its stage with data-lolly-player and assigns element.__lollyPlayback:

stage.__lollyPlayback = {
  duration: 12,          // seconds
  poster: 6,            // initial paused frame
  seek(seconds) { renderFrame(seconds); },
  portableMarkup() { return authoredMarkup; }
};

seek must draw a frame directly, forwards or backwards, without starting another clock. portableMarkup supplies the authored markup with any prepared emoji artwork; leave out transient selection, caret and animation writes. Omit the method when the freshly filled template is enough. animated: false produces a still with no transport controls. Snippet's presentation runtime is a working example.

The shell bundles the shared Sequence evaluator into the player at build time, and the export embeds that code in the HTML, so playback needs no app server. Tools keep their own scene evaluation and do not implement another transport or copy Lolly Design's keyframe maths. The CLI uses its browser render tier for trusted tools that declare portable presentations, as it does for Lolly Design's HTML export.

What people get from an HTML export

Lolly Design and Snippet offer HTML in the export format menu. The file embeds its fonts, images and playback code, and opens paused with play, replay, seek and fullscreen controls; a Lolly Design soundtrack adds mute and volume. Space or K toggles playback, the arrow keys seek, M toggles sound and F toggles fullscreen. Playback works offline.

Lolly Design supports native layers, mixed audio and several timed artboards as scenes. Each scene has its own camera and child animation window, the player offers a scene menu and Page Up and Page Down jump between scenes. Artboards of different sizes fit inside the output size with the same proportions the movie exporter uses. Cuts, fades and bounded custom fades follow the movie transition policy; slide, morph and flight transitions become dissolves for now.

Timeline's Place in order arranges artboards as timed scenes. Dragging a scene in the sequence moves its members' start times and leaves their local keys unchanged. Audio assigned to an artboard stops at that scene's bounds, and an audio layer outside any frame can span the whole film. An untimed deck gets five seconds per page during export without changing the saved document. A still Lolly Design exports without transport controls. Embedded video, Lottie and 3D produce an explicit HTML export error, because their playback adapters are separate work.